Installation

Installation

tvtimes is one Docker Compose stack: an all-in-one app container (API + worker + web UI), Postgres 16, and Redis 7. No build step — it runs a published multi-arch image (linux/amd64 + linux/arm64). You need Docker with the Compose plugin.

1. Get the files

mkdir tvtimes && cd tvtimes
curl -O https://raw.githubusercontent.com/issinoho/tvtimes/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/issinoho/tvtimes/main/.env.example

2. Configure

Edit .env. For a first run on your LAN you only need three lines:

TVTIMES_PUBLIC_ORIGIN=http://192.168.1.10:8888   # the address you'll open in a browser
TVTIMES_WEBAUTHN_RP_ID=localhost                  # keep as localhost for a bare-IP setup
POSTGRES_PASSWORD=pick-something

TVTIMES_PUBLIC_ORIGIN must match exactly what the browser shows — scheme, host, and port, no trailing slash. Passkeys are bound to it. See Configuration for everything else.

3. Start

docker compose up -d
docker compose logs -f tvtimes

Open TVTIMES_PUBLIC_ORIGIN and create your account. With the default TVTIMES_EMAIL_PROVIDER=console the email-verification link is printed to the log — click it from there:

docker compose logs tvtimes | grep -E "email.console|email.undelivered_body"

One container serves the API and the web app on port 8888 (/api/* to the backend, everything else to the SPA); a second container runs the background worker. Nothing else is exposed.

What's now running

	Purpose
tvtimes (web)	API + built SPA on the same origin. Runs alembic upgrade head on start, then uvicorn. Stateless.
worker	arq worker — refreshes sources & EPG, warms the TMDB cache, sends reminder emails (a cron every 5 min). One is enough.
db	Postgres 16 — the only stateful store
redis	queue + rate-limit storage (safe to lose)

The entrypoint generates the signing/encryption secrets into the secrets volume on first run. Back that volume up — see Upgrades and Backups.

Next

• Sources — connect a playlist or tuner
• Reverse Proxy and HTTPS — required for passkeys unless you're on localhost