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 sits behind a reverse proxy and connects to PostgreSQL and Redis. The bundled compose.yml starts all three services for a single-server deployment.

For deployment steps, see Installation and the VPS setup walkthrough. The sections below describe the production image itself.

Container layout

The production container has the following layout:

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/.

The container’s ephemeral runtime state lives under /tmp/. Local uploads are written to the /app/uploads/ bind mount instead of the root filesystem. This allows compose.yml to set read_only: true while mounting /tmp/ as a tmpfs.

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
FROM runtime-base AS production
5

6
RUN apk add --no-cache supervisor nginx nginx-mod-http-brotli \
7
    && addgroup -g 1001 rctf \
8
    && adduser -S -D -H -G rctf -u 1001 -s /sbin/nologin rctf \
9
    && install -d -m 0755 -o rctf -g rctf /app/uploads
10

11
COPY deploy/rctf/supervisord.conf /etc/supervisord.conf
12
COPY deploy/rctf/nginx-main.conf /etc/nginx/nginx.conf
13
COPY deploy/rctf/nginx.conf /etc/nginx/http.d/default.conf
14
COPY deploy/rctf/docker-entrypoint.sh /usr/local/bin/docker-entrypoint
15
RUN chmod +x /usr/local/bin/docker-entrypoint
16

17
COPY --from=build-api /app/apps/api/dist ./apps/api/dist
18
COPY --from=prod-deps /app/node_modules ./node_modules
19
# ...
20
COPY --from=build-web /app/apps/web/build ./static
21

22
ENV NODE_ENV=production
23
ENV WORKER_EXTENSION=.js
24
ENTRYPOINT ["/usr/local/bin/docker-entrypoint"]

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 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
user=rctf
4
autostart=true
5
autorestart=true
6
# ...
7

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

If either process exits, 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. Before supervisor starts, the container entrypoint generates the security-header configuration and the avatar upload body limit (derived from the maxAvatarSize config option) from rctf.d/, writes them to /tmp/nginx/, and runs nginx -t -e stderr to validate the complete configuration.

1
server {
2
    listen 80 default_server;
3
    root /app/static;
4
    gzip_static on;
5
    brotli_static on;
6
    proxy_max_temp_file_size 0;
7
    client_max_body_size 1m;
8
    include /tmp/nginx/security-headers.conf;
9
    # ...
10

11
    location ~ ^/api/v[12]/admin/upload$ {
12
        proxy_pass http://rctf_api;
13
        client_max_body_size 0;
14
        proxy_request_buffering off;
15
    }
16

17
    location = /api/v2/users/me/avatar {
18
        proxy_pass http://rctf_api;
19
        include /tmp/nginx/avatar-body-limit.conf;
20
    }
21

22
    location ~ ^/api/v[12]/admin/ {
23
        proxy_pass http://rctf_api;
24
        client_max_body_size 8m;
25
        proxy_request_buffering off;
26
    }
27

28
    location ~ ^/(api|uploads) {
29
        proxy_pass http://rctf_api;
30
    }
31

32
    location /_app/immutable/ {
33
        add_header Cache-Control "public, max-age=86400, immutable";
34
        include /tmp/nginx/security-headers.conf;
35
        try_files $uri $uri/ /index.html;
36
    }
37

38
    location / {
39
        try_files $uri $uri/ /index.html;
40
    }
41
}

Content Security Policy

CSP is generated in two places. SvelteKit writes a <meta http-equiv="Content-Security-Policy"> tag into each page, including hashes for the generated scripts. At container startup, rctf deployment generate-csp extracts all directives from the built index.html, merges and deduplicates them with the configured upload, captcha, and analytics provider rules, and emits a nginx Content-Security-Policy response header. Startup fails if the built policy cannot be read.

1
csp: dev
2
  ? undefined
3
  : {
4
      directives: {
5
        'script-src': [
6
          'self',
7
          // captcha script origins
8
          // ...
9
        ],
10
      },
11
    },

Together, the build-time and runtime policies contain the following sources. The generated nginx policy starts with the base sources below and adds only those required by the active providers:

Provider-specific style-src, connect-src, and frame-src sources are selected at runtime, so disabled providers are excluded from the nginx policy. For R2, connect-src uses the configured publicBaseUrl. Captcha script origins remain build-time entries because SvelteKit owns the generated script hashes.

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, R2, or GCS for non-local upload provider. 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-operator 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.