Skip to content

1. Start Here

Jump to bottom
DannyVFilms edited this page Apr 16, 2026 · 5 revisions

Getting Started

This guide focuses on the recommended path: Docker Compose with the prebuilt release image.

Recommended path: Docker Compose

  1. Clone the repo and enter the project root.
  2. Pick a compose file:
    • docker-compose.yml (SQLite, simplest)
    • docker-compose.postgres.yml (Postgres, production)
  3. Set required environment variables:
    • SECRET (required, long random string)
    • REDIS_URL (required for Docker, default in compose is redis://redis:6379)
    • TZ (recommended)
  4. Optional metadata keys for richer matching:
    • TMDB_API, TVDB_API_KEY, MAL_API, IGDB_ID, IGDB_SECRET, STEAM_API_KEY, BGG_API_TOKEN
    • See Environment Variables for the full list.
  5. Start the stack:
    • docker compose up -d
  6. Open http://localhost:8000 and log in.

First-run checklist

  • Migrations
    • Docker images run python manage.py migrate --noinput on boot.
    • From source: cd src && python manage.py migrate.
  • Create your first user
    • Use the "Register now" link on the login page (registration is enabled by default).
    • If registration is disabled (REGISTRATION=False), create a user from the CLI:
      • cd src && python manage.py createsuperuser
  • Enable the admin (optional)
    • Set ADMIN_ENABLED=True in your environment.
    • Create or promote an admin user:
      • Docker: docker exec -it yamtrack python manage.py createsuperuser
      • Or promote an existing user: 
        docker exec -it yamtrack python manage.py shell
>>> from users.models import User
>>> User.objects.filter(username="your_username").update(is_staff=True, is_superuser=True)
    • See Admin Guide for details.

First login: what to do next

  1. Connect integrations in Settings -> Integrations (Plex, Trakt, Pocket Casts, Last.fm, etc.).
  2. Run your first import in Settings -> Import.
  3. Visit History and Statistics; background caches may show "Refreshing ... in background" while they rebuild.
  4. Tune Preferences and Sidebar to control media types, sorting, and layout.

Running from source (local dev) If you are not using Docker, you will need Redis and a Celery worker/beat process for imports and cache refreshes. See the AGENTS.md Quickstart or README for the full local dev flow.

Upgrading? If you are moving from dev to release, follow the Upgrade Guide:

Upgrade Guide (dev to release)

This guide covers the fork upgrade path from upstream dev into release.

Before you upgrade

  • Back up your database.
    • Docker (SQLite): copy ./db or at least ./db/db.sqlite3.
    • Docker (Postgres): dump the postgres_data volume or use pg_dump.
    • From source: copy src/db/db.sqlite3 if you use SQLite locally.
  • Save your .env or compose files.
  • Note your current integrations (Plex, Trakt, Pocket Casts, Last.fm) and any webhook URLs.

Upgrade steps

  1. Update the code or image.
    • Docker: docker compose pull then docker compose up -d.
    • From source: git pull and update dependencies (pip install -r requirements.txt).
  2. Apply migrations.
    • Docker runs python manage.py migrate --noinput on boot.
    • From source: cd src && python manage.py migrate.
  3. Ensure Redis + Celery are running.
    • History/Statistics caches and import jobs rely on background tasks.

Migrations and model additions This release adds new data models and tables. Expect migrations for:

  • New media types: Music, Podcast, Board Game.
  • Music hierarchy (Artist, Album, Track) and podcast show/episode tracking.
  • Collection metadata (CollectionEntry) and metadata backfill tracking.

New caches: History and Statistics History and Statistics now use background caching. After upgrade you may see banners like "Refreshing history in background..." or "Refreshing statistics in background...". This is expected on first load or after a refresh:

  • Keep Redis and Celery running to allow cache rebuilds.
  • Use the in-page refresh buttons if data looks stale.

Integration additions to configure New or expanded integrations include:

  • Plex (connect + history + collection metadata)
  • Pocket Casts (connect + recurring import)
  • Last.fm (connect + scheduled scrobble polling)
  • Jellyfin / Emby / Jellyseerr webhooks

Environment variables you may need:

  • LASTFM_API_KEY
  • BGG_API_TOKEN
  • Plex tuning: PLEX_* (client identifier, SSL verify, history page size) See Environment Variables for the full list.

Webhook endpoints now include your user token. You can copy the correct URLs from Settings -> Integrations.

Common upgrade surprises and fixes

  • History/Statistics look empty or stuck
    • Cause: caches are rebuilding or Celery is not running.
    • Fix: confirm Redis + Celery are up, then wait for the refresh banner to clear.
  • Webhooks stop firing
    • Cause: webhook URLs need your user token.
    • Fix: update URLs from Settings -> Integrations; regenerate the token if needed.
  • Signups are closed
    • Cause: REGISTRATION=False in env.
    • Fix: set REGISTRATION=True or create a user via createsuperuser.
  • 403s behind a reverse proxy
    • Cause: missing URLS in env.
    • Fix: set URLS to your public base URL(s).

See also

Clone this wiki locally