Production architecture

rCTF ships as a single container managed by supervisord. Inside the container, the Hono API server runs as a Bun process that also spawns the leaderboard worker as a Bun Worker thread. Alongside it, an nginx instance serves the SvelteKit static build and proxies /api and /uploads to the API.

The container expects to sit behind a reverse proxy, with PostgreSQL and Redis running as external services. The bundled compose.yml wires those dependencies together for a single-node deployment.

For deployment steps, see Installation and the VPS setup walkthrough. This page is a reference for the inner architecture.

Container layout#

Paths inside the running container after the production stage finishes assembly:

• app/

  • apps/

    • api/

      • dist/Bun-built API + leaderboard worker
      • templates/Email templates
  • packages/

    • config/Loader sources
    • db/

      • src/
      • migrations/Drizzle SQL migrations
    • scoring/
    • types/
    • util/
  • node_modules/Production-only deps
  • static/SvelteKit static build, served by nginx
  • rctf.d/Mounted config directory
  • uploads/Local upload provider data (when used)
• etc/

  • supervisord.conf Process definitions
  • nginx/

    • http.d/

      • default.conf Static + /api proxy

The rctf.d/ and uploads/ directories are mounted from the host by compose.yml. With the default local upload provider, files land under /app/uploads/ because the provider resolves uploadDirectory from process.cwd(), which is /app/.

Build stages#

The Dockerfile is at deploy/rctf/Dockerfile and uses oven/bun:1.3.14-alpine as both the build and runtime base. The stages:

1
FROM oven/bun:1.3.14-alpine AS runtime-base
2
WORKDIR /app
3

4
# ...
5

6
FROM runtime-base AS production
7

8
RUN apk add --no-cache supervisor nginx nginx-mod-http-brotli
9
COPY deploy/rctf/supervisord.conf /etc/supervisord.conf
10
COPY deploy/rctf/nginx.conf /etc/nginx/http.d/default.conf
11

12
COPY --from=build /app/apps/api/dist ./apps/api/dist
13
COPY --from=prod-deps /app/node_modules ./node_modules
14
# ...
15
COPY --from=build /app/apps/web/build ./static
16

17
ENV NODE_ENV=production
18
ENV WORKER_EXTENSION=.js
19
CMD ["supervisord", "-c", "/etc/supervisord.conf"]

WORKER_EXTENSION is set to .js so the API process resolves its compiled worker entry (./leaderboard.js) rather than the .ts source used in development.

Process supervision#

/etc/supervisord.conf defines two long-running programs. Both inherit the container’s PID 1 (supervisord), have autorestart=true, and stream stdout/stderr to the container’s stdout/stderr without rotation.

1
[program:api]
2
command=/usr/local/bin/bun run /app/apps/api/dist/index.js
3
autostart=true
4
autorestart=true
5
# ...
6

7
[program:nginx]
8
command=/usr/sbin/nginx -g 'daemon off;'
9
autostart=true
10
autorestart=true

If either process exits non-zero, supervisord restarts it. The leaderboard worker is not a separate supervised program. It is a thread inside the API process, so it restarts together with the API.

Nginx#

The container’s nginx is built from Alpine’s nginx package together with nginx-mod-http-brotli. The site config at deploy/rctf/nginx.conf is copied to /etc/nginx/http.d/default.conf.

1
server {
2
    listen 80 default_server;
3
    root /app/static;
4
    gzip_static on;
5
    brotli_static on;
6

7
    # ...
8

9
    location ~ ^/api/v[12]/admin/upload$ {
10
        proxy_pass http://127.0.0.1:3000;
11
        client_max_body_size 0;
12
        proxy_request_buffering off;
13
    }
14

15
    location ~ ^/(api|uploads) {
16
        proxy_pass http://127.0.0.1:3000;
17
    }
18

19
    location /_app/immutable/ {
20
        add_header Cache-Control "public, max-age=86400, immutable";
21
        try_files $uri $uri/ /index.html;
22
    }
23

24
    location / {
25
        try_files $uri $uri/ /index.html;
26
    }
27
}

Notable behavior:

• brotli_static and gzip_static serve the .br and .gz files the SvelteKit adapter-static precompresses (precompress: true in apps/web/svelte.config.ts). No on-the-fly compression is configured.
• /_app/immutable/ is the SvelteKit hashed-asset directory and gets a one-day immutable cache.
• The admin upload route has request buffering disabled and client_max_body_size=0 so large uploads stream straight to the API.
• /api and /uploads proxy to the API on 127.0.0.1:3000. When the local upload provider is in use, the API serves files from /app/uploads/ through its own static handler.
• nginx adds Referrer-Policy: no-referrer, X-Frame-Options: DENY, and X-Content-Type-Options: nosniff on every response. CSP is not set here.

Content Security Policy#

CSP is defined in apps/web/svelte.config.ts and applied by SvelteKit at build time. Because apps/web/ is built with adapter-static, SvelteKit injects the policy as a <meta http-equiv="Content-Security-Policy"> tag in each rendered page, along with the auto-generated script hashes. nginx does not add a Content-Security-Policy header on its own.

1
csp: dev
2
  ? undefined
3
  : {
4
      directives: {
5
        'default-src': ['none'],
6
        // ...
7
      },
8
    },

The directives:

The list above is the entire allow-set the bundled build ships with. There is no provider-aware logic that widens it at runtime, so captcha sources, analytics endpoints, and cloud storage origins are always present, regardless of whether the matching provider is enabled. Self-hosted analytics endpoints, custom S3-compatible object stores, or any other external origin that the frontend needs to reach require editing apps/web/svelte.config.ts and rebuilding.

Horizontal scaling with instanceType#

The instanceType config option (environment variable RCTF_INSTANCE_TYPE) selects what an API process runs. The available modes are all, frontend, and leaderboard. The dispatch happens at startup in apps/api/src/index.ts:

1
if (config.instanceType === 'leaderboard' || config.instanceType === 'all') {
2
  startLeaderboardWorker(logger)
3
}
4

5
if (config.instanceType === 'frontend' || config.instanceType === 'all') {
6
  const port = Number(process.env.PORT ?? 3000)
7
  Bun.serve({ port, fetch: app.fetch })
8
}

See Scaling for the full mode table, the one-leaderboard-replica constraint, the forced-update limitation in split mode, and observed resource usage on real events.

External dependencies#

The container only contains the rCTF application, nginx, and supervisor. Everything else is external.

Optional dependencies that the deployer must supply when the matching provider is enabled:

• S3 / GCS for the uploads/s3 or uploads/gcs upload providers. See Uploads.
• SES, SMTP, or another email provider for the email integration.
• OpenAI (or another moderation provider) for avatar moderation.
• Docker instancer or a Kubernetes cluster running the rCTF k8s-controller for per-team challenge instances. See Instancer.
• Captcha provider (reCAPTCHA, hCaptcha, or Turnstile). The CSP already permits all three.

The bundled compose.yml pins one PostgreSQL and one Redis container alongside rctf. The rctf service exposes 127.0.0.1:8080 and expects a reverse proxy (typically nginx or Caddy on the host) to terminate TLS and forward to it.