Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
fix(deploy): make the console's endpoints runtime-configurable and a single host reachable (#888)
Beenu Arorab2cca25e2ed2
diff --git a/.env.example b/.env.exampleindex 856bba930..53eef26b3 100644--- a/.env.example+++ b/.env.example@@ -49,6 +49,33 @@ SECRET_KEY=# credential arrives with the wrong URL beside it.AISOC_CONSOLE_URL=http://localhost:3000+# ─── Where the stack is reachable from ────────────────────────────────────────+# Every host port is published to 127.0.0.1 by default, which is right for a+# laptop and fatal for a server: nothing outside the machine can reach it,+# including the browser you meant to use.+#+# Set this to publish the console on all interfaces. It is the only port a+# browser needs — the console proxies to the API, the agents service and the+# realtime gateway over the internal network — so the datastores and the+# development passwords in this file stay on loopback.+#+# AISOC_CONSOLE_BIND_ADDR=0.0.0.0+#+# Put a TLS-terminating reverse proxy in front before exposing it to a network+# you do not control. See apps/docs/docs/deployment/single-host.md.+# AISOC_CONSOLE_BIND_ADDR=0.0.0.0++# Moves EVERY published port, datastores included. Only for an isolated+# network: it hands Postgres, Redis, Kafka and Neo4j — with the development+# passwords in this file — to anything that can route to the host.+# AISOC_BIND_ADDR=0.0.0.0++# Whether this deployment is a demo. Read at run time by both the API and the+# console, and reported at GET /api/runtime-config so it can be checked from+# outside rather than inferred from the page. Leave false unless you are+# running a public demo; `make demo` is the opt-in that loads synthetic data.+AISOC_DEMO_MODE=false+# Shared HS256 secret used ONLY for short-lived realtime WS/SSE tickets# (Issue #239). The API mints tickets at `POST /api/v1/realtime/ticket` and the# Node realtime service (`services/realtime`) verifies them on every WebSocket@@ -286,9 +313,32 @@ AZURE_RESOURCE_GROUP=AZURE_WORKSPACE_NAME=# ─── Frontend ─────────────────────────────────────────────────────────────────-NEXT_PUBLIC_API_URL=http://localhost:8000-NEXT_PUBLIC_REALTIME_URL=http://localhost:8086-NEXT_PUBLIC_WS_URL=ws://localhost:8086+# Where the console proxies browser requests. The browser itself never uses+# these: the bundle calls same-origin paths like /api/v1/alerts and the Next.js+# server forwards them, which is why one image works on localhost, on a LAN+# address and behind a reverse proxy without rebuilding, and why there is no+# CORS configuration to get wrong.+#+# The defaults are the Compose service names and are right for the bundled+# stack. Change them when the API lives somewhere else — a different Compose+# project, another host, or an existing deployment.+AISOC_API_URL=http://api:8000+AISOC_AGENTS_URL=http://agents:8084+AISOC_REALTIME_URL=http://realtime:4000++# NEXT_PUBLIC_* is NOT listed here on purpose.+#+# Next.js inlines every NEXT_PUBLIC_* value into the JavaScript bundle when the+# image is *built*, so setting one in this file has no effect on the image+# `docker compose up` pulls. This file used to list NEXT_PUBLIC_API_URL,+# NEXT_PUBLIC_REALTIME_URL and NEXT_PUBLIC_WS_URL, which meant an operator+# pointing the console at their own host edited three variables, restarted,+# saw no change, and had nothing telling them the settings were inert. Use the+# three AISOC_*_URL values above; they are read at container start.+#+# To bypass the proxy and have the browser call another origin directly you+# have to rebuild the image with --build-arg NEXT_PUBLIC_API_URL=… and take on+# the CORS configuration that comes with it.# Override the docs site base URL (default: https://beenuar.github.io/AiSOC/docs).# Set this when serving docs from a custom domain like https://docs.tryaisoc.com/docs.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ac36d68cc..8593fcaa4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Fixed++- **The console's API and realtime addresses are now read when the container+ starts, so a deployment that is not a laptop can be pointed at its own+ services.** Reported by a self-hoster bringing AiSOC up with Compose on a+ single host: setting the documented variables changed nothing. It could not+ have — `next build` freezes *both* halves of the console's routing. Anything+ prefixed `NEXT_PUBLIC_` is inlined into the JavaScript bundle as a string+ literal, and the destinations returned by `rewrites()` in `next.config.js`+ are compiled into `.next/routes-manifest.json`. `next start` loads the+ config again and logs that it did, which makes this look configurable, but+ production routing is served from the manifest. A pulled image could+ therefore only ever talk to the hosts it was built against.++ It worked on the bundled Compose stack by coincidence: the baked+ `http://api:8000` happens to be that service's DNS name on that network.+ Any other topology resolved a hostname that does not exist, and no variable+ could re-point it.++ `apps/web/docker-entrypoint.sh` now re-evaluates `rewrites()` against the+ container's environment and writes the result into the manifest before the+ server starts. `next.config.js` stays the single definition of the routing+ table — the resolver duplicates no route — so `AISOC_API_URL`,+ `AISOC_AGENTS_URL` and `AISOC_REALTIME_URL` take effect on a pulled image+ with no rebuild. An address that is set and cannot be applied stops the+ container and names itself rather than starting on the built-in defaults,+ because a console silently pointed at the wrong host is worse than one that+ refuses to boot.++ The browser needs no absolute URL at all and did not need one before: the+ bundle calls same-origin paths and this server forwards them, which is why+ one image works on `localhost`, on a LAN address and behind a reverse proxy,+ and why there is no CORS surface to configure. `docker-compose.yml` no+ longer sets `NEXT_PUBLIC_API_URL` and `NEXT_PUBLIC_WS_URL` on the `web`+ service, where they were read by nothing while looking like the knob an+ operator was meant to turn.++- **A single-host deployment can be reached.** Every host port published to a+ literal `127.0.0.1`, so the stack came up healthy and nothing outside the+ machine could reach it — including the browser it was meant to be used from+ — and nothing in `.env` could change that. `AISOC_CONSOLE_BIND_ADDR`+ publishes the console, and `AISOC_BIND_ADDR` moves every binding for an+ isolated network. Both default to loopback, so a laptop install still+ exposes nothing by omission.++ The console gets its own knob because same-origin proxying means one port is+ enough: exposing AiSOC to a LAN no longer means handing out Postgres, Redis,+ Kafka and Neo4j with the development passwords this repository ships.++- **The Helm chart pointed the console at hostnames that do not exist in a+ cluster.** It set no upstream addresses on the web Deployment at all, while+ the published image dials `http://api:8000`; the chart's Services are+ `<release>-api`, `<release>-agents` and `<release>-realtime`. Every console+ request resolved nowhere, so the page loaded and every panel stayed empty.+ The three addresses are now derived from the release's own Services, and+ `services.web.env` overrides them for an API outside the release. This needs+ a console image carrying the runtime entrypoint above; an older image+ ignores them.++- **Demo mode has one authoritative answer, and it is visible.** Two flags+ decided it and neither could be reconciled from outside the container:+ `AISOC_DEMO_MODE` gated the API's seed at run time while the console read+ `NEXT_PUBLIC_DEMO_MODE`, compiled in at build time. The two could disagree,+ and `AppShell` wrapped the banner in `ClientOnly` to hide the resulting+ React hydration error rather than remove its cause. `AISOC_DEMO_MODE` now+ answers for both services and outranks the compiled value, the Server+ Component in `app/(app)/layout.tsx` resolves it once and hands it down so+ the two paints cannot differ, and `GET /api/runtime-config` reports the+ answer with the source that produced it (`runtime`, `build` or `default`)+ plus the version the image was built from. Checking whether a deployment+ thinks it is a demo no longer means inferring it from the rendered page —+ which was actively misleading, because the banner copy is an inlined+ constant present in the HTML either way.++### Added++- `apps/docs/docs/deployment/single-host.md` — the path for a server you reach+ over the network: publishing the console, pointing it at your services,+ confirming what the deployment thinks it is, and what changes on the way to+ Kubernetes.+- `tests/test_console_runtime_config_gate.py` — runs the real resolver against+ the real `next.config.js` and asserts an operator's chosen API address is+ the one the console proxies to, plus the deployment contract that carries+ it. All five fail against `v11.0.0`.+## [11.0.0] — 2026-09-25### BREAKINGdiff --git a/apps/docs/docs/deployment/env-vars.md b/apps/docs/docs/deployment/env-vars.mdindex 78dd0716e..23155355b 100644--- a/apps/docs/docs/deployment/env-vars.md+++ b/apps/docs/docs/deployment/env-vars.md@@ -412,15 +412,42 @@ All variables use the `PURPLE_TEAM_` prefix.## Web app (`apps/web`)-The Next.js frontend reads only public, build-time variables. Anything sensitive belongs in the API layer.+The console runs a Node process as well as serving a bundle, and the two read+their configuration at different times. Getting this backwards is why setting+"the right variables" on a self-hosted deployment could change nothing.++### Read when the container starts++Set these in `.env` or on the Deployment. They take effect on restart, with no+rebuild. They are the addresses the console's **server** proxies browser+requests to; the browser itself only ever talks to the console's own origin,+which is why there is no CORS to configure.| Variable | Default | Description ||----------|---------|-------------|-| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | Base URL the browser uses to reach the API |-| `NEXT_PUBLIC_REALTIME_URL` | `http://localhost:8086` | HTTP base of the realtime service (used for VAPID subscription registration) |-| `NEXT_PUBLIC_WS_URL` | `ws://localhost:8086` | WebSocket URL for the realtime feed |+| `AISOC_API_URL` | `http://api:8000` | Core API the console proxies `/api/v1/*` to |+| `AISOC_AGENTS_URL` | `http://agents:8084` | Agents service (copilot, hunt, playbooks) |+| `AISOC_REALTIME_URL` | `http://realtime:4000` | Realtime gateway for `/ws/*` and `/sse` |+| `AISOC_DEMO_MODE` | `false` | Whether this deployment is a demo. Reported at `/api/runtime-config` |+| `AISOC_CONSOLE_BIND_ADDR` | `127.0.0.1` | Interface the console's host port publishes on |+| `AISOC_BIND_ADDR` | `127.0.0.1` | Interface **every** host port publishes on, datastores included |++### Fixed when the image is built++`NEXT_PUBLIC_*` values are inlined into the JavaScript bundle by `next build`.+Setting one on a container running a pulled image does nothing — it is not+read at run time by anything. Change them with `--build-arg` and a rebuild, or+leave them empty and let same-origin proxying handle it, which is the default.++| Build arg | Default | Description |+|-----------|---------|-------------|+| `NEXT_PUBLIC_API_URL` | *(empty)* | Absolute API origin for the browser. Empty means same-origin; setting it opts into configuring CORS |+| `NEXT_PUBLIC_WS_URL` | *(empty)* | Absolute WebSocket origin. Empty derives it from the page's own origin |+| `NEXT_PUBLIC_DEMO_MODE` | *(empty)* | Compiles the image as a demo build. `AISOC_DEMO_MODE` overrides it at run time || `NEXT_PUBLIC_VAPID_PUBLIC_KEY` | — | Must match the realtime service's `VAPID_PUBLIC_KEY` |+See [Single-host deployment](./single-host.md) for the whole path end to end.+---## CORS configuration@@ -526,8 +553,15 @@ PURPLE_TEAM_DATABASE_URL=${DATABASE_URL}PURPLE_TEAM_CALDERA_API_KEY=...# --- Web ----NEXT_PUBLIC_API_URL=http://localhost:8000-NEXT_PUBLIC_REALTIME_URL=ws://localhost:8086+# Where the console's server proxies to. Read at container start, so these+# work on a pulled image; NEXT_PUBLIC_* would not, being compiled into the+# bundle at build time.+AISOC_API_URL=http://api:8000+AISOC_AGENTS_URL=http://agents:8084+AISOC_REALTIME_URL=http://realtime:4000+# Publish the console beyond loopback. Required on any host you browse to+# from another machine; put TLS in front of it.+AISOC_CONSOLE_BIND_ADDR=0.0.0.0NEXT_PUBLIC_VAPID_PUBLIC_KEY=${VAPID_PUBLIC_KEY}```diff --git a/apps/docs/docs/deployment/single-host.md b/apps/docs/docs/deployment/single-host.mdnew file mode 100644index 000000000..7a9cd45d4--- /dev/null+++ b/apps/docs/docs/deployment/single-host.md@@ -0,0 +1,151 @@+---+id: single-host+title: Single-host deployment+sidebar_label: Single host+---++# Running AiSOC on one server++This is the path for a server you reach over the network — a VM, a NUC in a+rack, a cloud instance — as opposed to `make up` on a laptop. It is also the+usual step before moving to Kubernetes.++Two things differ from a laptop install, and both are deliberate choices you+have to make rather than defaults you inherit.++## 1. Publish the console++Every host port ships bound to `127.0.0.1`. That is correct for a laptop and+useless for a server: the stack comes up healthy and nothing outside the+machine can reach it, including the browser you intended to use.++One variable changes that:++```bash+# .env+AISOC_CONSOLE_BIND_ADDR=0.0.0.0+```++The console is the **only** port a browser needs. The bundle it serves calls+same-origin paths — `/api/v1/alerts`, `/ws/…` — and the Next.js server+forwards them to the API, the agents service and the realtime gateway over the+internal Docker network. Publishing one port therefore exposes one service,+and Postgres, Redis, Kafka and Neo4j stay on loopback with the development+passwords this repository ships in `.env.example`.++```bash+docker compose up -d+curl http://<your-host>:3000/api/health # {"status":"ok"}+```++:::warning Put TLS in front of it+`0.0.0.0` means every interface the host has. On anything that is not a+trusted network, terminate TLS in a reverse proxy (nginx, Caddy, Traefik,+Cloudflare Tunnel) and point it at `127.0.0.1:3000` instead of publishing the+console directly. Sessions are bearer tokens; over plain HTTP they are+readable by anything on the path.+:::++There is a second variable, `AISOC_BIND_ADDR`, which moves **every** binding+including the datastores. It exists for an isolated network where you want+`psql` from another machine. On a routable network it hands out the shipped+development passwords, so rotate them first, or leave it alone and use an SSH+tunnel.++### Also set the console's own address++`make bootstrap` prints the URL to sign in at, and it defaults to+`http://localhost:3000`, which is the wrong instruction on a server:++```bash+# .env+AISOC_CONSOLE_URL=http://aisoc.internal:3000+```++## 2. Point the console at your services++If you run the bundled `docker-compose.yml` unchanged you can skip this —+the defaults already name the Compose services.++If your API lives somewhere else — a different Compose project, a separate+host, an existing deployment — set the addresses the console proxies to:++```bash+# .env+AISOC_API_URL=http://api.internal:8000+AISOC_AGENTS_URL=http://agents.internal:8084+AISOC_REALTIME_URL=http://realtime.internal:4000+```++These are read when the container starts. You do not need to rebuild the+image, and there is no CORS configuration, because the browser never talks to+these addresses — only the console's Node process does.++:::danger `NEXT_PUBLIC_*` cannot do this+Next.js inlines every `NEXT_PUBLIC_*` value into the JavaScript bundle when the+image is **built**. Setting `NEXT_PUBLIC_API_URL` on a container running a+*pulled* image is read by nothing, changes nothing, and reports nothing.++If you find that advice elsewhere, it predates this page. Use the+`AISOC_*_URL` variables above. To make the browser call a different origin+directly you have to rebuild:+`docker compose build --build-arg NEXT_PUBLIC_API_URL=https://api.example.com web`+— and then configure CORS on the API, which same-origin proxying exists to+avoid.+:::++## 3. Confirm what the deployment thinks it is++```bash+curl http://<your-host>:3000/api/runtime-config+```++```json+{ "demoMode": false, "demoModeSource": "runtime", "consoleVersion": "11.0.0" }+```++`demoMode` is the deployment's own answer rather than something to infer from+the page. `demoModeSource` says where it came from:++| `demoModeSource` | Meaning |+| --- | --- |+| `runtime` | `AISOC_DEMO_MODE` is set on the console container. |+| `build` | `NEXT_PUBLIC_DEMO_MODE` was compiled into the image; `AISOC_DEMO_MODE` is unset. |+| `default` | Neither is set. Not a demo. |++A `build` source on a self-hosted deployment means the image was built as a+demo. Set `AISOC_DEMO_MODE=false` to override it without rebuilding.++`consoleVersion` is the version the **image** was built from, which is not+necessarily the version of the repository you cloned: `latest` is a moving tag+and can lag a release. If it disagrees with `VERSION`, pull:++```bash+docker compose pull && docker compose up -d+```++The Compose file uses `pull_policy: missing`, so an image already on the host+is never refreshed on its own — a host that first pulled `latest` months ago+keeps running that build until you pull explicitly.++## Moving to Kubernetes++The Helm chart under `infra/helm/aisoc` sets the same three upstream addresses+on the console Deployment, derived from the release's own Services+(`<release>-api`, `<release>-agents`, `<release>-realtime`). Override them+through values when the API is outside the release:++```yaml+services:+ web:+ env:+ API_URL: http://api.aisoc.svc.cluster.local:80+```++This requires a console image built with the runtime entrypoint (AiSOC 11.1.0+or later). An older image ignores these variables and dials the addresses it+was built with — `http://api:8000` — which resolves to nothing in a cluster,+so the console loads and every panel stays empty.++Ingress hostnames, TLS and replica counts are covered in+[Kubernetes](./kubernetes.md).diff --git a/apps/docs/sidebars.ts b/apps/docs/sidebars.tsindex b0d2b375e..2d95f6553 100644--- a/apps/docs/sidebars.ts+++ b/apps/docs/sidebars.ts@@ -229,6 +229,7 @@ const sidebars: SidebarsConfig = {label: "Deployment",items: ["deployment/docker",+ "deployment/single-host","deployment/kubernetes","deployment/gcp","deployment/azure",diff --git a/apps/web/Dockerfile b/apps/web/Dockerfileindex 2767b7111..280cd015e 100644--- a/apps/web/Dockerfile+++ b/apps/web/Dockerfile@@ -131,9 +131,36 @@ RUN addgroup --system --gid 1001 nodejs && \# Copy the full workspace so symlinked workspace packages keep resolving.COPY --from=builder --chown=nextjs:nodejs /app ./+# ─── Runtime upstream addresses (server-side proxy) ─────────────────────────+# The same three values the builder stage used, re-declared because a new+# stage inherits no ENV from the one before it. They matter here for two+# reasons:+#+# 1. `docker inspect` now says what this image will proxy to, instead of the+# answer being locked inside .next/routes-manifest.json.+# 2. docker-entrypoint.sh re-evaluates next.config.js against this+# environment. Holding the build-time defaults means an unconfigured+# container resolves to exactly what was compiled in and re-points+# nothing — while `-e API_URL=…` now genuinely takes effect, which on a+# pulled image it previously could not.+#+# A `--build-arg` applies to every stage that declares the ARG, so an image+# built for a different topology keeps agreeing with itself here.+ARG API_URL=http://api:8000+ARG AGENTS_URL=http://agents:8084+ARG REALTIME_URL=http://realtime:4000+ENV API_URL=${API_URL}+ENV AGENTS_URL=${AGENTS_URL}+ENV REALTIME_URL=${REALTIME_URL}+USER nextjsEXPOSE 3000WORKDIR /app/apps/web+# Re-points the compiled rewrite table at the upstreams this container is+# started with, then execs CMD. Without it, API_URL and friends are inert on a+# pulled image — see apps/web/scripts/resolve-runtime-routes.mjs.+ENTRYPOINT ["/app/apps/web/docker-entrypoint.sh"]+# pnpm resolves the workspace's next binary correctly under symlinked layout.CMD ["pnpm", "start"]diff --git a/apps/web/docker-entrypoint.sh b/apps/web/docker-entrypoint.shnew file mode 100755index 000000000..00f29b923--- /dev/null+++ b/apps/web/docker-entrypoint.sh@@ -0,0 +1,19 @@+#!/bin/sh+# Console container entrypoint.+#+# Resolves the upstream addresses the Next.js server proxies to against the+# environment this container was *started* with, rather than the one the image+# was *built* with, then hands off to the real command.+#+# Without this step `API_URL`, `AGENTS_URL` and `REALTIME_URL` are inert on a+# pulled image: `next build` compiles rewrite destinations into+# .next/routes-manifest.json and `next start` serves routing from there. See+# scripts/resolve-runtime-routes.mjs for the full reasoning.+#+# `exec` so the Next.js server becomes PID 1 and receives SIGTERM directly —+# without it `docker stop` waits out the full timeout on every shutdown.+set -e++node "$(dirname "$0")/scripts/resolve-runtime-routes.mjs"++exec "$@"diff --git a/apps/web/scripts/resolve-runtime-routes.mjs b/apps/web/scripts/resolve-runtime-routes.mjsnew file mode 100755index 000000000..5606bd8d1--- /dev/null+++ b/apps/web/scripts/resolve-runtime-routes.mjs@@ -0,0 +1,154 @@+#!/usr/bin/env node+/**+ * Re-resolve the Next.js rewrite table from the live environment.+ *+ * WHY THIS EXISTS+ * ---------------+ * `next build` evaluates `rewrites()` once and compiles the results —+ * destinations included — into `.next/routes-manifest.json`. `next start`+ * loads `next.config.js` again (it prints "Running next.config.js took …"),+ * but production routing is served from that manifest, so the destinations+ * are build-time constants. Setting `API_URL` on a *pulled* image therefore+ * changes nothing, and the same is true of every `NEXT_PUBLIC_*` value, which+ * Next inlines into the JS bundle at build time.+ *+ * The practical result was that the console could only ever talk to the hosts+ * the image happened to be built with (`http://api:8000`, `http://agents:8084`,+ * `http://realtime:4000`). That is correct by coincidence on the bundled+ * Compose network, where the service DNS names match, and wrong everywhere+ * else — notably on Kubernetes, where the Services are `<release>-api` and the+ * baked hostname resolves to nothing at all.+ *+ * This script closes that gap: it re-evaluates `rewrites()` against the+ * current process environment and writes the resulting destinations back into+ * the manifest before the server starts. `next.config.js` stays the single+ * definition of the routing table — nothing here duplicates a route — so a+ * rewrite added later is picked up with no change to this file.+ *+ * Entries are matched on `source`, which is static in `next.config.js`; only+ * `destination` varies with the environment. The compiled `regex` is left+ * untouched because it is derived from `source`, which we never change.+ *+ * FAILURE POSTURE+ * ---------------+ * An operator who set an upstream variable and did not get it applied is+ * misconfigured in a way no retry clears, and booting anyway would serve a+ * console silently pointed at the wrong host. So: if an upstream variable is+ * set explicitly and cannot be applied, exit non-zero and name it. If nothing+ * was set, a manifest we cannot read is not worth refusing to boot over —+ * warn, and start on the built-in defaults.+ */++import { readFileSync, writeFileSync } from 'node:fs';+import { createRequire } from 'node:module';+import { dirname, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++const require = createRequire(import.meta.url);+const APP_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const MANIFEST = resolve(APP_DIR, '.next', 'routes-manifest.json');+const CONFIG = resolve(APP_DIR, 'next.config.js');++/**+ * The environment variables `next.config.js` reads to build destinations.+ * Used only to decide whether the operator asked for something specific —+ * the values themselves are read by the config, not by this script.+ */+const UPSTREAM_VARS = [+ 'API_URL',+ 'AGENTS_URL',+ 'REALTIME_URL',+ 'FUSION_URL',+ 'ENRICHMENT_URL',+ 'OSQUERY_TLS_URL',+];++const log = (msg) => process.stdout.write(`[runtime-routes] ${msg}\n`);+const warn = (msg) => process.stderr.write(`[runtime-routes] ${msg}\n`);++const explicit = UPSTREAM_VARS.filter((v) => (process.env[v] ?? '') !== '');++function fail(reason) {+ warn(`cannot apply ${explicit.join(', ')}: ${reason}`);+ warn('Refusing to start: the console would silently use the addresses this');+ warn('image was built with, not the ones you configured. Unset those');+ warn('variables to start on the built-in defaults.');+ process.exit(1);+}++function giveUp(reason) {+ if (explicit.length > 0) fail(reason);+ warn(`${reason} — starting on the addresses baked in at build time.`);+ process.exit(0);+}++/** Every rewrite bucket the manifest may carry, flattened to one list. */+function entriesOf(rewrites) {+ if (Array.isArray(rewrites)) return rewrites;+ if (rewrites && typeof rewrites === 'object') {+ return ['beforeFiles', 'afterFiles', 'fallback'].flatMap((k) =>+ Array.isArray(rewrites[k]) ? rewrites[k] : [],+ );+ }+ return [];+}++let manifest;+try {+ manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));+} catch (err) {+ giveUp(`could not read ${MANIFEST} (${err.message})`);+}++let desired;+try {+ const config = require(CONFIG);+ desired = entriesOf(await config.rewrites());+} catch (err) {+ giveUp(`could not evaluate rewrites() in next.config.js (${err.message})`);+}++const wanted = new Map(desired.map((r) => [r.source, r.destination]));+const baked = entriesOf(manifest.rewrites);++let changed = 0;+const origins = new Map();+for (const entry of baked) {+ const next = wanted.get(entry.source);+ if (typeof next !== 'string') continue;+ wanted.delete(entry.source);+ if (next === entry.destination) continue;+ entry.destination = next;+ changed += 1;+ try {+ origins.set(new URL(next).origin, true);+ } catch {+ /* relative destination — nothing to report as an origin */+ }+}++// A source the config emits now but the manifest never compiled cannot be+// added here: the manifest entry carries a `regex` that only `next build`+// produces. Say so rather than dropping it silently.+for (const source of wanted.keys()) {+ warn(+ `"${source}" is routed by next.config.js under this environment but was ` ++ 'not compiled into this image. Rebuild the image to enable it.',+ );+}++if (changed === 0) {+ log('upstream addresses already match the environment; nothing to re-point.');+ process.exit(0);+}++try {+ writeFileSync(MANIFEST, JSON.stringify(manifest));+} catch (err) {+ giveUp(`could not write ${MANIFEST} (${err.message})`);+}++log(+ `re-pointed ${changed} route${changed === 1 ? '' : 's'} to ` ++ `${[...origins.keys()].sort().join(', ')}`,+);diff --git a/apps/web/src/app/(app)/layout.tsx b/apps/web/src/app/(app)/layout.tsxindex 2fe029619..f049db72c 100644--- a/apps/web/src/app/(app)/layout.tsx+++ b/apps/web/src/app/(app)/layout.tsx@@ -1,5 +1,12 @@import { AppShell } from '@/components/layout/AppShell';+import { demoModeReport } from '@/lib/demoMode';+// A Server Component, which is what makes this the right place to answer+// "is this a demo". Server code reads the *running container's* environment,+// so `AISOC_DEMO_MODE` is visible here; the browser bundle only ever has the+// value that was compiled into it. Resolving once here and handing the answer+// down means the shell and the banner cannot disagree with the server — which+// they previously could, and did, as React hydration error #418.export default function AppLayout({ children }: { children: React.ReactNode }) {- return <AppShell>{children}</AppShell>;+ return <AppShell demoMode={demoModeReport().enabled}>{children}</AppShell>;}diff --git a/apps/web/src/app/api/runtime-config/route.ts b/apps/web/src/app/api/runtime-config/route.tsnew file mode 100644index 000000000..df68d2338--- /dev/null+++ b/apps/web/src/app/api/runtime-config/route.ts@@ -0,0 +1,43 @@+// What this deployment believes about itself, answered at request time.+//+// Two things about a console were previously impossible to check from+// outside it. Whether it considers itself a demo was decided by+// NEXT_PUBLIC_DEMO_MODE, which Next inlines when the image is built, so the+// only way to read it was to look at the rendered page and infer — and the+// banner copy is an inlined constant present in the HTML either way, which+// makes grepping for it actively misleading. And the version the bundle was+// built from is not the version of the repository an operator cloned:+// `latest` lags, so "which code am I running" had no answer either.+//+// `export const dynamic` keeps this off the static-render path so the+// environment is read per request rather than frozen at build; `runtime` is+// nodejs because AISOC_DEMO_MODE is a plain server variable with no+// NEXT_PUBLIC_ prefix and the edge runtime would not see it.+//+// Deliberately says nothing about upstream addresses. Those are internal+// topology and this route is unauthenticated — the console has to answer+// before anyone signs in. The resolved upstreams are printed at container+// start by apps/web/docker-entrypoint.sh, which is where an operator looking+// for them already is.+import { NextResponse } from 'next/server';++import { demoModeReport } from '@/lib/demoMode';++export const dynamic = 'force-dynamic';+export const runtime = 'nodejs';++export function GET() {+ const demo = demoModeReport();++ return NextResponse.json(+ {+ demoMode: demo.enabled,+ // 'runtime' — AISOC_DEMO_MODE in this container.+ // 'build' — NEXT_PUBLIC_DEMO_MODE, fixed when the image was built.+ // 'default' — neither was set.+ demoModeSource: demo.source,+ consoleVersion: process.env.NEXT_PUBLIC_APP_VERSION ?? 'unknown',+ },+ { headers: { 'cache-control': 'no-store' } },+ );+}diff --git a/apps/web/src/components/demo/DemoBanner.tsx b/apps/web/src/components/demo/DemoBanner.tsxindex 84c21b755..4ed87d841 100644--- a/apps/web/src/components/demo/DemoBanner.tsx+++ b/apps/web/src/components/demo/DemoBanner.tsx@@ -15,8 +15,18 @@import { isDemoMode, demoBannerMessage } from '@/lib/demoMode';import { docs } from '@/lib/docs';-export function DemoBanner() {- if (!isDemoMode()) return null;+interface DemoBannerProps {+ /**+ * The deployment's answer, resolved server-side in `app/(app)/layout.tsx`+ * so it reflects the running container rather than the build. Falls back to+ * the compiled value when the banner is mounted outside that layout, as the+ * stories and tests do.+ */+ demoMode?: boolean;+}++export function DemoBanner({ demoMode }: DemoBannerProps = {}) {+ if (!(demoMode ?? isDemoMode())) return null;return (<divdiff --git a/apps/web/src/components/layout/AppShell.tsx b/apps/web/src/components/layout/AppShell.tsxindex ab17b6b7c..2645143f3 100644--- a/apps/web/src/components/layout/AppShell.tsx+++ b/apps/web/src/components/layout/AppShell.tsx@@ -14,12 +14,20 @@ import { isDemoMode } from '@/lib/demoMode';interface AppShellProps {children: React.ReactNode;+ /**+ * Resolved by the Server Component in `app/(app)/layout.tsx`, which can see+ * the running container's `AISOC_DEMO_MODE`. Passed in rather than read here+ * so server and client render the same value by construction. Optional so+ * the stories and tests that mount the shell directly keep working; those+ * run in the browser, where `isDemoMode()` is the only answer available.+ */+ demoMode?: boolean;}-export function AppShell({ children }: AppShellProps) {+export function AppShell({ children, demoMode }: AppShellProps) {// In demo mode the banner adds 36px (h-9) to the top, so push the main// content down to keep the TopBar from sliding underneath it.- const demo = isDemoMode();+ const demo = demoMode ?? isDemoMode();const topPadClass = demo ? 'pt-[100px]' : 'pt-16';return (@@ -51,15 +59,18 @@ export function AppShell({ children }: AppShellProps) {<TenantProvider><div className="min-h-screen bg-surface-base">{/*- DemoBanner reads `NEXT_PUBLIC_DEMO_MODE`, a build-time env var.- In development the client bundle can have a stale inlined value that- differs from the SSR process.env read, producing React hydration- error #418. Wrapping in ClientOnly defers the banner to after mount- so both paints see the same value (client-only, post-hydration).+ `demo` arrives as a prop from the Server Component above, so the SSR+ pass and the hydration pass render from the same value and the+ banner can be part of the first paint.++ It used to call `isDemoMode()` itself, which the server answered+ from `process.env` and the client from the value Next inlined at+ build time. When those disagreed the result was React hydration+ error #418, and the fix at the time was to defer the whole banner+ behind ClientOnly — which hid the mismatch rather than removing it,+ and cost a frame of layout shift on every demo page load.*/}- <ClientOnly>- <DemoBanner />- </ClientOnly>+ <DemoBanner demoMode={demo} /><Sidebar /><div className="md:ml-60"><TopBar demoOffset={demo} />diff --git a/apps/web/src/lib/demoMode.ts b/apps/web/src/lib/demoMode.tsindex 6dded1764..0550ae9b0 100644--- a/apps/web/src/lib/demoMode.ts+++ b/apps/web/src/lib/demoMode.ts@@ -33,13 +33,61 @@ const TRUTHY = new Set(['1', 'true', 'yes', 'on']);let _override: boolean | null = null;-/** Returns `true` when the build is the hosted demo. */-export function isDemoMode(): boolean {- if (_override !== null) return _override;- const v = process.env.NEXT_PUBLIC_DEMO_MODE?.toLowerCase().trim() ?? '';+/** Where the answer came from, so an operator never has to infer it. */+export type DemoModeSource =+ /** `AISOC_DEMO_MODE` in the running container. Outranks the compiled value. */+ | 'runtime'+ /** `NEXT_PUBLIC_DEMO_MODE`, fixed when the image was built. */+ | 'build'+ /** Neither was set. Not a demo. */+ | 'default'+ /** `__setDemoModeForTests` is in force. */+ | 'test-override';++function truthy(raw: string | undefined): boolean | null {+ const v = raw?.toLowerCase().trim() ?? '';+ if (v === '') return null;return TRUTHY.has(v);}+/**+ * The single authoritative answer to "is this deployment a demo", and where it+ * came from.+ *+ * Two flags used to decide this and neither could be reconciled from outside+ * the container. `AISOC_DEMO_MODE` gates the API service's seed at run time,+ * while the console read `NEXT_PUBLIC_DEMO_MODE`, which Next inlines when the+ * image is *built* — so on a pulled image the console's answer was fixed at+ * build time and could disagree with the API's, with nothing to consult but+ * the rendered page. `AISOC_DEMO_MODE` now answers here too and outranks the+ * compiled value; `GET /api/runtime-config` reports the result.+ *+ * Runtime environment is only readable server-side, so in the browser this+ * returns the compiled answer. That is the first-paint value — `DemoBanner`+ * reconciles it against the endpoint, which cannot be stale.+ */+export function demoModeReport(): { enabled: boolean; source: DemoModeSource } {+ if (_override !== null) return { enabled: _override, source: 'test-override' };++ // `typeof window` is the client/server test Next itself compiles against;+ // AISOC_DEMO_MODE carries no NEXT_PUBLIC_ prefix, so it is never inlined+ // into the browser bundle and reading it there yields undefined.+ if (typeof window === 'undefined') {+ const runtime = truthy(process.env.AISOC_DEMO_MODE);+ if (runtime !== null) return { enabled: runtime, source: 'runtime' };+ }++ const build = truthy(process.env.NEXT_PUBLIC_DEMO_MODE);+ if (build !== null) return { enabled: build, source: 'build' };++ return { enabled: false, source: 'default' };+}++/** Returns `true` when this deployment is a demo. */+export function isDemoMode(): boolean {+ return demoModeReport().enabled;+}+/** Banner copy shown at the top of every page in demo mode. */export function demoBannerMessage(): string {return (diff --git a/docker-compose.yml b/docker-compose.ymlindex 6cb5fc784..ea8b0d2d8 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -11,8 +11,27 @@# host is attached to. This is intentional: the same passwords ship in# every clone of this repo.#-# To change a binding, write a docker-compose.override.yml and tag the list-# `!override`:+# DEPLOYING ON A HOST THAT IS NOT YOUR LAPTOP+# -------------------------------------------+# Loopback is the right default and the wrong one for a server: it makes a+# single-host install unreachable from anywhere, including from the browser+# you intended to use it from. Set ONE variable in .env:+#+# AISOC_CONSOLE_BIND_ADDR=0.0.0.0+#+# That publishes the console on every interface and leaves everything else —+# Postgres, Redis, Kafka, Neo4j and their shipped development passwords — on+# loopback where they belong. One port is enough because the console proxies+# to every other service over the internal network, so the browser only ever+# talks to the console's own origin.+#+# `AISOC_BIND_ADDR` moves ALL of the bindings, including the datastores. It+# exists for an isolated network where that is what you want. On anything+# routable it hands out the passwords in this file, so reach for the console+# variable first and put a TLS-terminating reverse proxy in front.+#+# Per-service overrides still work through a docker-compose.override.yml, and+# there the list MUST be tagged `!override`:## services:# postgres:@@ -87,7 +106,7 @@ services:# privilege levels.AISOC_APP_DB_PASSWORD: ${AISOC_APP_DB_PASSWORD:-aisoc_app_dev_secret}ports:- - "127.0.0.1:5432:5432"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:5432:5432"volumes:- postgres_data:/var/lib/postgresql/data# The init hooks: 10_ applies the migration chain, 20_ gives the runtime@@ -111,7 +130,7 @@ services:container_name: aisoc-rediscommand: redis-server --appendonly yes --requirepass redis_dev_secretports:- - "127.0.0.1:6379:6379"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:6379:6379"volumes:- redis_data:/datanetworks:@@ -160,7 +179,7 @@ services:zookeeper:condition: service_healthyports:- - "127.0.0.1:9092:9092"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9092:9092"environment:KAFKA_BROKER_ID: 1KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181@@ -193,7 +212,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8090:8080"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8090:8080"environment:KAFKA_CLUSTERS_0_NAME: localKAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:29092@@ -206,8 +225,8 @@ services:image: clickhouse/clickhouse-server:23.8container_name: aisoc-clickhouseports:- - "127.0.0.1:8123:8123"- - "127.0.0.1:9000:9000"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8123:8123"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9000:9000"volumes:- clickhouse_data:/var/lib/clickhouse- ./services/api/clickhouse:/docker-entrypoint-initdb.d:ro@@ -245,7 +264,7 @@ services:volumes:- opensearch_data:/usr/share/opensearch/dataports:- - "127.0.0.1:9200:9200"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9200:9200"networks:- aisochealthcheck:@@ -280,7 +299,7 @@ services:image: qdrant/qdrant:v1.7.0container_name: aisoc-qdrantports:- - "127.0.0.1:6333:6333"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:6333:6333"volumes:- qdrant_data:/qdrant/storagenetworks:@@ -302,8 +321,8 @@ services:image: neo4j:5.15-communitycontainer_name: aisoc-neo4jports:- - "127.0.0.1:7474:7474" # HTTP browser- - "127.0.0.1:7687:7687" # Bolt+ - "${AISOC_BIND_ADDR:-127.0.0.1}:7474:7474" # HTTP browser+ - "${AISOC_BIND_ADDR:-127.0.0.1}:7687:7687" # Boltenvironment:NEO4J_AUTH: neo4j/neo4j_dev_secretNEO4J_PLUGINS: '["apoc"]'@@ -340,7 +359,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8000:8000"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8000:8000"environment:# Two roles, on purpose. DATABASE_URL is the runtime role: DML only, and# row-level security applies to it. DATABASE_MIGRATION_URL is the owner,@@ -458,8 +477,8 @@ services:postgres:condition: service_healthyports:- - "127.0.0.1:8081:8080"- - "127.0.0.1:9090:9090"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8081:8080"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9090:9090"environment:ENV: developmentHTTP_PORT: 8080@@ -510,7 +529,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8080:8082"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8080:8082"environment:KAFKA_BOOTSTRAP_SERVERS: kafka:29092REDIS_URL: redis://:redis_dev_secret@redis:6379/2@@ -540,7 +559,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8003:8003"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8003:8003"environment:KAFKA_BOOTSTRAP_SERVERS: kafka:29092REDIS_URL: redis://:redis_dev_secret@redis:6379/3@@ -579,7 +598,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8001:8084"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8001:8084"environment:DATABASE_URL: postgresql+asyncpg://aisoc_app:${AISOC_APP_DB_PASSWORD:-aisoc_app_dev_secret}@postgres:5432/aisocREDIS_URL: redis://:redis_dev_secret@redis:6379/4@@ -653,7 +672,7 @@ services:volumes:- ollama_data:/root/.ollamaports:- - "127.0.0.1:11434:11434"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:11434:11434"healthcheck:test: ["CMD-SHELL", "ollama list >/dev/null 2>&1 || exit 1"]interval: 10s@@ -735,7 +754,7 @@ services:OPENAI_API_KEY: ${OPENAI_API_KEY:-}ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}ports:- - "127.0.0.1:4000:4000"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:4000:4000"healthcheck:test:- CMD-SHELL@@ -769,7 +788,7 @@ services:# `running`. Found by adding the healthcheck below and watching it sit# at `starting` against a port with no server on it.ports:- - "127.0.0.1:8091:9001"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8091:9001"profiles:- osqueryenvironment:@@ -821,7 +840,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8002:8085"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8002:8085"environment:KAFKA_BOOTSTRAP_SERVERS: kafka:29092REDIS_URL: redis://:redis_dev_secret@redis:6379/5@@ -852,7 +871,7 @@ services:redis:condition: service_healthyports:- - "127.0.0.1:8088:8003"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8088:8003"environment:# app/scripts/serve.py binds PORT, defaulting to 8087. The mapping above# publishes container port 8003, so leaving PORT unset put the listener@@ -933,7 +952,7 @@ services:# which is what the console reads. `make up-full` starts it and this# service picks it up on its next restart.ports:- - "127.0.0.1:8005:8005"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8005:8005"environment:KAFKA_BOOTSTRAP_SERVERS: kafka:29092REDIS_URL: redis://:redis_dev_secret@redis:6379/7@@ -978,7 +997,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8007:8004"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8007:8004"environment:# Two roles, the same split the api service uses. This service manages# its own schema through alembic, so it needs the owner to apply DDL and@@ -1031,7 +1050,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8008:8005"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8008:8005"environment:# Two roles, the same split the api service uses. This service manages# its own schema through alembic, so it needs the owner to apply DDL and@@ -1081,7 +1100,7 @@ services:redis:condition: service_healthyports:- - "127.0.0.1:8006:8006"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8006:8006"environment:# Two roles, the same split the api service uses. This service manages# its own schema through alembic, so it needs the owner to apply DDL and@@ -1127,7 +1146,7 @@ services:kafka:condition: service_healthyports:- - "127.0.0.1:8086:4000"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8086:4000"environment:KAFKA_BOOTSTRAP_SERVERS: kafka:29092REDIS_URL: redis://:redis_dev_secret@redis:6379@@ -1152,7 +1171,7 @@ services:- api- actionsports:- - "127.0.0.1:8009:8089"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8009:8089"profiles:- chatopsenvironment:@@ -1188,10 +1207,36 @@ services:- api- realtimeports:- - "127.0.0.1:3000:3000"+ # The console has its own bind address because it is the only port a+ # browser needs. Everything it talks to — the API, the agents service,+ # the realtime gateway — is reached through this server's same-origin+ # proxy on the internal network, so exposing AiSOC to a single host's+ # LAN means publishing one port, not fourteen.+ #+ # AISOC_CONSOLE_BIND_ADDR=0.0.0.0 # reachable at http://<host>:3000+ #+ # Falls back to AISOC_BIND_ADDR and then to loopback, so the default+ # install is still reachable only from the machine it runs on. Put it+ # behind a reverse proxy with TLS before anything hostile can route to+ # it; see apps/docs/docs/deployment/single-host.md.+ - "${AISOC_CONSOLE_BIND_ADDR:-${AISOC_BIND_ADDR:-127.0.0.1}}:3000:3000"environment:- NEXT_PUBLIC_API_URL: http://localhost:8000- NEXT_PUBLIC_WS_URL: ws://localhost:8086+ # Where this server proxies to. These are read at container start by+ # apps/web/docker-entrypoint.sh, which re-points the compiled rewrite+ # table at them — so unlike the NEXT_PUBLIC_* pair that used to sit+ # here, they take effect on a pulled image.+ API_URL: ${AISOC_API_URL:-http://api:8000}+ AGENTS_URL: ${AISOC_AGENTS_URL:-http://agents:8084}+ REALTIME_URL: ${AISOC_REALTIME_URL:-http://realtime:4000}+ # NOTE: do not add NEXT_PUBLIC_* here. Next inlines those into the+ # JavaScript bundle at `next build` time, so on the pulled image this+ # service runs they are read by nothing. NEXT_PUBLIC_API_URL and+ # NEXT_PUBLIC_WS_URL were set here and did exactly nothing; an operator+ # pointing the console at their own host edited them, saw no change,+ # and had no way to tell the setting was inert. The browser needs no+ # absolute URL at all — the bundle calls same-origin paths and this+ # server proxies them onward.+ AISOC_DEMO_MODE: ${AISOC_DEMO_MODE:-false}NODE_ENV: productionnetworks:- aisoc@@ -1203,7 +1248,7 @@ services:image: prom/prometheus:v2.48.0container_name: aisoc-prometheusports:- - "127.0.0.1:9091:9090"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9091:9090"volumes:- ./infra/docker/prometheus.yml:/etc/prometheus/prometheus.yml:ro# Phase 2.4 — alert rules mounted as a directory so adding a@@ -1236,7 +1281,7 @@ services:image: prom/alertmanager:v0.27.0container_name: aisoc-alertmanagerports:- - "127.0.0.1:9094:9093"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9094:9093"volumes:- ./infra/docker/alertmanager.yml:/etc/alertmanager/alertmanager.yml:rocommand:@@ -1276,8 +1321,8 @@ services:volumes:- ./infra/docker/otel/collector.yaml:/etc/otel/collector.yaml:roports:- - "127.0.0.1:4317:4317"- - "127.0.0.1:4318:4318"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:4317:4317"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:4318:4318"healthcheck:test: ["CMD", "/otelcol-contrib", "--version"]interval: 30s@@ -1297,7 +1342,7 @@ services:- ./infra/docker/otel/tempo.yaml:/etc/tempo/tempo.yaml:ro- tempo_data:/var/tempoports:- - "127.0.0.1:3200:3200"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:3200:3200"networks:- aisocprofiles:@@ -1310,7 +1355,7 @@ services:- prometheus- tempoports:- - "127.0.0.1:3001:3000"+ - "${AISOC_BIND_ADDR:-127.0.0.1}:3001:3000"# Default admin password is intentionally weak for the dev compose stack;# the 127.0.0.1 binding above keeps the dashboard off the LAN. Override# GF_SECURITY_ADMIN_PASSWORD in production deployments (helm/terraform).diff --git a/infra/helm/aisoc/templates/deployment.yaml b/infra/helm/aisoc/templates/deployment.yamlindex 733530ac4..a9ec7a8d5 100644--- a/infra/helm/aisoc/templates/deployment.yaml+++ b/infra/helm/aisoc/templates/deployment.yaml@@ -71,6 +71,36 @@ spec:valueFrom:fieldRef:fieldPath: metadata.namespace+ {{- if eq $name "web" }}+ {{- /*+ The console proxies every browser request to these addresses.+ They have to be named here because the published image is built+ against the Compose network's DNS (`http://api:8000`), and no+ such host exists in a cluster — the chart's Services are+ `<release>-api`, `<release>-agents`, `<release>-realtime`. The+ chart set none of them, so a Helm install rendered a console+ whose every API call resolved nowhere.++ Setting them was necessary and not sufficient: until+ apps/web/docker-entrypoint.sh shipped, these were read by+ nothing at run time, because `next build` compiles rewrite+ destinations into .next/routes-manifest.json. An image older+ than that entrypoint will ignore these and still dial+ `http://api:8000`.++ `values.yaml`'s `services.web.env` wins, for an API that lives+ outside the release.+ */}}+ {{- $fullname := include "aisoc.fullname" $ }}+ {{- $webEnv := $svc.env | default dict }}+ {{- range $upstream, $target := dict "API_URL" "api" "AGENTS_URL" "agents" "REALTIME_URL" "realtime" }}+ {{- if not (hasKey $webEnv $upstream) }}+ {{- $targetSvc := get $.Values.services $target }}+ - name: {{ $upstream }}+ value: "http://{{ $fullname }}-{{ $target }}:{{ $targetSvc.service.port | default 80 }}"+ {{- end }}+ {{- end }}+ {{- end }}{{- range $k, $v := $svc.env }}- name: {{ $k }}value: {{ $v | quote }}diff --git a/tests/test_console_runtime_config_gate.py b/tests/test_console_runtime_config_gate.pynew file mode 100644index 000000000..20d233a58--- /dev/null+++ b/tests/test_console_runtime_config_gate.py@@ -0,0 +1,261 @@+"""Gate: the console's upstream addresses must follow the environment it runs in.++A self-hoster deploying with Compose on one host reported that setting the+documented variables changed nothing. It could not have: `next build` freezes+*both* halves of the console's routing.++* Everything prefixed `NEXT_PUBLIC_` is inlined into the JavaScript bundle as+ a string literal when the image is built, so setting it on a container that+ *pulled* that image is read by nobody.+* The destinations returned by `rewrites()` in `next.config.js` are compiled+ into `.next/routes-manifest.json`. `next start` loads the config again — it+ even logs that it did — but production routing is served from the manifest,+ so `API_URL` was inert too.++The stack appeared to work only because the value baked into the published+image, `http://api:8000`, happens to be the service's DNS name on the bundled+Compose network. Any other topology — a different Compose project, an API on+another host, or Kubernetes, where the chart's Services are `<release>-api` —+resolved a hostname that does not exist, and no variable could re-point it.++These tests pin the property that was missing rather than the mechanism that+supplies it: *an operator's chosen upstream is the one the console proxies+to.* The first exercises the real resolver against the real `next.config.js`;+the rest hold the deployment contract that carries it — an image that runs the+resolver, a Compose file that passes addresses the running container can read+instead of ones it cannot, and a bind address a server deployment can change.+"""++from __future__ import annotations++import json+import pathlib+import shutil+import subprocess++import pytest+import yaml # type: ignore[import-untyped] # PyYAML ships no stubs; only used to read compose here++REPO = pathlib.Path(__file__).resolve().parent.parent+WEB = REPO / "apps" / "web"+COMPOSE = REPO / "docker-compose.yml"+RESOLVER = WEB / "scripts" / "resolve-runtime-routes.mjs"+ENTRYPOINT = WEB / "docker-entrypoint.sh"+DOCKERFILE = WEB / "Dockerfile"++# RFC 5737 TEST-NET-1. Chosen because it is guaranteed not to be the loopback+# address the image is built against, which is the whole point of the report:+# the console has to be pointable somewhere that is not localhost.+OPERATOR_API = "http://192.0.2.10:8000"++[email protected](scope="module")+def compose() -> dict:+ return yaml.safe_load(COMPOSE.read_text())+++def _web_env(compose: dict) -> dict[str, str]:+ env = compose["services"]["web"].get("environment") or {}+ if isinstance(env, list): # compose accepts `- KEY=value` too+ return dict(item.split("=", 1) for item in env if "=" in item)+ return {str(k): str(v) for k, v in env.items()}+++def test_operator_chosen_api_address_is_the_one_the_console_proxies_to(+ tmp_path: pathlib.Path,+) -> None:+ """The defect itself: a manifest compiled against one API host must end up+ pointing at the host the container is *started* with.++ The real `next.config.js` and the real resolver are used — reimplementing+ either here would only prove that a copy agrees with itself, which is the+ failure mode this repository has already been bitten by. The manifest is a+ fixture in the shape `next build` emits, with the destination the published+ image actually carries.+ """+ # `or ""` rather than a None check: `shutil.which` is typed Optional, and+ # narrowing it through `pytest.fail` depends on that being inferred+ # NoReturn, which the type-check baseline does not do.+ node = shutil.which("node") or ""+ if not node:+ pytest.fail(+ "node is required to run apps/web/scripts/resolve-runtime-routes.mjs. "+ "Skipping would hide whether the console can be re-pointed at all."+ )++ # Mirror the repository layout the resolver locates itself against:+ # <root>/apps/web/{next.config.js,scripts/,.next/} and <root>/VERSION.+ app = tmp_path / "apps" / "web"+ (app / "scripts").mkdir(parents=True)+ (app / ".next").mkdir()+ shutil.copy(WEB / "next.config.js", app / "next.config.js")+ shutil.copy(RESOLVER, app / "scripts" / RESOLVER.name)+ (tmp_path / "VERSION").write_text((REPO / "VERSION").read_text())++ manifest = app / ".next" / "routes-manifest.json"+ manifest.write_text(+ json.dumps(+ {+ "version": 3,+ "rewrites": {+ "beforeFiles": [],+ "afterFiles": [+ {+ "source": "/api/v1/:path*",+ "destination": "http://api:8000/api/v1/:path*",+ "regex": "^/api/v1(?:/((?:[^/]+?)(?:/(?:[^/]+?))*))?(?:/)?$",+ }+ ],+ "fallback": [],+ },+ }+ )+ )++ result = subprocess.run( # noqa: S603 — fixed argv, no shell+ [node, str(app / "scripts" / RESOLVER.name)],+ env={"PATH": "/usr/bin:/bin:/usr/local/bin", "API_URL": OPERATOR_API},+ capture_output=True,+ text=True,+ timeout=60,+ )++ assert result.returncode == 0, (+ f"the resolver exited {result.returncode} instead of re-pointing the proxy.\nstdout: {result.stdout}\nstderr: {result.stderr}"+ )++ written = json.loads(manifest.read_text())+ destination = written["rewrites"]["afterFiles"][0]["destination"]+ assert destination == f"{OPERATOR_API}/api/v1/:path*", (+ "the console still proxies to the address compiled into the image "+ f"({destination!r}) after the operator asked for {OPERATOR_API!r}. "+ "Setting API_URL on a pulled image has to take effect, or a "+ "single-host deployment can never reach its own API."+ )+++def test_resolver_refuses_to_start_when_a_chosen_address_cannot_be_applied(+ tmp_path: pathlib.Path,+) -> None:+ """Booting anyway would serve a console silently pointed at the wrong host.++ An operator who set an address and did not get it is misconfigured in a way+ no retry clears, so this is a permanent condition that must stop and name+ itself rather than degrade quietly to the built-in defaults.+ """+ node = shutil.which("node") or ""+ if not node:+ pytest.fail("node is required to exercise the resolver's failure posture.")++ app = tmp_path / "apps" / "web"+ (app / "scripts").mkdir(parents=True)+ shutil.copy(WEB / "next.config.js", app / "next.config.js")+ shutil.copy(RESOLVER, app / "scripts" / RESOLVER.name)+ (tmp_path / "VERSION").write_text((REPO / "VERSION").read_text())+ # No .next/routes-manifest.json — the manifest cannot be applied.++ result = subprocess.run( # noqa: S603 — fixed argv, no shell+ [node, str(app / "scripts" / RESOLVER.name)],+ env={"PATH": "/usr/bin:/bin:/usr/local/bin", "API_URL": OPERATOR_API},+ capture_output=True,+ text=True,+ timeout=60,+ )++ assert result.returncode != 0, (+ "the resolver started the console on the built-in addresses after failing to apply an address the operator explicitly set"+ )+ assert "API_URL" in result.stderr, f"the failure has to name the variable it could not apply; stderr was {result.stderr!r}"+++def test_web_image_resolves_upstreams_before_the_server_starts() -> None:+ """The resolver only helps if the image actually runs it."""+ assert ENTRYPOINT.is_file(), (+ f"{ENTRYPOINT.relative_to(REPO)} is missing, so nothing re-points the compiled rewrite table when the container starts"+ )+ assert RESOLVER.name in ENTRYPOINT.read_text(), "the entrypoint does not invoke the resolver"++ dockerfile = DOCKERFILE.read_text()+ assert "ENTRYPOINT" in dockerfile and "docker-entrypoint.sh" in dockerfile, (+ "apps/web/Dockerfile does not wire docker-entrypoint.sh as its ENTRYPOINT, so `next start` runs against the build-time manifest"+ )+++def test_compose_gives_the_console_addresses_it_can_actually_read(+ compose: dict,+) -> None:+ """`NEXT_PUBLIC_*` under `environment:` is read by nothing.++ The Compose file set `NEXT_PUBLIC_API_URL` and `NEXT_PUBLIC_WS_URL` on a+ service that pulls its image. Next inlines those at build time, so an+ operator editing them to point at their own host saw no change and had no+ way to tell the setting was inert — which is exactly what was reported.+ """+ env = _web_env(compose)++ inert = sorted(k for k in env if k.startswith("NEXT_PUBLIC_"))+ assert not inert, (+ f"docker-compose.yml sets {inert} on the `web` service. Next inlines "+ "NEXT_PUBLIC_* into the bundle at build time, so on the pulled image "+ "this service runs they do nothing but mislead. The browser needs no "+ "absolute URL — it calls same-origin paths that this server proxies."+ )++ for required in ("API_URL", "AGENTS_URL", "REALTIME_URL"):+ assert required in env, f"the `web` service sets no {required}, so the console can only reach the hosts its image was built against"+++def test_helm_points_the_console_at_the_chart_s_own_services() -> None:+ """The same defect is worse on Kubernetes, which is where this user is going.++ The chart creates `<release>-api`, `<release>-agents` and+ `<release>-realtime`, while the published image is built against the+ Compose network's `http://api:8000`. No such host exists in a cluster, and+ the chart set no upstream addresses at all — so every console request+ resolved nowhere. Parsed from the template rather than rendered with+ `helm`, which is not installed in the job that runs these tests.+ """+ template = (REPO / "infra" / "helm" / "aisoc" / "templates" / "deployment.yaml").read_text()++ for upstream in ("API_URL", "AGENTS_URL", "REALTIME_URL"):+ assert upstream in template, (+ f"the Helm chart never sets {upstream} on the web deployment, so "+ "the console proxies to the hostnames its image was built with — "+ "which do not resolve in a cluster"+ )++ assert 'include "aisoc.fullname"' in template, (+ "the upstream addresses must be built from the release's own Service names; a hard-coded hostname is the defect this is fixing"+ )+++def test_single_host_deployment_can_publish_the_console(compose: dict) -> None:+ """Loopback-only is right for a laptop and fatal for a server.++ Every published port was the literal `127.0.0.1`, so a single-host install+ was unreachable from the browser it was meant to be used from, and nothing+ in `.env` could change that. The console gets its own knob because+ same-origin proxying means one port is enough — the datastores and their+ shipped development passwords stay on loopback.+ """+ published = [port for service in compose["services"].values() for port in (service.get("ports") or []) if isinstance(port, str)]+ assert published, "no published ports found — has the compose schema changed?"++ hardcoded = [p for p in published if p.startswith("127.0.0.1:")]+ assert not hardcoded, (+ f"{len(hardcoded)} port(s) publish to a hard-coded 127.0.0.1 "+ f"({hardcoded[:3]}…). A deployment on a host that is not the "+ "operator's laptop cannot be reached, and no variable changes it."+ )++ console = compose["services"]["web"]["ports"]+ assert any("AISOC_CONSOLE_BIND_ADDR" in str(p) for p in console), (+ "the console has no bind address of its own, so making it reachable "+ "would mean moving every binding — including Postgres, Redis and "+ "Kafka with the development passwords this file ships"+ )++ defaults_to_loopback = all("127.0.0.1" in p for p in published)+ assert defaults_to_loopback, (+ "a port stopped defaulting to loopback. An install must not expose itself to whatever network the host is attached to by omission."+ )diff --git a/tests/test_docs_profile_table_gate.py b/tests/test_docs_profile_table_gate.pyindex 1e2b66cbe..85c603f50 100644--- a/tests/test_docs_profile_table_gate.py+++ b/tests/test_docs_profile_table_gate.py@@ -119,9 +119,16 @@ def test_documented_host_ports_match_compose() -> None:for name, cfg in services.items():published = set()for mapping in (cfg or {}).get("ports") or []:- match = re.match(r"^(?:[\d.]+:)?(\d+):", str(mapping))- if match:- published.add(match.group(1))+ # `[bind:]host:container[/proto]`. Read positionally from the right+ # rather than matching the bind address, which is now a Compose+ # interpolation with a nested default —+ # `${AISOC_CONSOLE_BIND_ADDR:-${AISOC_BIND_ADDR:-127.0.0.1}}` —+ # and carries colons of its own. A pattern anchored on a literal+ # IP silently matched nothing and reported every service as+ # publishing no host port at all.+ fields = str(mapping).split("/")[0].split(":")+ if len(fields) >= 2 and fields[-2].isdigit():+ published.add(fields[-2])actual[name] = publishedwrong: list[str] = []diff --git a/tests/test_env_placeholder_gate.py b/tests/test_env_placeholder_gate.pyindex df9ffbf73..887d5ab9a 100644--- a/tests/test_env_placeholder_gate.py+++ b/tests/test_env_placeholder_gate.py@@ -64,6 +64,10 @@ DELIBERATE_DEFAULTS: dict[str, str] = {"ENVIRONMENT": "selects the dev auth bypass; documented and read by compose","LOG_LEVEL": "a log level, not a secret","AISOC_CONSOLE_URL": "the address `make bootstrap` prints; localhost is right for a laptop",+ "AISOC_API_URL": "the compose hostname the console proxies API calls to",+ "AISOC_AGENTS_URL": "the compose hostname the console proxies agent calls to",+ "AISOC_REALTIME_URL": "the compose hostname the console proxies WS/SSE to",+ "AISOC_DEMO_MODE": "a boolean; false is the correct value for every deployment that is not the public demo","AISOC_REALTIME_TICKET_TTL_SECONDS": "a duration","CONNECTORS_SERVICE_URL": "the compose hostname of the connectors service","CONNECTORS_SERVICE_TIMEOUT_SECONDS": "a duration",