Docker Compose: Registry Images

This page covers:

• docker-compose.registry.yml

Use this path when you want Docker Compose on a self-managed host, but do not want to build the runtime images locally.

GHCR status

This path is supported.

If you prefer not to manage GHCR authentication on the target host, use Docker Compose: Source Build.

GitHub Container Registry auth

GitHub’s container registry typically uses personal access token authentication for private image pulls.

Reference:

• Working with the Container registry

Typical login flow:

echo "YOUR_CLASSIC_PAT" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

The token needs:

• read:packages

Infisical or raw envs

Like the source-build compose file, this path supports:

• Infisical-backed startup
• direct env-file startup with SKIP_INFISICAL=true

Use the same guidance from Environment Reference.

What this compose file creates

It creates:

• postgres
• redis
• api
• worker
• web
• migrate

Optional profiles:

• docs
• tools

Standard deployment flow

docker compose -f docker-compose.registry.yml pull
docker compose -f docker-compose.registry.yml up -d

Common follow-up commands:

docker compose -f docker-compose.registry.yml ps
docker compose -f docker-compose.registry.yml logs --tail=200 api worker web migrate
docker compose -f docker-compose.registry.yml --profile tools build tools
docker compose -f docker-compose.registry.yml --profile tools run --rm \
  -e SYSTEM_ADMIN_PASSWORD="YourStrongPasswordHere" \
  tools pnpm seed:system-admin

The runtime services pull from GHCR, but the tools profile is still built locally from the repository because it is not published as a standalone runtime image.

If you are using SKIP_INFISICAL=true, the tools and migrate containers still validate the same runtime config schema as the app. A partial .env is not enough.

Ports

Default host mappings:

When to choose this path

Choose registry images when:

• you want a simpler host without local image builds
• you already have GHCR access
• you still want the compose-managed Postgres and Redis services

Next step

After the stack is up, continue with Routing and Domains and Post-Deploy Bootstrap.