228 lines
6.5 KiB
Markdown
228 lines
6.5 KiB
Markdown
# Immich Drop Uploader
|
||
|
||
A tiny, zero-login web app for collecting photos/videos into your **Immich** server.
|
||
|
||
- **No accounts** — open the page, drop files, done
|
||
- **Queue with progress** via WebSocket (success / duplicate / error)
|
||
- **Duplicate prevention** (local SHA‑1 cache + optional Immich bulk‑check)
|
||
- **Original dates preserved** (EXIF → `fileCreatedAt` / `fileModifiedAt`)
|
||
- **Mobile‑friendly**
|
||
- **.env‑only config** (clean deploys) + Docker/Compose
|
||
- **Privacy‑first**: never lists server media; UI only shows the current session
|
||
|
||
---
|
||
|
||
## Table of contents
|
||
- [Quick start](#Quick_start)
|
||
- [Architecture](#architecture)
|
||
- [Folder structure](#folder-structure)
|
||
- [Requirements](#requirements)
|
||
- [Configuration (.env)](#configuration-env)
|
||
- [Quick start (Docker/Compose)](#quick-start-dockercompose)
|
||
- [How it works](#how-it-works)
|
||
- [Mobile notes](#mobile-notes)
|
||
- [Troubleshooting](#troubleshooting)
|
||
- [Security notes](#security-notes)
|
||
- [Development](#development)
|
||
- [License](#license)
|
||
|
||
---
|
||
## Quick start
|
||
Copy the docker-compose.yml and the .env file to a common folder,
|
||
update the .env file before executing the CLI commands to quick start the container.
|
||
### docker-compose.yml
|
||
```
|
||
version: "3.9"
|
||
|
||
services:
|
||
immich-drop:
|
||
image: ghcr.io/nasogaa/immich-drop:latest
|
||
pull_policy: always
|
||
container_name: immich-drop
|
||
restart: unless-stopped
|
||
|
||
# Load all variables from your repo's .env (PORT, IMMICH_BASE_URL, IMMICH_API_KEY, etc.)
|
||
env_file:
|
||
- ./.env
|
||
|
||
# Expose the app on the same port as configured in .env (defaults to 8080)
|
||
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:
|
||
```
|
||
### .env
|
||
|
||
```
|
||
HOST=0.0.0.0
|
||
PORT=8080
|
||
IMMICH_BASE_URL=http://REPLACE_ME:2283/api
|
||
IMMICH_API_KEY=REPLACE_ME
|
||
MAX_CONCURRENT=3
|
||
STATE_DB=/data/state.db
|
||
```
|
||
### CLI
|
||
```
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
---
|
||
|
||
## Architecture
|
||
|
||
- **Frontend:** static HTML/JS (Tailwind). Drag & drop or “Choose files”, queue UI with progress and status chips.
|
||
- **Backend:** FastAPI + Uvicorn.
|
||
- Proxies uploads to Immich `/assets`
|
||
- Computes SHA‑1 and checks a local SQLite cache (`state.db`)
|
||
- Optional Immich de‑dupe via `/assets/bulk-upload-check`
|
||
- WebSocket `/ws` pushes per‑item progress to the current browser session only
|
||
- **Persistence:** local SQLite (`state.db`) prevents re‑uploads across sessions/runs.
|
||
|
||
---
|
||
|
||
## Folder structure
|
||
|
||
```
|
||
immich_drop/
|
||
├─ app/ # FastAPI application (Python package)
|
||
│ ├─ __init__.py
|
||
│ ├─ app.py # uvicorn app:app
|
||
│ └─ config.py # loads .env from repo root
|
||
├─ frontend/ # static UI served at /static
|
||
│ ├─ index.html
|
||
│ └─ app.js
|
||
├─ main.py # thin entrypoint (python main.py)
|
||
├─ requirements.txt # Python deps
|
||
├─ .env # single config file (see below)
|
||
├─ Dockerfile
|
||
├─ docker-compose.yml
|
||
└─ README.md
|
||
```
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
- **Python** 3.11
|
||
- An **Immich** server + **API key**
|
||
|
||
---
|
||
## Configuration (.env)
|
||
|
||
```ini
|
||
# Server
|
||
HOST=0.0.0.0
|
||
PORT=8080
|
||
|
||
# Immich connection (include /api)
|
||
IMMICH_BASE_URL=http://REPLACE_ME:2283/api
|
||
IMMICH_API_KEY=REPLACE_ME
|
||
MAX_CONCURRENT=3
|
||
|
||
# Local dedupe cache
|
||
STATE_DB=./data/state.db # local dev -> ./state.db (data folder is created in docker image)
|
||
# In Docker this is overridden to /data/state.db by docker-compose.yml
|
||
```
|
||
|
||
|
||
You can keep a checked‑in `/.env.example` with the keys above for onboarding.
|
||
|
||
---
|
||
|
||
## Quick start (Docker/Compose)
|
||
|
||
1) Put your settings in **.env** at the repo root (see below).
|
||
2) Build & run:
|
||
|
||
```bash
|
||
docker compose build
|
||
docker compose up -d
|
||
# open http://localhost:8080
|
||
```
|
||
|
||
A named volume stores `/data/state.db` so duplicates are remembered across container restarts.
|
||
|
||
---
|
||
|
||
|
||
|
||
## 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**.
|
||
3. **De‑dupe (server)** – Attempts Immich `/assets/bulk-upload-check`; if Immich reports duplicate, marks accordingly.
|
||
4. **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`.
|
||
5. **Progress** – Backend streams progress via WebSocket to the same session.
|
||
6. **Privacy** – UI shows only the current session’s items. It never lists server media.
|
||
|
||
---
|
||
|
||
|
||
## Mobile notes
|
||
|
||
- Uses a **label‑wrapped input** + short **ghost‑click suppression** so the system picker does **not** re‑open after tapping **Done** (fixes iOS/Android quirks).
|
||
- Drag‑and‑drop is desktop‑oriented; on touch, use **Choose files**.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
**Uploads don’t start on phones / picker re‑opens**
|
||
– Hard‑refresh; current UI suppresses ghost clicks and resets the input.
|
||
– If using a PWA/WebView, test in Safari/Chrome directly to rule out container quirks.
|
||
|
||
**WebSocket connects/disconnects in a loop**
|
||
– Match schemes: `ws://` for `http://`, `wss://` for `https://`.
|
||
– If behind a reverse proxy, ensure it forwards WebSockets.
|
||
|
||
**413 Request Entity Too Large**
|
||
– If running behind nginx/Traefik/etc., bump body size limits (`client_max_body_size` for nginx).
|
||
|
||
**/assets returns 401**
|
||
– Check `IMMICH_API_KEY` and ensure the base URL includes `/api` (e.g., `http://<host>:2283/api`).
|
||
|
||
**Duplicate detected but you expect an upload**
|
||
– The proxy caches SHA‑1 in `state.db`. For a fresh run, delete that DB or point `STATE_DB` to a new file.
|
||
|
||
---
|
||
|
||
## Security notes
|
||
|
||
- The app is **unauthenticated** by design. Share the URL only with trusted people or keep it on a private network/VPN.
|
||
- The Immich API key remains **server‑side**; the browser never sees it.
|
||
- No browsing of uploaded media; only ephemeral session state is shown.
|
||
|
||
---
|
||
|
||
## Development
|
||
|
||
Run with live reload:
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
The backend contains docstrings so you can generate docs later if desired.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT.
|