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).
• worker: the background task runner. It fires scheduled jobs, runs plugin tasks, and does routine maintenance. Its queue lives in PostgreSQL tables, not in the cache, and Admin → Task queue shows it live.

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¶

With an external S3, point S3_HOST, S3_PORT, S3_TLS and S3_PUBLIC_URL at it. The bundled s3 service is then unused: remove it from compose.yml, along with the app service's depends_on entry for it.

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.

The compose file publishes the container's ports on every interface of the host:

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

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

TLS_TERMINATED_UPSTREAM=true
TRUSTED_PROXY_COUNT=2

ports:
  - "127.0.0.1:8080:80"

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. The default of 1 is right when clients connect to the container directly. 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 worker.

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.

Logs¶

Outside development, each process writes JSON lines to the container output and to a rotated file of its own under /var/log/nexctf: api.log for the backend, worker.log for the worker, migrate.log for the migrations run at start. The compose file keeps that directory in the app-logs volume. Every line names the process it came from in its service field, and a line logged during a request carries the signed-in user.

Health checks the container makes on itself are left out of the access log.

Metrics¶

The backend serves Prometheus metrics at /metrics on the main hostname, next to /api. They are on by default, but outside development nothing is served until METRICS_TOKEN is set; the backend logs a warning at start to say so.

METRICS_TOKEN=a-long-random-value

The scraper sends it as a bearer token:

scrape_configs:
  - job_name: nexctf
    scheme: https
    authorization:
      credentials: a-long-random-value
    static_configs:
      - targets: ["ctf.example.com"]

METRICS_ENABLED=false removes the endpoint altogether.

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 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, what triggered it, and the schema version it was taken at:

backups/nexctf-20260913T041500Z-manual-d4a9c17e3b52.dump

The trailing component is the Alembic revision, and it is what makes a dump safe to restore later. The one before it is the source, shown in the list's Source column:

Dumps taken before NexCTF 0.10.1 carry no source and show an empty cell. 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. Manual and scheduled dumps count towards it; pre-restore dumps never do, and are never pruned, so delete those by hand once you no longer need to undo a restore.

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 worker.
2. Dumps the current database as a Pre-restore backup, 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 worker 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-manual-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"

Downloading a dump takes two requests. The first exchanges its key for a ticket, which works once and only for 60 seconds; the second fetches the dump with that ticket, and needs no other credential:

$ curl -H "Authorization: Bearer nexctf_..." -X POST \
    "https://ctf.example.com/api/v1/admin/backup/download?key=backups/nexctf-20260913T041500Z-manual-d4a9c17e3b52.dump"
{"status": "SUCCESS", ..., "data": {"ticket": "..."}}
$ curl -o nexctf.dump \
    "https://ctf.example.com/api/v1/admin/backup/download?ticket=..."

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, and their POSTGRES_AUTH_* counterparts: connections per worker. The ceiling is WORKERS × (POOL_SIZE + MAX_OVERFLOW + AUTH_POOL_SIZE + AUTH_MAX_OVERFLOW), and the bundled PostgreSQL is started with max_connections=350. At the defaults that is 4 × 75 = 300, within budget, but raising WORKERS without raising max_connections will exhaust it.
• The worker is a single process per app container, separate from WORKERS. Jobs are queued in PostgreSQL and claimed with row locks, so a job fires once even if a second copy of the container runs a second worker, though the restore flow still assumes a single container.

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.