tanner/image-drop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simplify README and install instructions

Browse Source
This commit is contained in:
Tanner Collin
2026-01-22 11:59:48 -07:00
parent c340a75eda
commit d4159dcd9e
6 changed files with 35 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
README.md
View File

@@ -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 disabled 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 enabled by default.
Forked from "Immich Drop Uploader": https://github.com/Nasogaa/immich-drop
![File Drop Uploader Dark Mode UI](./screenshot.png)
@@ -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‑1 cache prevents re-uploading the same file.
- **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 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.
- Chunked 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‑item progress via WebSocket.
---
## 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‑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
### 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‑in `/.env.example` with the keys above for onboarding.
---
## How it works
### How it works
1. **Queue** – Files selected in the browser are queued; each gets a client-side ID.
2. **De-dupe (local)** – Server computes **SHA‑1** and checks `state.db`. If seen, marks as **duplicate**.
@@ -207,24 +126,10 @@ You can keep a checked‑in `/.env.example` with the keys above for onboarding.
5. **Progress** – Backend streams progress via WebSocket to the same session.
6. **Privacy** – The UI shows only the current session's items. It does not provide a way to browse saved files.
---
## 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.