Front Flask and the Vue SPA with a Caddy frontend-proxy on port 8000

Adds a new frontend-proxy service (multi-stage Dockerfile: node builder
stage compiles the SPA bundle; caddy:2-alpine runtime stage serves it)
that terminates the host HTTP port and fans out over the existing
web-host network:

  /spa/*     -> spa-frontend:5173 (vite dev) in dev, baked /srv/spa-dist
               via file_server in prod
  /static/*  -> webapp/ref/static bind-mount served directly by Caddy
  /admin, /admin/ -> 302 to /admin/exercise/view
  /spa -> 308 /spa/
  everything else -> reverse_proxy web:8000 (X-Tinyproxy set from
               remote_host so the rate limiter keys on real client IP)

Dev/prod Caddyfiles are selected at container start via entrypoint.sh
based on $HOT_RELOADING. Prod adds Cache-Control headers: immutable +
long max-age on /spa/assets/*, no-cache on the SPA HTML fallback, 1h on
Flask static assets. Caddy's reverse_proxy auto-upgrades Vite's HMR
websocket for /spa/@vite/client.

The SPA URL prefix moves from /v2 to /spa (vite base, router history,
Flask landing redirects). The /api/v2/* JSON API path is unchanged.

The spa-frontend service is gated behind the 'dev' compose profile so
it only starts when hot-reloading is active; ctrl.sh exports
COMPOSE_PROFILES=dev by default and clears it in prod-mode up. The
prod-mode branch of spa-frontend/entrypoint.sh is now a hard error
since the prod bundle is baked into the frontend-proxy image.

web and spa-frontend no longer publish host ports; the test harness
maps frontend-proxy:8000 instead. SPA_HOST_PORT is removed from
settings.yaml/env and prepare.py. A repo-root .dockerignore keeps the
frontend-proxy build context lean.

UI:
- SPA DefaultLayout app bar gets an unobtrusive mdi-shield-account-outline
  icon button linking to /admin.
- Admin navbar gains a "Student View" link (school icon + label) with a
  pipe separator from the user name/logout group.
- Admin navbar brand (logo + course name) now links to the exercise view
  instead of the SPA landing.

Author: Nils Bars

.claude/CLAUDE.md

@@ -162,7 +162,7 @@ REF is a containerized platform for hosting programming exercises with isolated
    - `ref/model/` - SQLAlchemy models (users, groups, exercises, instances, submissions, grades, system settings)
    - `ref/core/` - Business logic managers (`ExerciseManager`, `InstanceManager`, `ExerciseImageManager`, `UserManager`, `DockerClient`, etc.)
 
-   Student-facing pages (registration, restore-key, public scoreboard) are served by the Vue SPA under `/v2/*` and talk to `ref/frontend_api/`. Admin pages live under `ref/view/` as Jinja-rendered HTML.
+   Student-facing pages (registration, restore-key, public scoreboard) are served by the Vue SPA under `/spa/*` and talk to `ref/frontend_api/`. Admin pages live under `ref/view/` as Jinja-rendered HTML. The Caddy `frontend-proxy` container fronts both on a single host port 8000 — it reverse-proxies `/spa/*` to `spa-frontend:5173` (dev, with HMR) or serves a baked SPA bundle (prod), serves Flask's `/static/*` directly, and proxies everything else to `web:8000`.
 
 2. **SSH Reverse Proxy** (`ssh-reverse-proxy/`) - Rust-based SSH proxy on port 2222
    - Routes student SSH connections to exercise containers

.dockerignore

@@ -0,0 +1,27 @@
+**/.git
+**/node_modules
+**/__pycache__
+**/*.pyc
+**/.venv
+**/.mypy_cache
+**/.ruff_cache
+**/.pytest_cache
+
+ref-linux/
+data/
+backup_exercises/
+ref-exercises/
+.docker-cache/
+
+tests/
+tests/failure_logs/
+
+webapp/ref_webapp.egg-info/
+
+.codex/
+.claude/
+
+docs/
+*.md
+
+spa-frontend/dist/

README.md

@@ -184,4 +184,4 @@ The following features are disabled by default and can be enabled from the admin
 Allows students to be organized into named groups with a configurable maximum size. Students pick a group during registration, and admins can manage the available groups and reassign students afterwards. Enable via the `GROUPS_ENABLED` setting and configure the per-group capacity via `GROUP_SIZE`.
 
 #### Scoreboard
