Skip to main content

Configuration and Deployment Runbook

Introduction​

This runbook documents local development, build, Docker runtime, Nginx behavior, runtime configuration, and common troubleshooting steps for the Ravenxcope frontend.

Local Development​

Install dependencies using Yarn (recommended for consistency with Docker):

yarn install --frozen-lockfile

Common Commands:

  • Dev Server: yarn dev
  • Build: yarn build
  • Lint: yarn lint

Equivalent npm commands may work locally, but production Docker builds strictly use Yarn.

Environment Variables​

Documented in .env.example:

VITE_API_BASE_URL=
VITE_ANALYTICS_AI_CHAT_ENABLED=false
VariableRequiredDefault / FallbackPurpose
VITE_API_BASE_URLRecommendedhttp://localhost:5009/apiBackend base URL
VITE_ANALYTICS_AI_CHAT_ENABLEDNofalseEnables analytics AI chat UI

For production, set these variables on the container so docker-entrypoint.sh can inject them.

Docker Build​

The Dockerfile uses a two-stage build:

  1. Builder Stage:

    • Uses node:22-alpine.
    • Installs dependencies with yarn install --frozen-lockfile.
    • Generates production assets with yarn build.

  2. Runtime Stage:

    • Uses nginx:alpine.
    • Serves assets from /usr/share/nginx/html.
    • Injects runtime configuration via docker-entrypoint.sh.
    • Exposes port 8000.

Runtime Config Injection​

At container startup, docker-entrypoint.sh writes variables into window.__APP_CONFIG__ before starting Nginx. This allows the same image to be deployed across different environments (Staging, Production) without rebuilds.

Nginx Behavior​

nginx/default.conf listens on port 8000 and provides:

  • Static Serving: Serves built assets with long-term caching.
  • Compression: Enables gzip for text and JSON assets.
  • Security: Adds X-Frame-Options, X-Content-Type-Options, and X-XSS-Protection.
  • SPA Fallback: Uses try_files $uri $uri/ /index.html to support client-side routing.
  • Config Freshness: Serves /config.js with no-cache headers.

Deployment Checklist​

Before deploying, verify the following:

  1. API Reachability: Backend API must be reachable from the user's browser.
  2. API Origin: VITE_API_BASE_URL should be the public backend origin without /api.
  3. Chat Status: VITE_ANALYTICS_AI_CHAT_ENABLED=true requires a configured backend chat endpoint.
  4. Port Mapping: Nginx port 8000 must be correctly routed.
  5. Config Verification: Confirm /config.js returns the expected runtime values.
  6. Route Fallback: Confirm deep-linked dashboard routes refresh correctly.

Troubleshooting​

Login requests go to localhost​

  • Cause: VITE_API_BASE_URL is missing or invalid.
  • Check: Verify /config.js content. It should be a valid http or https URL.

404 on dashboard refresh​

  • Cause: SPA fallback is inactive.
  • Check: Ensure nginx/default.conf is correctly mounted and contains the try_files directive.

Config changes not reflecting​

  • Cause: Browser or CDN caching of /config.js.
  • Check: Verify Cache-Control: no-store headers are present.

Auth redirects to login​

  • Possible Causes:
    • Missing or expired session cookies.
    • Backend returned 401.
    • API base URL mismatch.
    • SameSite cookie policy restrictions.
  • Check: Browser devtools for cookie presence and API response payloads.

Analytics AI chat is missing​

  • Possible Causes:
    • VITE_ANALYTICS_AI_CHAT_ENABLED is false.
    • Backend chat status endpoint is unreachable or reports disabled.
  • Check: /config.js and GET /api/analytics/chat/status.

Non-Goals​

This frontend image only serves the browser application and runtime config. It does not run backend services, databases, or sensor agents.