Docker installation

Requirements

Use a host with Git, Docker Engine and the Docker Compose plugin (docker compose). The supplied stack runs PostgreSQL 17 plus separate API and worker containers. The API image includes the built web application.

There is no established universal minimum RAM/disk figure in the repository. Catalog size and selected languages dominate first-import time, database growth, image storage and network traffic. Plan free disk space for both the database and images, plus backups; a small user count does not make full catalog imports small.

Examples below use the prebuilt stack. The source-build stack has a different project name and data-dev directory.

1. Obtain the source and configuration

git clone https://github.com/FoxOps/zukan.git
cd zukan
cp .env.example .env

Set these values in .env before first start:

POSTGRES_PASSWORD=REPLACE_WITH_RANDOM_HEXADECIMAL_VALUE
TCG_SECRET_KEY=REPLACE_WITH_ANOTHER_RANDOM_VALUE_AT_LEAST_32_CHARACTERS
TCG_DEFAULT_ADMIN_USERNAME=admin
TCG_DEFAULT_ADMIN_PASSWORD=REPLACE_WITH_A_STRONG_ADMIN_PASSWORD
TCG_PUBLIC_URL=http://localhost:8000
TCG_COOKIE_SECURE=false

Generate each secret independently, for example with openssl rand -hex 32. Do not use the literal placeholders. Hexadecimal database passwords avoid URL-encoding and Compose interpolation problems. The local HTTP example requires TCG_COOKIE_SECURE=false; use true behind public HTTPS.

The bootstrap password is explicitly set here because the application default is changeme. Bootstrap runs only while the database has no users. Changing the bootstrap environment variable later is not a password reset.

For repeatable upgrades, set ZUKAN_TAG to an existing release tag rather than following latest. Verify the tag exists in the registry/release workflow.

2. Start the stack

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 api
docker compose logs --tail=100 worker

The repository documents the GHCR images as public. An old comment in Compose still mentions a private package; a GitHub token is not a normal installation prerequisite.

Open http://localhost:8000, or the host's reachable address and configured port. Sign in using the configured bootstrap administrator.

3. Check initialization

The API startup command runs alembic upgrade head before Uvicorn. PostgreSQL must be healthy first. The worker registers games and starts importing catalog data.

curl --fail http://localhost:8000/api/health
docker compose logs -f worker

The health route reports API version and maintenance state. A successful HTTP response does not certify that every catalog has finished importing. Check the Data sync page and worker logs.

4. Locate persistent data

Host path	Contents
data/postgres	PostgreSQL data directory
data/images	Card images, symbols, source caches, user overrides
import	Read-only image-import input mounted into the API
.env	Deployment configuration and secrets

The database is not published on a host port by the supplied Compose file. The API is published on ${ZUKAN_PORT:-8000}; the short port syntax normally binds on host interfaces, so decide deliberately how it should be reached.

5. Add HTTPS and accounts

For remote use, complete Reverse proxy and HTTPS, then create users or configure Single sign-on. Keep a working administrator account during authentication changes.

Common first-start mistakes

• Secret key shorter than 32 characters: API startup refuses it.
• Secure cookie on plain HTTP: login does not persist.
• Existing database: bootstrap settings do not reset credentials.
• Worker not running: catalogs remain empty and UI jobs stay queued.
• Phone uses localhost: it connects to itself.
• Production and source-build stacks use the same host port: choose another ZUKAN_PORT when running both.

Implementation references

• docker-compose.yml
• Dockerfile
• .env.example
• backend/app/main.py