-A public leaderboard at `/v2/scoreboard` that ranks students based on their exercise submissions using a Formula 1 style, time-weighted strategy. Exercises can be grouped into assignments. Enable via `SCOREBOARD_ENABLED`; optionally set `LANDING_PAGE` to `scoreboard` to use it as the default landing page.
+A public leaderboard at `/spa/scoreboard` that ranks students based on their exercise submissions using a Formula 1 style, time-weighted strategy. Exercises can be grouped into assignments. Enable via `SCOREBOARD_ENABLED`; optionally set `LANDING_PAGE` to `scoreboard` to use it as the default landing page.

ctrl.sh

@@ -276,6 +276,13 @@ if [[ -z "$HTTP_HOST_PORT" ]]; then
     exit 1
 fi
 
+# The spa-frontend service is gated behind the `dev` compose profile so it
+# is only started when --hot-reloading is active. Activate the profile for
+# every ctrl.sh subcommand so profile-gated services can still be
+# built/stopped/inspected; the `up` function unsets this again for prod
+# mode so spa-frontend does not get started there.
+export COMPOSE_PROFILES=dev
+
 if [[ -z "$SECRET_KEY" ]]; then
     error "Please set SECRET_KEY in $ENV_SETTINGS_FILE to a random string"
     exit 1
@@ -422,6 +429,12 @@ function up {
         esac
     done
 
+    if [[ "$HOT_RELOADING" != "true" ]]; then
+        # Prod mode: skip the profile-gated spa-frontend service. Caddy
+        # serves the baked SPA bundle from the frontend-proxy image.
+        unset COMPOSE_PROFILES
+    fi
+
     execute_cmd $DOCKER_COMPOSE -p ref --env-file $ENV_SETTINGS_FILE up "$@"
 }
 

docker-compose.template.yml

@@ -101,10 +101,6 @@ services:
             - coverage-data:/coverage-data:rw
             - ./coverage:/coverage-config:ro
 {% endif %}
-        {% if not testing %}
-        ports:
-            - "${HTTP_HOST_PORT}:8000"
-        {% endif %}
         networks:
             - web-host
             - web-and-ssh
@@ -113,16 +109,53 @@ services:
             - db
         cgroup_parent: "{{ cgroup_parent }}-core.slice"
 
-    # Vue 3 + Vuetify SPA that serves the student-facing pages under /v2/
-    # (registration, restore-key, scoreboard). In dev (HOT_RELOADING=true)
-    # runs `vite dev` with HMR against the host bind-mounted source;
-    # otherwise runs `vite build && vite preview`. Either way the
-    # container's port 5173 is mapped to SPA_HOST_PORT on the host, and
-    # Vite's proxy forwards /api, /student/download, and /static to the
-    # web container over the web-host network.
+    # Caddy reverse proxy that fronts the whole web interface on a single
+    # host port. Routes /spa/* to the SPA (vite dev in dev mode, baked
+    # static bundle in prod) and /static/* directly from webapp/ref/static;
+    # everything else is reverse-proxied to the Flask web container. The
+    # SPA build artifact is baked into this image at docker build time via
+    # a multi-stage Dockerfile, so prod does not need `vite preview` or a
+    # shared volume. Dev selection is done at container start by
+    # entrypoint.sh based on $HOT_RELOADING.
+    frontend-proxy:
+        init: true
+        hostname: frontend-proxy
+        build:
+            context: .
+            dockerfile: frontend-proxy/Dockerfile
+        environment:
+            - HOT_RELOADING=${HOT_RELOADING:-false}
+        volumes:
+            # Serve Flask's static assets directly from Caddy, skipping
+            # uWSGI. Read-only to keep the proxy sandboxed.
+            - ./webapp/ref/static:/srv/flask-static:ro
+    {% if not testing %}
+        ports:
+            - "${HTTP_HOST_PORT}:8000"
+    {% endif %}
+        networks:
+            - web-host
+        depends_on:
+            - web
+        cgroup_parent: "{{ cgroup_parent }}-core.slice"
+        healthcheck:
+            test: ["CMD", "wget", "-q", "--spider", "http://localhost:8000/static/favicon.ico"]
+            interval: 10s
+            timeout: 3s
+            retries: 5
+            start_period: 5s
+
+    # Vue 3 + Vuetify SPA dev server. Only started in the `dev` compose
+    # profile (ctrl.sh adds --profile dev when --hot-reloading is set).
+    # In dev it runs `vite dev` with HMR against the host bind-mounted
+    # source; frontend-proxy reverse-proxies /spa/* to this container's
+    # port 5173 (including Vite's HMR websocket). In prod this service
+    # is not started at all — frontend-proxy serves the baked SPA bundle.
     spa-frontend:
         init: true
         hostname: spa-frontend
