Deployment¶

NexCTF ships as a single application image plus three supporting services. This page covers a production Docker Compose deployment: what runs, what you must configure, TLS, backups, and upgrades.

What runs¶

The stack is four containers:

The app container is not just the API. A supervisor inside it runs three processes:

• caddy: terminates TLS, serves the built React frontend, proxies /api/* to the backend.
• backend: the FastAPI application (WORKERS uvicorn workers).
• scheduler: the worker that ticks scheduled jobs once a minute.

Getting the compose file¶

curl -O https://raw.githubusercontent.com/nexctf/nexctf/main/compose.yml

The published file pins an exact image tag. Keep it pinned; see Upgrades.

Configuration¶

Every setting is an environment variable read by the app container. The compose file gives each one a default via ${VAR:-default}, so you override them from a .env file next to compose.yml, or from your orchestrator.

Application¶

python -c "import secrets; print(secrets.token_urlsafe(32))"

Setting DOMAIN is normally all you need:

DOMAIN=ctf.example.com

FRONTEND_HOST, BACKEND_HOST and S3_PUBLIC_URL are each filled in from it (https://<DOMAIN>, and https://s3.<DOMAIN> for storage) whenever you leave them empty, matching the Caddyfile the container generates.

DOMAIN=ctf.example.com
FRONTEND_HOST=https://ctf.example.com:8443
BACKEND_HOST=https://ctf.example.com:8443

Database¶

Cache¶

Object storage¶

S3_PUBLIC_URL=https://files.example.net

TLS¶

Caddy inside the container generates its own certificate by default. It does not use Let's Encrypt or any other ACME provider. You have two supported options.

services:
  app:
    volumes:
      - ${CERTS_PATH}:/certs:ro

ports:
  - "127.0.0.1:8080:80"
  - "127.0.0.1:8443:443"

Client IP addresses¶

Rate limiting, the event log and session records all record a client IP. TRUSTED_PROXY_COUNT decides where it comes from:

Count every proxy that appends to the header, including the bundled Caddy. Setting it too high lets a client spoof its own IP and slip past rate limits; too low and every request appears to come from your proxy, so one player's rate limit throttles everyone.

Starting up¶

docker compose up -d

On every start, before serving traffic, the app container:

1. Installs anything listed in NEXCTF_PLUGINS.
2. Runs core database migrations.
3. Runs plugin database migrations.
4. Loads fixtures (plus demo data if DEMO_DATA=true).
5. Creates the default admin account if it does not already exist.
6. Starts Caddy, the backend and the scheduler.

Any failure in steps 1 to 3 stops the container rather than starting a half-migrated instance. docker compose logs app has the reason, on a line starting with [start].

The container is healthy once GET /api/v1/info answers.

The first admin account¶

Step 5 above creates one account from these variables, and only if no account with that username exists yet:

DEFAULT_ADMIN_TOKEN optionally provisions an API token for that account in the same step, so automation can talk to a fresh instance without a login round-trip. It must start with nexctf_ or the container refuses to start.

Backups¶

Persistent state lives in four named volumes.

Redis holds nothing you cannot lose. Sessions themselves are rows in PostgreSQL, so a cache wipe does not sign everyone out; it only drops in-flight password-reset links and rate-limit counters.

Database dumps from the admin panel¶

Admin → Backups dumps the database without leaving the browser. Backup now runs pg_dump in PostgreSQL's custom format and stores the result in the S3 bucket under the backups/ prefix, named for the moment it was taken and the schema version it was taken at:

backups/nexctf-20260913T041500Z-d4a9c17e3b52.dump

That trailing component is the Alembic revision, and it is what makes a dump safe to restore later. Each row in the list can be downloaded to your own machine, restored, or deleted.

Scheduling them¶

A backup_database job in the Scheduler takes the same dump on a cron expression, and its keep_last parameter prunes older ones afterwards, so the prefix does not grow without limit. Anything from 1 to 100 is accepted, and it defaults to 7.

Restoring¶

Restore on a row replaces the entire database with that dump. The platform does the sequence for you:

1. Stops the backend and the scheduler.
2. Dumps the current database, so the restore itself can be rolled back.
3. Replaces the database (pg_restore --clean --single-transaction) and flushes the cache.
4. Runs core and plugin migrations.
5. Starts the backend and the scheduler again.

The instance is unavailable for the length of that, and every user is signed out. The outcome of the last restore is reported back on the Backups page, whether it succeeded or not.

Restoring the other way, into a newer NexCTF, is fine: step 4 migrates the restored schema forward.

manager restore backups/nexctf-20260913T041500Z-d4a9c17e3b52.dump

From the command line¶

Nothing about this is admin-panel-only. A token carrying the admin.backup scope drives the same endpoints, which is the supported way to pull a nightly dump onto storage you control:

$ curl -H "Authorization: Bearer nexctf_..." \
    "https://ctf.example.com/api/v1/admin/backup"
$ curl -H "Authorization: Bearer nexctf_..." -X POST \
    "https://ctf.example.com/api/v1/admin/backup"

Take a dump immediately before every upgrade.

Upgrades¶

Migrations run automatically at container start, so an upgrade is a tag bump:

1. Back up the database (Admin → Backups, or POST /api/v1/admin/backup) and the S3 volume.
2. Edit the app image tag in compose.yml.
3. docker compose pull app && docker compose up -d app
4. Watch docker compose logs -f app for the [start] lines.

Scaling¶

The knobs that matter, and how they interact:

• WORKERS: backend processes in the app container. Start at the number of CPU cores available to it.
• POSTGRES_POOL_SIZE / POSTGRES_MAX_OVERFLOW: connections per worker. The ceiling is WORKERS × (POOL_SIZE + MAX_OVERFLOW), and the bundled PostgreSQL is started with max_connections=350. At the defaults that is 4 × 60 = 240, within budget, but raising WORKERS without raising max_connections will exhaust it.
• The scheduler is a single process that ticks once a minute. Do not run a second copy of the app container without accounting for it; jobs would fire twice.

The scoreboard is cached and pushed over Server-Sent Events, so a large field of players watching the ranking does not translate into database load.