From 6f0918a5306b6a91d417994a68cc504ff7e22e2d Mon Sep 17 00:00:00 2001 From: Greirson Lee-Thorp Date: Tue, 4 Feb 2025 21:15:21 -0800 Subject: [PATCH] docs/test: Add dev setup and update docs (#23) * feat: Add development environment configuration - Create dev/dev.sh script for simplified development workflow - Add docker-compose.dev.yml for local development setup - Update .gitignore to exclude dev directory except specific files - Add development section to README.md with guide reference * docs: Update README and docker-compose with comprehensive setup instructions and configuration options --- .gitignore | 8 +- README.md | 180 ++++++++++++++++++------------------- dev/README.md | 70 +++++++++++++++ dev/dev.sh | 37 ++++++++ dev/docker-compose.dev.yml | 25 ++++++ docker-compose.yml | 18 ++-- 6 files changed, 234 insertions(+), 104 deletions(-) create mode 100644 dev/README.md create mode 100755 dev/dev.sh create mode 100644 dev/docker-compose.dev.yml diff --git a/.gitignore b/.gitignore index 4d99b93..781c82b 100644 --- a/.gitignore +++ b/.gitignore @@ -144,4 +144,10 @@ convert-icon.js # OS .DS_Store -Thumbs.db \ No newline at end of file +Thumbs.db + +# Development +dev/* +!dev/docker-compose.dev.yml +!dev/dev.sh +!dev/README.md \ No newline at end of file diff --git a/README.md b/README.md index 36026f8..a6d6eee 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,77 @@ A stupid simple file upload application that provides a clean, modern interface ![image](https://github.com/user-attachments/assets/2e39d8ef-b250-4689-9553-a580f11c06a7) - No auth (unless you want it now!), no storage, no nothing. Just a simple file uploader to drop dumb files into a dumb folder. +## Quick Start + +### Option 1: Docker (For Dummies) +```bash +# Pull and run with one command +docker run -p 3000:3000 -v ./local_uploads:/app/uploads dumbwareio/dumbdrop:latest +``` +1. Go to http://localhost:3000 +2. Upload a File - It'll show up in ./local_uploads +3. Celebrate on how dumb easy this was + +### Option 2: Docker Compose (For Dummies who like customizing) +Create a `docker-compose.yml` file: +```yaml +services: + dumbdrop: + image: dumbwareio/dumbdrop:latest + ports: + - 3000:3000 + volumes: + # Where your uploaded files will land + - ./local_uploads:/app/uploads + environment: + # The title shown in the web interface + DUMBDROP_TITLE: DumbDrop + # Maximum file size in MB + MAX_FILE_SIZE: 1024 + # Optional PIN protection (leave empty to disable) + DUMBDROP_PIN: 123456 + # Upload without clicking button + AUTO_UPLOAD: false +``` + +Then run: +```bash +docker compose up -d +``` + +1. Go to http://localhost:3000 +2. Upload a File - It'll show up in ./local_uploads +3. Rejoice in the glory of your dumb uploads + +### Option 3: Running Locally (For Developers) + +> If you're a developer, check out our [Dev Guide](#development) for the dumb setup. + +1. Install dependencies: +```bash +npm install +``` + +2. Set environment variables in `.env`: +```env +PORT=3000 # Port to run the server on +MAX_FILE_SIZE=1024 # Maximum file size in MB +DUMBDROP_PIN=123456 # Optional PIN protection +``` + +3. Start the server: +```bash +npm start +``` + +#### Windows Users +If you're using Windows PowerShell with Docker, use this format for paths: +```bash +docker run -p 3000:3000 -v "${PWD}\local_uploads:/app/uploads" dumbwareio/dumbdrop:latest +``` + ## Features - Drag and drop file uploads @@ -19,9 +87,10 @@ No auth (unless you want it now!), no storage, no nothing. Just a simple file up - Drag and Drop Directory Support (Maintains file structure in upload) - Optional PIN protection (4-10 digits) with secure validation - Configurable notifications via Apprise -- Custom notification messages with filename templating -## Environment Variables +## Configuration + +### Environment Variables | Variable | Description | Default | Required | |------------------|---------------------------------------|---------|----------| @@ -35,14 +104,16 @@ No auth (unless you want it now!), no storage, no nothing. Just a simple file up | AUTO_UPLOAD | Enable automatic upload on file selection | false | No | | ALLOWED_EXTENSIONS| Comma-separated list of allowed file extensions | None | No | -## File Extension Filtering +### File Extension Filtering To restrict which file types can be uploaded, set the `ALLOWED_EXTENSIONS` environment variable. For example: ```env ALLOWED_EXTENSIONS=.jpg,.jpeg,.png,.pdf,.doc,.docx,.txt ``` If not set, all file extensions will be allowed. -## Notification Templates +### Notification Setup + +#### Message Templates The notification message supports the following placeholders: - `{filename}`: Name of the uploaded file - `{size}`: Size of the file (formatted according to APPRISE_SIZE_UNIT) @@ -59,6 +130,12 @@ Size formatting examples: Both {size} and {storage} use the same formatting rules based on APPRISE_SIZE_UNIT. +#### Notification Support +- Integration with [Apprise](https://github.com/caronc/apprise?tab=readme-ov-file#supported-notifications) for flexible notifications +- Support for all Apprise notification services +- Customizable notification messages with filename templating +- Optional - disabled if no APPRISE_URL is set + ## Security Features - Variable-length PIN support (4-10 digits) @@ -69,94 +146,9 @@ Both {size} and {storage} use the same formatting rules based on APPRISE_SIZE_UN - Rate Limiting to prevent brute force attacks - Optional file extension filtering -## Notification Support -- Integration with [Apprise](https://github.com/caronc/apprise?tab=readme-ov-file#supported-notifications) for flexible notifications -- Support for all Apprise notification services -- Customizable notification messages with filename templating -- Optional - disabled if no APPRISE_URL is set - -# Future Features -- Camera Upload for Mobile -- Enhanced Progress Features (upload speed display, time remaining estimation) - - -## Quick Start - -### Running Locally - -1. Install dependencies: -```bash -npm install -``` - -2. Set environment variables in `.env`: -```env -PORT=3000 # Port to run the server on -MAX_FILE_SIZE=1024 # Maximum file size in MB (default: 1024 MB / 1 GB) -DUMBDROP_PIN=123456 # Optional PIN protection (4-10 digits, leave empty to disable) -``` - -3. Start the server: -```bash -npm start -``` - -### Running with Docker +## Development -#### Pull from Docker Hub -```bash -# Pull the image -docker pull dumbwareio/dumbdrop:latest - -# Run the container -# For Linux/Mac: -docker run -p 3000:3000 -v $(pwd)/local_uploads:/app/uploads -e DUMBDROP_PIN=123456 dumbwareio/dumbdrop:latest - -# For Windows PowerShell: -docker run -p 3000:3000 -v "${PWD}\local_uploads:/app/uploads" -e DUMBDROP_PIN=123456 dumbwareio/dumbdrop:latest -``` - -# Docker Compose -```yml -name: Dumb Drop -services: - dumbdrop: - ports: - - 3000:3000 - volumes: - - $(pwd)/local_uploads:/app/uploads - environment: - - DUMBDROP_PIN=123456 - # - APPRISE_URL= # i.e. tgram://bottoken/ChatID - # - APPRISE_MESSAGE= - image: dumbwareio/dumbdrop:latest -``` - -#### Build Locally -1. Build the Docker image: -```bash -docker build -t dumbdrop . -``` - -2. Run the container: -```bash -# For Linux/Mac: -docker run -p 3000:3000 -v $(pwd)/local_uploads:/app/uploads -e DUMBDROP_PIN=123456 dumbdrop - -# For Windows PowerShell: -docker run -p 3000:3000 -v "${PWD}\local_uploads:/app/uploads" -e DUMBDROP_PIN=123456 dumbdrop -``` - -## Usage - -1. Open your browser and navigate to `http://localhost:3000` (unless another domain has been setup) -2. If PIN protection is enabled, enter the 4-10 digit PIN -3. Drag and drop files into the upload area or click "Browse Files" -4. Select one or multiple files -5. Click "Upload Files" -6. Files will be saved to: - - Local development: `./uploads` directory - - Docker/Unraid: The directory you mapped to `/app/uploads` in the container +Want to contribute or develop locally? Check out our [Development Guide](dev/README.md) - it's stupid simple, just the way we like it! If you're writing complex code to solve a simple problem, you're probably doing it wrong. Keep it dumb, keep it simple. ## Technical Details @@ -165,3 +157,7 @@ docker run -p 3000:3000 -v "${PWD}\local_uploads:/app/uploads" -e DUMBDROP_PIN=1 - File handling: Chunked file uploads with configurable size limits - Security: Optional PIN protection for uploads - Containerization: Docker with automated builds via GitHub Actions + +## Future Features +- Camera Upload for Mobile +> Got an idea? [Open an issue](https://github.com/dumbwareio/dumbdrop/issues) or [submit a PR](https://github.com/dumbwareio/dumbdrop/pulls) diff --git a/dev/README.md b/dev/README.md new file mode 100644 index 0000000..5a42cd2 --- /dev/null +++ b/dev/README.md @@ -0,0 +1,70 @@ +# DumbDrop Development + +Because we're too dumb for complexity, development is super simple! + +## Quick Start + +1. Clone this repo +2. Navigate to the `dev` directory +3. Use our dumb-simple development script: + +```bash +# Start development environment +./dev.sh up + +# Stop development environment +./dev.sh down + +# View logs +./dev.sh logs + +# Rebuild without cache +./dev.sh rebuild + +# Clean everything up +./dev.sh clean +``` + +## Development Environment Features + +Our development setup is sophisticatedly simple: + +- Builds from local Dockerfile instead of pulling image +- Mounts local directory for live code changes +- Uses development-specific settings +- Adds helpful labels for container identification +- Hot-reloading for faster development + +## Development-specific Settings + +The `docker-compose.dev.yml` includes: +- Local volume mounts for live code updates +- Development-specific environment variables +- Container labels for easy identification +- Automatic container restart for development + +### Node Modules Handling + +Our volume setup uses a technique called "volume masking" for handling node_modules: +```yaml +volumes: + - ../:/app # Mount local code + - /app/node_modules # Mask node_modules directory +``` + +This setup: +- Prevents local node_modules from interfering with container modules +- Preserves container's node_modules installed during build +- Avoids platform-specific module issues +- Keeps development simple and consistent across environments + +## Directory Structure + +``` +dev/ +├── README.md # You are here! +├── docker-compose.dev.yml # Development-specific Docker setup +└── dev.sh # Simple development helper script +``` + +That's it! We told you it was dumb simple! If you need more complexity, you're probably in the wrong place! diff --git a/dev/dev.sh b/dev/dev.sh new file mode 100755 index 0000000..4b3ca40 --- /dev/null +++ b/dev/dev.sh @@ -0,0 +1,37 @@ +#!/bin/bash + +# Simple development helper script because we're too dumb for complexity + +case "$1" in + "up") + echo "🚀 Starting DumbDrop in development mode..." + docker compose -f docker-compose.dev.yml up --build + ;; + "down") + echo "👋 Stopping DumbDrop development environment..." + docker compose -f docker-compose.dev.yml down + ;; + "logs") + echo "📝 Showing DumbDrop logs..." + docker compose -f docker-compose.dev.yml logs -f + ;; + "rebuild") + echo "🔨 Rebuilding DumbDrop..." + docker compose -f docker-compose.dev.yml build --no-cache + ;; + "clean") + echo "🧹 Cleaning up development environment..." + docker compose -f docker-compose.dev.yml down -v + ;; + *) + echo "DumbDrop Development Helper" + echo "Usage: ./dev.sh [command]" + echo "" + echo "Commands:" + echo " up - Start development environment" + echo " down - Stop development environment" + echo " logs - Show container logs" + echo " rebuild - Rebuild container without cache" + echo " clean - Clean up everything" + ;; +esac \ No newline at end of file diff --git a/dev/docker-compose.dev.yml b/dev/docker-compose.dev.yml new file mode 100644 index 0000000..b1d5cb3 --- /dev/null +++ b/dev/docker-compose.dev.yml @@ -0,0 +1,25 @@ +version: '3.8' + +services: + dumbdrop: + build: + context: .. + dockerfile: Dockerfile + ports: + - "3000:3000" + volumes: + - ../:/app + - /app/node_modules + - ../local_uploads:/app/uploads + environment: + NODE_ENV: development + DUMBDROP_TITLE: DumbDrop-Dev + MAX_FILE_SIZE: 1024 + DUMBDROP_PIN: 123456 + APPRISE_MESSAGE: "[DEV] New file uploaded - {filename} ({size}), Storage used {storage}" + APPRISE_SIZE_UNIT: auto + # Enable container restart during development + restart: unless-stopped + # Add development labels + labels: + - "dev.dumbware.environment=development" \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index bc4bbed..e177974 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,17 +1,13 @@ services: dumbdrop: + image: dumbwareio/dumbdrop:latest ports: - 3000:3000 volumes: - - ./local_uploads:/app/uploads + # Replace "./local_uploads" ( before the colon ) with the path where the files land + - ./local_uploads:/app/uploads environment: - DUMBDROP_TITLE: DumbDrop - MAX_FILE_SIZE: 1024 - DUMBDROP_PIN: 123456 - # APPRISE_URL: ntfys:// - # APPRISE_MESSAGE: New file uploaded - {filename} ({size}), Storage used {storage} - # AUTO_UPLOAD: false - APPRISE_MESSAGE: New file uploaded - {filename} ({size}), Storage used {storage} - APPRISE_SIZE_UNIT: auto - image: dumbwareio/dumbdrop:latest - # build: . \ No newline at end of file + DUMBDROP_TITLE: DumbDrop # Replace "DumbDrop" with the title you want to display + MAX_FILE_SIZE: 1024 # Replace "1024" with the maximum file size you want to allow in MB + DUMBDROP_PIN: 123456 # Replace "123456" with the pin you want to use + AUTO_UPLOAD: false # Set to true if you want dont want to have to click the upload button \ No newline at end of file