+        profiles:
+            - dev
         build:
             context: ./spa-frontend
         environment:
@@ -133,10 +166,6 @@ services:
             # so deps installed at build time remain available.
             - ./spa-frontend/:/spa-frontend
             - /spa-frontend/node_modules
-    {% if not testing %}
-        ports:
-            - "${SPA_HOST_PORT:-5173}:5173"
-    {% endif %}
         networks:
             - web-host
         depends_on:

docs/ARCHITECTURE.md

@@ -5,14 +5,32 @@ Remote Exercise Framework - A platform for hosting programming exercises with is
 ## System Overview
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                         HOST SYSTEM                             │
-├─────────────────────────────────────────────────────────────────┤
-│  Port 2222 ──> ssh-reverse-proxy (Rust) ──> Instance (SSH)      │
-│  Port 8000 ──> web (Flask) ──> Docker API ──> Instance Mgmt     │
-└─────────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────────┐
+│                            HOST SYSTEM                               │
+├──────────────────────────────────────────────────────────────────────┤
+│  Port 2222 ──> ssh-reverse-proxy (Rust) ──> Instance (SSH)           │
+│  Port 8000 ──> frontend-proxy (Caddy) ──┬─> web (Flask)              │
+│                                         ├─> spa-frontend (vite dev)  │
+│                                         └─> baked SPA dist/ (prod)   │
+└──────────────────────────────────────────────────────────────────────┘
 ```
 
+The `frontend-proxy` Caddy container terminates host port 8000 and routes
+traffic by URL prefix:
+
+- `/spa/*` — the Vue SPA. In dev (`--hot-reloading`) proxied to the
+  `spa-frontend` container running `vite dev` with HMR; in prod served as
+  a static bundle baked into the frontend-proxy image at build time via a
+  multi-stage Dockerfile.
+- `/static/*` — Flask's own static assets (bootstrap, ace-builds, favicon,
+  etc.), served directly by Caddy from a read-only bind-mount of
+  `webapp/ref/static/`.
+- Everything else (`/`, `/admin/*`, `/api/*`, `/student/*`) — reverse-proxied
+  to the Flask `web` container on the internal `web-host` network.
+
+The `ssh-reverse-proxy` still calls `http://web:8000` over the internal
+`web-and-ssh` network and does **not** go through Caddy.
+
 ## Components
 
 ### 1. Web Application (`webapp/`)
@@ -96,6 +114,35 @@ Isolated Docker container per student/exercise based on Ubuntu 24.04.
 
 **Entry point:** SSH server on port 13370
 
+### 2b. Frontend Proxy (`frontend-proxy/`)
+
+Caddy-based reverse proxy container that terminates host port 8000 and fans
+out to the Flask webapp and the Vue SPA. Built from a multi-stage
+Dockerfile that compiles the SPA bundle (stage 1: `node:22-alpine`,
+`npm run build`) and copies it into a `caddy:2-alpine` runtime image
+(stage 2). At container start, `entrypoint.sh` picks `Caddyfile.dev`
+(reverse-proxies `/spa/*` to `spa-frontend:5173` for HMR) or
+`Caddyfile.prod` (serves the baked `/srv/spa-dist` with SPA history-mode
+fallback) based on `$HOT_RELOADING`.
+
+**Stack:** Caddy 2 + multi-stage Node builder
+
+**Key files:**
+- `Dockerfile` — multi-stage SPA build + Caddy runtime
+- `Caddyfile.dev` — dev routing (proxies `/spa/*` to vite dev)
+- `Caddyfile.prod` — prod routing (serves baked dist with cache headers)
+- `entrypoint.sh` — selects config based on `HOT_RELOADING`
+
+**Notes:**
+- The Flask rate limiter reads `X-Tinyproxy` to key on the real client IP;
+  Caddy sets this header via `header_up X-Tinyproxy {remote_host}` on the
+  reverse-proxy path.
+- Flask static assets (`/static/*`) are served directly by Caddy with a 1h
+  cache header, skipping uWSGI.
+- SPA hashed assets (`/spa/assets/*`) are served with
+  `public, max-age=31536000, immutable`; `index.html` is `no-cache` so
+  deploys are picked up atomically.
+
 ### 3. SSH Reverse Proxy (`ssh-reverse-proxy/`)
 
 Rust-based SSH proxy routing student connections to their containers.
@@ -160,7 +207,7 @@ PostgreSQL 17.2 storing:
 
 | Network | Bridge Name | Type | Purpose |
 |---------|-------------|------|---------|
-| `web-host` | `br-whost-ref` | External | Web ↔ Host (HTTP access) |
+| `web-host` | `br-whost-ref` | External | frontend-proxy ↔ Host, frontend-proxy ↔ web, frontend-proxy ↔ spa-frontend |
 | `web-and-ssh` | `br-w2ssh-ref` | Internal | Web ↔ SSH reverse proxy API |
 | `web-and-db` | `br-w2db-ref` | Internal | Web ↔ PostgreSQL |
 | `ssh-and-host` | `br-shost-ref` | External | SSH reverse proxy ↔ Host |

docs/SCOREBOARD.md

@@ -1,6 +1,6 @@
 # Scoreboard
 
-A public leaderboard at `/v2/scoreboard` that ranks students/teams based
+A public leaderboard at `/spa/scoreboard` that ranks students/teams based
 on submission scores. Exercises are grouped into **assignments**
 (time-boxed rounds, one per `ExerciseConfig.category`). Each exercise
 has **per-task scoring policies** that transform the raw score of each

frontend-proxy/Caddyfile.dev

@@ -0,0 +1,33 @@
+{
+	admin off
+	auto_https off
+}
+
+:8000 {
+	log {
+		output stdout
+		format console
+	}
+
+	redir /spa /spa/ 308
+
+	# /admin and /admin/ have no Flask view of their own; route both to
+	# the exercise list (the first item in the admin navbar dropdown).
+	redir /admin /admin/exercise/view 302
+	redir /admin/ /admin/exercise/view 302
+
+	handle /spa/* {
+		reverse_proxy spa-frontend:5173
+	}
+
+	handle_path /static/* {
+		root * /srv/flask-static
+		file_server
+	}
+
+	handle {
+		reverse_proxy web:8000 {
+			header_up X-Tinyproxy {remote_host}
+		}
+	}
+}

frontend-proxy/Caddyfile.prod

@@ -0,0 +1,47 @@
+{
+	admin off
+	auto_https off
+}
+
+:8000 {
+	log {
+		output stdout
+		format console
+	}
+
+	redir /spa /spa/ 308
+
+	# /admin and /admin/ have no Flask view of their own; route both to
+	# the exercise list (the first item in the admin navbar dropdown).
+	redir /admin /admin/exercise/view 302
+	redir /admin/ /admin/exercise/view 302
+
+	handle_path /spa/* {
+		root * /srv/spa-dist
+
+		@immutable path /assets/*
+		header @immutable Cache-Control "public, max-age=31536000, immutable"
+
+		# Everything outside /assets/* is either index.html itself or a
+		# deep-link that try_files falls back to index.html. The header
+		# matcher evaluates against the current request path (before the
+		# try_files rewrite), so "not /assets/*" catches all of them.
+		@html not path /assets/*
+		header @html Cache-Control "no-cache"
+
+		try_files {path} {path}/ /index.html
+		file_server
+	}
+
+	handle_path /static/* {
+		root * /srv/flask-static
+		header Cache-Control "public, max-age=3600"
+		file_server
+	}
+
+	handle {
+		reverse_proxy web:8000 {
+			header_up X-Tinyproxy {remote_host}
+		}
+	}
+}

frontend-proxy/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:22-alpine AS spa-builder
+WORKDIR /build
+COPY spa-frontend/package.json spa-frontend/package-lock.json ./
+RUN npm ci
+COPY spa-frontend/ ./
+RUN npm run build
+
+FROM caddy:2.8-alpine
+COPY --from=spa-builder /build/dist /srv/spa-dist
+COPY frontend-proxy/Caddyfile.dev /etc/caddy/Caddyfile.dev
+COPY frontend-proxy/Caddyfile.prod /etc/caddy/Caddyfile.prod
+COPY frontend-proxy/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+ENTRYPOINT ["/entrypoint.sh"]