chore: added documentation

2026-03-09 22:45:24 +01:00
parent dd0d0cfde6
commit ec8d5a6124
11 changed files with 963 additions and 0 deletions
--- a/docs/docker-deployment.md
+++ b/docs/docker-deployment.md
@@ -0,0 +1,109 @@
+# Docker & Deployment
+
+## Overview
+
+Trackpull is fully containerized with Docker. The `docker-compose.yml` handles all volume mounts and environment configuration. A single `docker compose up -d --build` is enough to get a running instance.
+
+---
+
+## Quick Start
+
+```bash
+cp .env.example .env
+# Edit .env: set ADMIN_USERNAME, ADMIN_PASSWORD, SECRET_KEY, and PORT
+docker compose up -d --build
+```
+
+The app will be available at `http://localhost:{PORT}` (default: 5000).
+
+---
+
+## Environment Variables
+
+All configuration goes in `.env`. Copy `.env.example` to get started.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ADMIN_USERNAME` | — | Username for the seeded admin account |
+| `ADMIN_PASSWORD` | — | Password for the seeded admin account |
+| `SECRET_KEY` | — | Flask session key; use a 32-byte random hex string |
+| `PORT` | `5000` | Host port the app is exposed on |
+| `HOST_DOWNLOADS_DIR` | `./downloads` | Host path for downloaded files |
+| `HOST_CONFIG_DIR` | `./config` | Host path for DB, cookies, device cert |
+| `DOWNLOADS_DIR` | `/downloads` | Container-internal downloads path (rarely changed) |
+| `COOKIES_PATH` | `/config/cookies.txt` | Path to Spotify cookies file inside the container |
+| `CONFIG_DIR` | `/config` | Config directory inside the container |
+| `WVD_PATH` | `/config/device.wvd` | Path to Widevine device certificate inside the container |
+
+> **Important**: `SECRET_KEY` must be a stable secret. Changing it invalidates all active sessions.
+
+---
+
+## Volumes
+
+| Host path (from `.env`) | Container path | Contents |
+|-------------------------|----------------|---------|
+| `HOST_DOWNLOADS_DIR` | `/downloads` | Per-user download directories |
+| `HOST_CONFIG_DIR` | `/config` | SQLite DB, cookies.txt, device.wvd |
+
+Both directories are created automatically by Docker if they don't exist.
+
+---
+
+## Dockerfile Summary
+
+**Base image**: `python:3.12-slim`
+
+**System packages installed**:
+- `ffmpeg` — audio conversion
+- `aria2` — download manager
+- `git`, `curl`, `unzip` — tooling
+
+**Binaries installed**:
+- **Bento4 `mp4decrypt`** — MP4 DRM decryption (version 1.6.0-641, downloaded from bok.net)
+
+**Python packages**:
+- From `requirements.txt`: Flask, gunicorn, mutagen, werkzeug, etc.
+- `websocket-client` — WebSocket support
+- `votify-fix` — Spotify downloader (installed from GitHub: GladistonXD/votify-fix)
+
+**Runtime command**:
+```
+gunicorn --bind 0.0.0.0:5000 --workers 1 --threads 4 app:app
+```
+
+One worker with four threads keeps SQLite contention low while still handling concurrent requests.
+
+---
+
+## Persistent Data
+
+| File | Created by | Purpose |
+|------|-----------|---------|
+| `/config/trackpull.db` | App on first run | All users, jobs, settings |
+| `/config/cookies.txt` | Admin upload | Spotify auth for Votify |
+| `/config/device.wvd` | Admin upload | Widevine cert for Votify |
+
+Back up `/config/` to preserve all user data between rebuilds.
+
+---
+
+## Updating
+
+```bash
+docker compose down
+docker compose up -d --build
+```
+
+The database and config files persist on the host, so user data survives rebuilds.
+
+---
+
+## Key Files
+
+| File | Relevance |
+|------|-----------|
+| [Dockerfile](../Dockerfile) | Container image definition |
+| [docker-compose.yml](../docker-compose.yml) | Service orchestration |
+| [.env.example](../.env.example) | Environment template |
+| [requirements.txt](../requirements.txt) | Python dependencies |