Files

Tanner Collin 4cc360c3ca docs: Update README for local file saving and Telegram notifications

Co-authored-by: aider (gemini/gemini-2.5-pro) <aider@aider.chat>

2026-01-22 11:43:43 -07:00

7.8 KiB

Raw Blame History

File Drop Uploader

A tiny web app for collecting photos/videos and saving them to the local filesystem. Admin users log in to create public invite links; invite links are always public-by-URL. A public uploader page is optional and disabled by default.

Features

Local Saving: All uploaded files are saved to the local filesystem.
Invite Links: Create public-by-URL links for uploads; one-time or multi-use.
Manage Links: Search/sort, enable/disable, delete, edit name/expiry.
Passwords (optional): Protect invites with a password gate.
Albums: Upload into a specific folder (auto-create supported). Preserves client-side folder structure on upload.
Duplicate Prevention: Local SHA‑1 cache prevents re-uploading the same file.
Telegram Notifications: Get notified via Telegram when upload batches are complete.
Progress Queue: WebSocket updates; see upload progress in real-time.
Chunked Uploads (optional): Large-file support with configurable chunk size.
Mobile + Dark Mode: Responsive UI, safe-area padding, persistent theme.

Quick start
New Features
Chunked Uploads
Architecture
Folder structure
Requirements
Configuration (.env)
How it works
Mobile notes
Troubleshooting
Security notes
Development
License

Quick start

You can run without a .env file by putting all settings in docker-compose.yml (recommended for deploys). Use a .env file only for local development.

docker-compose.yml (deploy without .env)

version: "3.9"

