1# jellyfin-year-review
 2
 3Run these commands from the project directory.
 4
 5## 1. Generate review data
 6
 7Requires Go 1.27.2, `psql`, and native Jellystat history. Copy `.env.example` to
 8`.env` and configure:
 9
10- `JELLYFIN_URL` (reachable from this machine) and `JELLYFIN_API_KEY`.
11- `PGHOST`, `PGDATABASE`, `PGUSER`, and `PGPASSWORD` for read-only Jellystat access.
12- `REVIEW_TIMEZONE`. Posters come from Jellyfin, with TVmaze as a fallback for
13  TV shows (no additional API key).
14
15Set `PGPASSWORD='your-postgresql-password'` in `.env` (keep the quotes).
16Keep `.env` private (`chmod 600 .env`), then run:
17
18```sh
19./scripts/generate-review.sh 2025
20```
21
22The script reports its progress, loads `.env`, exports history, and generates
23`data/`. If it reports a missing `psql`, install the PostgreSQL client on this
24machine (for Debian/Ubuntu: `sudo apt install postgresql-client`). Change the year
25to generate another recap. Optionally set `REVIEW_COVERAGE` to describe your
26collection window and known gaps.
27
28## 2. Export Jellyfin users
29
30With Python 3.9+ on the Jellyfin 12.2 host:
31
32```sh
33python3 scripts/export-jellyfin-auth.py --database /path/to/jellyfin.db --output auth/users.json
34```
35
36Use the actual database path with read access to its WAL/SHM files. The export
37contains private password verifiers, never plaintext passwords. Rerun after
38password or account changes. Only supported built-in accounts can log in offline.
39
40## 3. Serve the webapp
41
42On the serving host, place the project, generated `data/`, and private
43`auth/users.json` together. **Upload `data/` and `auth/` separately:** the normal
44code-upload rsync excludes them. Do not upload the Jellyfin database or API keys.
45
46Run either option as the non-root user who owns `data/` and `auth/`.
47First set permissions and the public origin:
48
49```sh
50chmod 700 data auth
51chmod 600 auth/users.json
52
53export APP_ORIGIN=https://review.example.com
54```
55
56With Docker Compose:
57
58```sh
59export REVIEW_UID="$(id -u)" REVIEW_GID="$(id -g)"
60docker compose -f compose.offline.yaml up -d --build
61```
62
63Without Docker (requires Go 1.27.2 and Node.js 24+ to build):
64
65```sh
66npm --prefix web ci
67npm --prefix web run build
68go build -buildvcs=false -o ./review ./cmd/review
69
70./review serve --listen 127.0.0.1:8080 \
71  --data ./data --web ./web/build \
72  --auth-mode offline --auth-file ./auth/users.json
73```
74
75The server runs in the foreground; Node.js is only needed for the frontend build.
76
77Point your HTTPS reverse proxy at `127.0.0.1:8080`; `APP_ORIGIN` must match the
78public origin exactly, without a trailing slash. Compose reads settings from
79`.env`; without Docker, export `APP_ORIGIN` each time you start the server.
80
81Users log in with their exported Jellyfin credentials. Serving requires no
82Jellyfin connection. See [offline setup](docs/offline-auth.md) for secure transfer
83and atomic credential-refresh instructions.