@@ -1,7 +1,9 @@
# 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 dis abled by default.
A tiny web app for collecting files and media 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 en abled by default.
Forked from "Immich Drop Uploader": https://github.com/Nasogaa/immich-drop
@@ -13,99 +15,53 @@ Admin users log in to create public invite links; invite links are always public
- **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‑
- **Telegram Notifications:** Get notified via Telegram when upload batches are complete.
- **Telegram Notifications (optional) :** 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.
---
## Table of contents
- [Quick start ](#quick-start )
- [New Features ](#new-features )
- [Chunked Uploads ](#chunked-uploads )
- [Architecture ](#architecture )
- [Folder structure ](#folder-structure )
- [Requirements ](#requirements )
- [Configuration (.env) ](#configuration-env )
- [How it works ](#how-it-works )
- [Mobile notes ](#mobile-notes )
- [Troubleshooting ](#troubleshooting )
- [Security notes ](#security-notes )
- [Development ](#development )
- [License ](#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)
Clone the repo.
Copy `.env.example` to `.env` and edit.
### docker-compose.yml
``` yaml
version : "3.9"
services :
immich-drop :
image : ghcr.io/nasogaa/immich-drop:latest
pull_policy : always
container_name : immich-drop
file-drop :
build : .
container_name : file-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
- "8080:8080"
env_file :
- .env
volumes :
- immich_drop_data: /data
# Simple healthcheck
- ./data:/file_drop /data
- /mnt/example/file-drop:/file_drop/data/uploads
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" ]
test : [ "CMD-SHELL" , "python - <<'PY'\nimport urllib.request,sys\ntry:\n urllib.request.urlopen('http://localhost:8080/').read( ); sys.exit(0)\nexcept Exception:\n 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
$ sudo docker compose up --build -d
```
---
## Chunked Uploads
### Chunked Uploads
- Enable c hunked uploads by setting `CHUNKED_UPLOADS_ENABLED=true` .
- Configure chunk size with `CHUNK_SIZE_MB` (default: `9 5` ). The client only uses chunked mode for files larger than this.
- C hunked uploads are enabled by default. Uses setting `CHUNKED_UPLOADS_ENABLED=true` .
- Configure chunk size with `CHUNK_SIZE_MB` (default: `50 ` ). 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‑
---
## Developtment
## Architecture
### Architecture
- **Frontend:** static HTML/JS (Tailwind). Drag & drop or "Choose files", queue UI with progress and status chips.
- **Backend:** FastAPI + Uvicorn.
@@ -114,43 +70,11 @@ docker compose up -d
- WebSocket `/ws` pushes per‑
- **Persistence:** A local SQLite database (`state.db` ) prevents re‑ `/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
### Requirements
- **Python** 3.11
---
# Local dev quickstart
## Development
### Local dev quickstart
Run with live reload:
@@ -160,9 +84,7 @@ python main.py
The backend contains docstrings so you can generate docs later if desired.
---
## Dev Configuration (.env)
### Dev Configuration (.env)
``` ini
# Server (dev only)
@@ -193,12 +115,9 @@ CHUNK_SIZE_MB=95
```
You can keep a checked‑ `/.env.example` with the keys above for onboarding.
---
## How it works
### How it works
1. **Queue ** –
2. **De-dupe (local) ** – **SHA‑ ** and checks `state.db` . If seen, marks as **duplicate ** .
@@ -207,24 +126,10 @@ You can keep a checked‑
5. **Progress ** –
6. **Privacy ** –
---
## Security notes
### 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` .
- 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 for a default landing page.
---
## License
MIT.