services:
  immich-drop:
    image: ghcr.io/nasogaa/immich-drop:latest
    pull_policy: always
    container_name: immich-drop
    restart: unless-stopped

    # Configure all settings here (no .env required)
    environment:

      # Optional behavior
      PUBLIC_UPLOAD_PAGE_ENABLED: "false"   # keep disabled by default
      PUBLIC_BASE_URL: https://drop.example.com

      # Telegram Bot for notifications (optional)
      #TELEGRAM_BOT_API_KEY: "YOUR_BOT_API_KEY"
      #TELEGRAM_BOT_OWNER_ID: "YOUR_TELEGRAM_USER_ID"

      # Large files: chunked uploads (bypass 100MB proxy limits)
      CHUNKED_UPLOADS_ENABLED: "false"      # enable chunked uploads
      CHUNK_SIZE_MB: "95"                  # per-chunk size (MB)

      # App internals
      SESSION_SECRET: ${SESSION_SECRET}

    # Expose the app on the host
    ports:
      - 8080:8080

    # Persist local dedupe cache (state.db) across restarts
    volumes:
      - immich_drop_data:/data

    # Simple healthcheck
    healthcheck:
      test: ["CMD-SHELL", "python - <<'PY'\nimport os,urllib.request,sys; url=f\"http://127.0.0.1:{os.getenv('PORT','8080')}/\";\ntry: urllib.request.urlopen(url, timeout=3); sys.exit(0)\nexcept Exception: sys.exit(1)\nPY"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  immich_drop_data:

### CLI
```bash
docker compose pull
docker compose up -d

Chunked Uploads

Enable chunked uploads by setting CHUNKED_UPLOADS_ENABLED=true.
Configure chunk size with CHUNK_SIZE_MB (default: 95). The client only uses chunked mode for files larger than this.
Intended to bypass upstream proxy limits (e.g., 100MB) while preserving duplicate checks, EXIF timestamps, album add, and per‑item progress via WebSocket.

Architecture

Frontend: static HTML/JS (Tailwind). Drag & drop or "Choose files", queue UI with progress and status chips.
Backend: FastAPI + Uvicorn.
- Saves uploaded files to the local filesystem.
- Computes SHA‑1 and checks a local SQLite cache (state.db) to prevent duplicates.
- WebSocket /ws pushes per‑item progress to the current browser session only.
Persistence: A local SQLite database (state.db) prevents re‑uploads across sessions. Uploaded files are stored in /data/uploads.

Folder structure

immich_drop/
├─ app/                     # FastAPI application (Python package)
│  ├─ app.py                # ASGI app (uvicorn entry: app.app:app)
│  └─ config.py             # Settings loader (reads .env/env)
├─ frontend/                # Static UI (served at /static)
│  ├─ index.html            # Public uploader (optional)
│  ├─ login.html            # Login page (admin)
│  ├─ menu.html             # Admin menu (create invites)
│  ├─ invite.html           # Public invite upload page
│  ├─ app.js                # Uploader logic (drop/queue/upload/ws)
│  ├─ header.js             # Shared header (theme + ping + banner)
│  └─ favicon.png           # Tab icon (optional)
├─ data/                    # Local dev data dir (bind to /data in Docker)
├─ main.py                  # Thin dev entrypoint (python main.py)
├─ requirements.txt         # Python dependencies
├─ Dockerfile
├─ docker-compose.yml
├─ .env.example             # Example dev environment (optional)
├─ README.md
└─ screenshot.png           # UI screenshot for README

Requirements

Python 3.11

Local dev quickstart

Development

Run with live reload:

python main.py

The backend contains docstrings so you can generate docs later if desired.

Dev Configuration (.env)

# Server (dev only)
HOST=0.0.0.0
PORT=8080

# Public uploader page (optional) — disabled by default
PUBLIC_UPLOAD_PAGE_ENABLED=TRUE

# Local dedupe cache (SQLite)
STATE_DB=./data/state.db

# Telegram Bot for notifications (optional)
#TELEGRAM_BOT_API_KEY=
#TELEGRAM_BOT_OWNER_ID=

# Base URL for generating absolute invite links (recommended for production)
# e.g., PUBLIC_BASE_URL=https://photos.example.com
#PUBLIC_BASE_URL=

# Session and security
SESSION_SECRET=SET-A-STRONG-RANDOM-VALUE
LOG_LEVEL=DEBUG

# Chunked uploads (optional)
CHUNKED_UPLOADS_ENABLED=true
CHUNK_SIZE_MB=95

You can keep a checked‑in /.env.example with the keys above for onboarding.

How it works

Queue – Files selected in the browser are queued; each gets a client‑side ID.
De‑dupe (local) – Server computes SHA‑1 and checks state.db. If seen, marks as duplicate.
De‑dupe (server) – Attempts Immich /assets/bulk-upload-check; if Immich reports duplicate, marks accordingly.
Upload – Multipart POST to ${IMMICH_BASE_URL}/assets with:
- assetData, deviceAssetId, deviceId,
- fileCreatedAt, fileModifiedAt (from EXIF when available; else lastModified),
- isFavorite=false, filename, and header x-immich-checksum.
Album – If IMMICH_ALBUM_NAME is configured, adds the uploaded asset to the album (creates album if it doesn't exist).
Progress – Backend streams progress via WebSocket to the same session.
Privacy – UI shows only the current session's items. It never lists server media.

Security notes

The menu and invite creation are behind login. Logout clears the session.
Invite links are public by URL; share only with intended recipients.
The default uploader page at / is disabled unless PUBLIC_UPLOAD_PAGE_ENABLED=true.
The Immich API key remains server‑side; the browser never sees it.
No browsing of uploaded media; only ephemeral session state is shown.
Run behind HTTPS with a reverse proxy and restrict CORS to your domain(s).

Usage flow

Admin: Login → Menu → Create invite link (optionally one‑time / expiry / album) → Share link or QR.
Guest: Open invite link → Drop files → Upload progress and results shown.
Optional: Enable public uploader and set IMMICH_ALBUM_NAME for a default landing page.

License

MIT.

7.8 KiB Raw Blame History Unescape Escape