Skip to content

armgit / AiSOC

Public Imported from GitHub
0

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.

fix(deploy): make the console's endpoints runtime-configurable and a single host reachable (#888)

Beenu Arorab2cca25e2ed2
diff --git a/.env.example b/.env.example
index 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.md
index 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
### BREAKING
diff --git a/apps/docs/docs/deployment/env-vars.md b/apps/docs/docs/deployment/env-vars.md
index 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.0
NEXT_PUBLIC_VAPID_PUBLIC_KEY=${VAPID_PUBLIC_KEY}
```
diff --git a/apps/docs/docs/deployment/single-host.md b/apps/docs/docs/deployment/single-host.md
new file mode 100644
index 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.ts
index 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/Dockerfile
index 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 nextjs
EXPOSE 3000
WORKDIR /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.sh
new file mode 100755
index 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.mjs
new file mode 100755
index 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.tsx
index 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.ts
new file mode 100644
index 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.tsx
index 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 (
<div
diff --git a/apps/web/src/components/layout/AppShell.tsx b/apps/web/src/components/layout/AppShell.tsx
index 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.ts
index 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.yml
index 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-redis
command: redis-server --appendonly yes --requirepass redis_dev_secret
ports:
- - "127.0.0.1:6379:6379"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:6379:6379"
volumes:
- redis_data:/data
networks:
@@ -160,7 +179,7 @@ services:
zookeeper:
condition: service_healthy
ports:
- - "127.0.0.1:9092:9092"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9092:9092"
environment:
KAFKA_BROKER_ID: 1
KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
@@ -193,7 +212,7 @@ services:
kafka:
condition: service_healthy
ports:
- - "127.0.0.1:8090:8080"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8090:8080"
environment:
KAFKA_CLUSTERS_0_NAME: local
KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:29092
@@ -206,8 +225,8 @@ services:
image: clickhouse/clickhouse-server:23.8
container_name: aisoc-clickhouse
ports:
- - "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/data
ports:
- - "127.0.0.1:9200:9200"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9200:9200"
networks:
- aisoc
healthcheck:
@@ -280,7 +299,7 @@ services:
image: qdrant/qdrant:v1.7.0
container_name: aisoc-qdrant
ports:
- - "127.0.0.1:6333:6333"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:6333:6333"
volumes:
- qdrant_data:/qdrant/storage
networks:
@@ -302,8 +321,8 @@ services:
image: neo4j:5.15-community
container_name: aisoc-neo4j
ports:
- - "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" # Bolt
environment:
NEO4J_AUTH: neo4j/neo4j_dev_secret
NEO4J_PLUGINS: '["apoc"]'
@@ -340,7 +359,7 @@ services:
kafka:
condition: service_healthy
ports:
- - "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_healthy
ports:
- - "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: development
HTTP_PORT: 8080
@@ -510,7 +529,7 @@ services:
kafka:
condition: service_healthy
ports:
- - "127.0.0.1:8080:8082"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8080:8082"
environment:
KAFKA_BOOTSTRAP_SERVERS: kafka:29092
REDIS_URL: redis://:redis_dev_secret@redis:6379/2
@@ -540,7 +559,7 @@ services:
kafka:
condition: service_healthy
ports:
- - "127.0.0.1:8003:8003"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8003:8003"
environment:
KAFKA_BOOTSTRAP_SERVERS: kafka:29092
REDIS_URL: redis://:redis_dev_secret@redis:6379/3
@@ -579,7 +598,7 @@ services:
kafka:
condition: service_healthy
ports:
- - "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/aisoc
REDIS_URL: redis://:redis_dev_secret@redis:6379/4
@@ -653,7 +672,7 @@ services:
volumes:
- ollama_data:/root/.ollama
ports:
- - "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:
- osquery
environment:
@@ -821,7 +840,7 @@ services:
kafka:
condition: service_healthy
ports:
- - "127.0.0.1:8002:8085"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8002:8085"
environment:
KAFKA_BOOTSTRAP_SERVERS: kafka:29092
REDIS_URL: redis://:redis_dev_secret@redis:6379/5
@@ -852,7 +871,7 @@ services:
redis:
condition: service_healthy
ports:
- - "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:29092
REDIS_URL: redis://:redis_dev_secret@redis:6379/7
@@ -978,7 +997,7 @@ services:
kafka:
condition: service_healthy
ports:
- - "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_healthy
ports:
- - "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_healthy
ports:
- - "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_healthy
ports:
- - "127.0.0.1:8086:4000"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8086:4000"
environment:
KAFKA_BOOTSTRAP_SERVERS: kafka:29092
REDIS_URL: redis://:redis_dev_secret@redis:6379
@@ -1152,7 +1171,7 @@ services:
- api
- actions
ports:
- - "127.0.0.1:8009:8089"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:8009:8089"
profiles:
- chatops
environment:
@@ -1188,10 +1207,36 @@ services:
- api
- realtime
ports:
- - "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: production
networks:
- aisoc
@@ -1203,7 +1248,7 @@ services:
image: prom/prometheus:v2.48.0
container_name: aisoc-prometheus
ports:
- - "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.0
container_name: aisoc-alertmanager
ports:
- - "127.0.0.1:9094:9093"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:9094:9093"
volumes:
- ./infra/docker/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
command:
@@ -1276,8 +1321,8 @@ services:
volumes:
- ./infra/docker/otel/collector.yaml:/etc/otel/collector.yaml:ro
ports:
- - "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/tempo
ports:
- - "127.0.0.1:3200:3200"
+ - "${AISOC_BIND_ADDR:-127.0.0.1}:3200:3200"
networks:
- aisoc
profiles:
@@ -1310,7 +1355,7 @@ services:
- prometheus
- tempo
ports:
- - "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.yaml
index 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.py
new file mode 100644
index 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.py
index 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] = published
wrong: list[str] = []
diff --git a/tests/test_env_placeholder_gate.py b/tests/test_env_placeholder_gate.py
index 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",