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
DumbWareio · Feb 5, 2025 · 6f0918a · 6f0918a
1 parent beb03e2
commit 6f0918a
Show file tree

Hide file tree

Showing 6 changed files with 234 additions and 104 deletions.
diff --git a/.gitignore b/.gitignore
@@ -144,4 +144,10 @@ convert-icon.js
 
 # OS
 .DS_Store
-Thumbs.db
+Thumbs.db
+
+# Development
+dev/*
+!dev/docker-compose.dev.yml
+!dev/dev.sh
+!dev/README.md
diff --git 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
@@ -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
@@ -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 
diff --git a/dev/docker-compose.dev.yml 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"