feat(offline): authenticated offline deployment (Keycloak overlay) (#563)

* feat(offline): optionally bundle Keycloak in pull-and-save-images

Prompt whether to include the Keycloak image when saving images for an
offline transfer, so authenticated offline deployments have the IdP
available. The tag is read from docker-compose.prod.yml so it never
drifts from the auth overlay; appending to the image list means both the
pull and save loops pick it up. Honours INCLUDE_KEYCLOAK=true|false to
skip the prompt (defaults to excluding on a non-TTY, so CI is unchanged).

The run summary notes that the image alone isn't enough to run auth
offline (realm export + auth-enabled compose/nginx still needed).

Refs #559

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix/keycloak-image-parse-exit-and-portable-case

Two review fixes on the Keycloak opt-in:
- Append `|| true` to the KEYCLOAK_IMAGE command substitution so a
  missing docker-compose.prod.yml or a no-match grep no longer exits the
  whole script under `set -euo pipefail` (want_keycloak already handles an
  empty tag gracefully).
- Replace the bash-4-only `${INCLUDE_KEYCLOAK,,}` with a portable
  case-insensitive `case` pattern.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(offline): add authenticated offline deployment (Keycloak overlay)

Add docker-compose.offline-prod.yml — the offline equivalent of the prod
auth overlay, using pre-built images instead of building from source. It
adds a Keycloak service (import-realm), turns on backend auth, and points
nginx at an auth-enabled frontend image.

pull-and-save-images.sh now, when Keycloak is included, also builds and
saves an auth-enabled nginx image (tracepcap-nginx-auth) with the
VITE_AUTH_* / VITE_OIDC_* build args, and the run summary points at the
new overlay + PUBLIC_URL. Document the flow in offline-deployment.rst.

This makes "save the Keycloak image" actually usable offline end to end.

Refs #559

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(offline): pass VITE_APP_VERSION, fix api base, persist keycloak

Address review + a smoke-test failure of the offline auth path:
- Pass VITE_APP_VERSION to both nginx builds (resolved via git describe).
  Without it the frontend build fails outright — vite.config.ts requires
  it and git describe isn't available inside the Docker builder.
- Default VITE_API_BASE_URL to /api/v1 (matches nginx/Dockerfile and the
  base compose) instead of /api, which routed the SPA to the wrong path.
- Parse the Keycloak image tag from docker-compose.offline-prod.yml (the
  file that actually runs offline) so the saved image can't drift from it.
- Add a persistent keycloak_data volume so users created in the admin
  console survive container recreate.
- Warn against a trailing slash in PUBLIC_URL in the offline docs.

Refs #559

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: NotYuSheng

docker-compose.offline-prod.yml

@@ -0,0 +1,74 @@
+# docker-compose.offline-prod.yml
+#
+# Offline + authentication overlay. Layers OIDC auth (a bundled Keycloak) on top of the
+# offline stack, using pre-built images loaded via scripts/load-images.sh — the offline
+# equivalent of docker-compose.prod.yml (which builds from source and cannot run air-gapped).
+#
+# Prerequisites:
+#   1. On an internet-connected machine, INCLUDE Keycloak when saving images:
+#          INCLUDE_KEYCLOAK=true bash scripts/pull-and-save-images.sh
+#      This saves the Keycloak image AND an auth-enabled frontend (tracepcap-nginx-auth).
+#   2. Transfer images/, this file, docker-compose.offline.yml, keycloak/realm-export.json,
+#      .env, and scripts/load-images.sh to the offline machine.
+#   3. On the offline machine:  bash scripts/load-images.sh
+#
+# Start (layer this file ON TOP of the base offline file):
+#   PUBLIC_URL=http://<host>:8888 \
+#     docker compose -f docker-compose.offline.yml -f docker-compose.offline-prod.yml up -d
+#
+# PUBLIC_URL must be the exact origin you browse to (scheme + host + port). It pins Keycloak's
+# token issuer and the backend's issuer check; the browser must load the app via this same
+# origin. It does NOT track NGINX_PORT — default is http://localhost:8888. See
+# docs/configuration/authentication.rst and docs/getting-started/offline-deployment.rst.
+#
+# Manage users at <PUBLIC_URL>/admin (Keycloak admin console, served same-origin by nginx).
+# Default demo login: analyst / analyst. Default Keycloak admin: user / P@ssw0rd — override
+# both for any real deployment.
+services:
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.0
+    container_name: tracepcap-keycloak
+    command: ["start-dev", "--import-realm"]
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: ${KEYCLOAK_ADMIN:-user}
+      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD:-P@ssw0rd}
+      # Public, browser-facing base URL — determines the token `iss` claim and all KC URLs.
+      KC_HOSTNAME: ${PUBLIC_URL:-http://localhost:8888}
+      # Trust X-Forwarded-* from the nginx proxy (same-origin reverse proxy in front of KC).
+      KC_PROXY_HEADERS: xforwarded
+      KC_HTTP_ENABLED: "true"
+      KC_HEALTH_ENABLED: "true"
+      TZ: Asia/Singapore
+    volumes:
+      - ./keycloak/realm-export.json:/opt/keycloak/data/import/realm-export.json:ro
+      # Persist Keycloak's embedded H2 store so accounts/credentials created at
+      # runtime in the admin console survive container restart/recreate. (The
+      # online prod overlay is ephemeral by the same start-dev design; persistence
+      # matters more offline, where re-provisioning users is manual.)
+      - keycloak_data:/opt/keycloak/data
+    networks:
+      - tracepcap-network
+
+  backend:
+    environment:
+      TRACEPCAP_AUTH_ENABLED: "true"
+      # Public issuer (matches the token `iss`). Must equal PUBLIC_URL + /realms/tracepcap.
+      KEYCLOAK_ISSUER_URI: ${PUBLIC_URL:-http://localhost:8888}/realms/tracepcap
+      # Backend-reachable JWKS endpoint (internal docker network), fetched lazily so the
+      # backend need not wait for Keycloak to be ready.
+      KEYCLOAK_JWK_SET_URI: http://keycloak:8080/realms/tracepcap/protocol/openid-connect/certs
+    depends_on:
+      keycloak:
+        condition: service_started
+
+  nginx:
+    # Auth-enabled frontend built by pull-and-save-images.sh when Keycloak is included.
+    # Overrides the plain tracepcap-nginx:latest from the base offline file.
+    image: tracepcap-nginx-auth:latest
+    depends_on:
+      - backend
+      - keycloak
+
+volumes:
+  keycloak_data:
+    driver: local

docs/getting-started/offline-deployment.rst

@@ -86,6 +86,49 @@ Step 3 — Load Images and Start the Stack (offline machine)
    # Start the stack using the offline compose file
    docker compose -f docker-compose.offline.yml up -d
 
+Authenticated Offline Deployment (Keycloak)
+-------------------------------------------
+
+The base offline stack runs with **no login**. To deploy offline *with* OIDC
+authentication, use the ``docker-compose.offline-prod.yml`` overlay — the
+offline equivalent of :doc:`../configuration/authentication` (which builds from
+source and so cannot run air-gapped).
+
+**Step 1 (online machine)** — include Keycloak when saving images:
+
+.. code-block:: bash
+
+   INCLUDE_KEYCLOAK=true bash scripts/pull-and-save-images.sh
+
+This additionally saves the Keycloak image and an **auth-enabled frontend**
+(``tracepcap-nginx-auth``) alongside the normal tarballs.
+
+**Step 2** — also transfer ``docker-compose.offline-prod.yml`` and
+``keycloak/realm-export.json`` (in addition to the files listed above).
+
+**Step 3 (offline machine)** — load images, then start with the auth overlay,
+setting ``PUBLIC_URL`` to the exact origin you browse to (scheme + host + port):
+
+.. code-block:: bash
+
+   bash scripts/load-images.sh
+
+   PUBLIC_URL=http://<host>:8888 \
+     docker compose -f docker-compose.offline.yml -f docker-compose.offline-prod.yml up -d
+
+.. warning::
+   ``PUBLIC_URL`` does **not** track ``NGINX_PORT`` (default
+   ``http://localhost:8888``). It pins Keycloak's token issuer and the backend's
+   issuer check, so the browser must load the app via this same origin. Do **not**
+   include a trailing slash (use ``http://<host>:8888``, not
+   ``http://<host>:8888/``) — it produces a double slash in the issuer URI and
+   breaks JWT validation.
+
+Create and manage logins at ``<PUBLIC_URL>/admin`` — see
+:doc:`../configuration/user-management`. The default demo login is
+``analyst`` / ``analyst`` and the default Keycloak admin is ``user`` /
+``P@ssw0rd``; **change both for any real deployment.**
+
 LLM Configuration for Offline Use
 ----------------------------------
 

scripts/pull-and-save-images.sh

@@ -24,6 +24,9 @@ IMAGES_DIR="$ROOT_DIR/images"
 
 BACKEND_IMAGE="tracepcap-backend:latest"
 NGINX_IMAGE="tracepcap-nginx:latest"
+# Auth-enabled frontend, built only when Keycloak is included. Kept as a separate
+# tag so the auth-off offline stack keeps using the plain nginx image unchanged.
+NGINX_AUTH_IMAGE="tracepcap-nginx-auth:latest"
 
 # ---------------------------------------------------------------------------
 # Helper
@@ -65,12 +68,13 @@ mapfile -t DOCKERHUB_IMAGES < <(
 )
 
 # Optionally include Keycloak, for an authenticated offline deployment. The image
-# tag is read from docker-compose.prod.yml (the auth overlay) so it never drifts.
+# tag is read from docker-compose.offline-prod.yml — the SAME file the offline host
+# starts — so the saved image can never drift from what the offline stack expects.
 # Appending to DOCKERHUB_IMAGES means the pull and save loops below both pick it
 # up automatically. Set INCLUDE_KEYCLOAK=true|false to skip the prompt (e.g. CI).
-PROD_COMPOSE="$ROOT_DIR/docker-compose.prod.yml"
+OFFLINE_PROD_COMPOSE="$ROOT_DIR/docker-compose.offline-prod.yml"
 KEYCLOAK_IMAGE="$(
-  grep -E '^[[:space:]]*image:[[:space:]]*.*keycloak' "$PROD_COMPOSE" 2>/dev/null | \
+  grep -E '^[[:space:]]*image:[[:space:]]*.*keycloak' "$OFFLINE_PROD_COMPOSE" 2>/dev/null | \
   sed -E 's/^[[:space:]]*image:[[:space:]]*"?([^" #]+)"?.*/\1/' | head -n1 || true
 )"
 
@@ -115,15 +119,37 @@ docker build \
   -t "$BACKEND_IMAGE" \
   ./backend
 
+# vite.config.ts REQUIRES a version at build time and falls back to `git describe`,
+# which is unavailable inside the Docker builder (no .git in the build context) —
+# so resolve it here (git works in this checkout) and pass it explicitly, else the
+# frontend build fails. Override by exporting VITE_APP_VERSION.
+VITE_APP_VERSION="${VITE_APP_VERSION:-$(git -C "$ROOT_DIR" describe --tags --always --dirty 2>/dev/null || echo "offline-build")}"
+
 echo "  Building nginx (frontend)..."
 docker build \
-  --build-arg "VITE_API_BASE_URL=${VITE_API_BASE_URL:-/api}" \
+  --build-arg "VITE_API_BASE_URL=${VITE_API_BASE_URL:-/api/v1}" \
   --build-arg "VITE_SUPPORTED_FILE_TYPES=${VITE_SUPPORTED_FILE_TYPES:-.pcap,.pcapng,.cap}" \
   --build-arg "VITE_NETWORK_DIAGRAM_CONVERSATION_LIMIT=${VITE_NETWORK_DIAGRAM_CONVERSATION_LIMIT:-false}" \
+  --build-arg "VITE_APP_VERSION=${VITE_APP_VERSION}" \
   -t "$NGINX_IMAGE" \
   -f ./nginx/Dockerfile \
   .
 
+if [ "$SAVE_KEYCLOAK" = "1" ]; then
+  echo "  Building nginx (frontend, auth-enabled)..."
+  docker build \
+    --build-arg "VITE_API_BASE_URL=${VITE_API_BASE_URL:-/api/v1}" \
+    --build-arg "VITE_SUPPORTED_FILE_TYPES=${VITE_SUPPORTED_FILE_TYPES:-.pcap,.pcapng,.cap}" \
+    --build-arg "VITE_NETWORK_DIAGRAM_CONVERSATION_LIMIT=${VITE_NETWORK_DIAGRAM_CONVERSATION_LIMIT:-false}" \
+    --build-arg "VITE_APP_VERSION=${VITE_APP_VERSION}" \
+    --build-arg "VITE_AUTH_ENABLED=true" \
+    --build-arg "VITE_OIDC_CLIENT_ID=tracepcap-frontend" \
+    --build-arg "VITE_OIDC_REALM=tracepcap" \
+    -t "$NGINX_AUTH_IMAGE" \
+    -f ./nginx/Dockerfile \
+    .
+fi
+
 # ---------------------------------------------------------------------------
 # 3. Save all images as tars
 # ---------------------------------------------------------------------------
@@ -136,6 +162,9 @@ for img in "${DOCKERHUB_IMAGES[@]}"; do
 done
 save_image "$BACKEND_IMAGE" "tracepcap-backend.tar"
 save_image "$NGINX_IMAGE"   "tracepcap-nginx.tar"
+if [ "$SAVE_KEYCLOAK" = "1" ]; then
+  save_image "$NGINX_AUTH_IMAGE" "tracepcap-nginx-auth.tar"
+fi
 
 # ---------------------------------------------------------------------------
 # Summary
@@ -154,11 +183,16 @@ echo "  bash scripts/load-images.sh"
 echo "  docker compose -f docker-compose.offline.yml up -d"
 echo ""
 if [ "$SAVE_KEYCLOAK" = "1" ]; then
-  echo "Keycloak image was saved. To run auth offline you must ALSO transfer:"
+  echo "Keycloak (auth) was included. To run authenticated offline, ALSO transfer:"
+  echo "  docker-compose.offline-prod.yml"
   echo "  keycloak/realm-export.json"
-  echo "and start with an auth-enabled compose (add the Keycloak service + auth env,"
-  echo "and rebuild nginx with the VITE_AUTH_* args). Saving the image alone is not"
-  echo "enough — see docs/configuration/authentication.rst."
+  echo ""
+  echo "and start with the auth overlay, setting PUBLIC_URL to the exact origin"
+  echo "you browse to (scheme + host + port):"
+  echo "  PUBLIC_URL=http://<host>:8888 \\"
+  echo "    docker compose -f docker-compose.offline.yml -f docker-compose.offline-prod.yml up -d"
+  echo ""
+  echo "Then manage users at <PUBLIC_URL>/admin — see docs/configuration/user-management.rst."
   echo ""
 fi
 echo "To refresh nDPI: rebuild the backend image (it installs the latest nDPI),"