Quickstart

1. Get the compose file

   curl -fsSL https://raw.githubusercontent.com/Strandgaard96/mc-gamertime/main/docker-compose.yml -o docker-compose.yml

   No clone needed — this one file is the whole self-host setup.

2. Set your admin credentials

   echo "ADMIN_USERNAME=admin" >> .env
   echo "ADMIN_PASSWORD=<your-password>" >> .env

   Compose auto-loads .env from the same directory. The first boot creates this admin account; afterwards the variables are ignored, so an existing password is never overwritten.

   Caution

   Don’t skip this. Until an admin account exists, every request — the login page included — returns 503 {"detail": "Service unavailable"}. Set both here, or create the account by hand as shown in the next step. Setting only one of the two is a startup error.

3. Start the stack

   docker compose up -d

   Pulls the pre-built image from GHCR and creates the SQLite database and storage directory under ./config/app/ on first run. Wait a few seconds for the app container to become healthy.

   Image tags: latest and X.Y.Z follow releases; main is the edge build from every commit. Pin image: ghcr.io/strandgaard96/mc-gamertime:X.Y.Z in docker-compose.yml if you want to control when you upgrade.

   Tip

   To create accounts by hand — the first one if you skipped step 2, or more later:

   docker compose exec app python3 scripts/create-user.py \
     --username alice --display-name "Alice" --role admin --password <your-password>

   Run it with no arguments and it prompts for each value (needs a real terminal, so docker compose exec works but exec -T does not). Takes effect on the next request; no restart needed.

4. Open the app

   Navigate to http://localhost:4263 and log in.

Tip

No Compose? The image is self-hosted by default — SQLite, local file storage, no cloud account — so a bare docker run works too:

docker run -d -p 4263:4263 -v ./config/app:/data \
  -e ADMIN_USERNAME=admin -e ADMIN_PASSWORD=<your-password> \
  ghcr.io/strandgaard96/mc-gamertime

Mount /data as shown, or the database and generated JWT secret vanish with the container.

Tip

Want to build from source instead? Clone the repo and build locally:

git clone https://github.com/Strandgaard96/mc-gamertime && cd mc-gamertime
docker build -t mc-gamertime-local .

Then point image: in your docker-compose.yml at mc-gamertime-local before docker compose up -d.

What’s running

Container	Role	Port (internal)
app	FastAPI + React frontend, embedded SQLite, local filesystem storage	4263
init	One-shot, fixes ownership on config/app then exits	none

Only app is exposed to the host at localhost:4263.

docker-compose.yml

docker-compose.yml

services:
  init:
    container_name: mc-gamertime-init
    image: alpine:3
    user: root
    command: >-
      sh -c "mkdir -p /config/app &&
      chown -R ${PUID:-1000}:${PGID:-1000} /config/app"
    volumes:
      - ./config:/config
    restart: "no"
    deploy:
      resources:
        limits:
          memory: 32m
          cpus: "0.1"
    security_opt:
      - no-new-privileges:true
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
    cap_drop: [ALL]

  app:
    container_name: mc-gamertime
    image: ghcr.io/strandgaard96/mc-gamertime:latest
    ports:
      - "${APP_PORT:-4263}:4263"
    environment:
      DB_BACKEND: sqlite
      STORAGE_BACKEND: local
      SECRETS_PROVIDER: env
      ORIGIN_GUARD_ENABLED: "false"
      PUBLIC_RECOMMENDED_ENABLED: "false"
      BGG_TOKEN: ${BGG_TOKEN:-}
      ADMIN_USERNAME: ${ADMIN_USERNAME:-}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-}
      APP_BASE_URL: ${APP_BASE_URL:-}
      SMTP_HOST: ${SMTP_HOST:-}
      SMTP_PORT: ${SMTP_PORT:-587}
      SMTP_USERNAME: ${SMTP_USERNAME:-}
      SMTP_PASSWORD: ${SMTP_PASSWORD:-}
      SMTP_FROM_ADDRESS: ${SMTP_FROM_ADDRESS:-}
      METRICS_ENABLED: ${METRICS_ENABLED:-false}
      FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-}
      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-}
    volumes:
      - ./config/app:/data
    restart: unless-stopped
    depends_on:
      init:
        condition: service_completed_successfully
    deploy:
      resources:
        limits:
          memory: 512m
          cpus: "1.0"
        reservations:
          memory: 128m
          cpus: "0.25"
    security_opt:
      - no-new-privileges:true
    cap_drop: [ALL]

Next steps

• Configuration — BGG token for game search, password reset email, metrics
• HTTPS / Reverse proxy — before exposing it beyond your LAN
• Backups