Skip to content

Deployment

Value Stream currently targets single-host deployment: one machine (or container) runs ingestion, the Streamlit UI, and optionally the read-only API and MCP surfaces against workspace directories on local or mounted storage. Distributed execution and multi-user auth are out of scope or deferred — see Product overview.

Host Requirements

  • Python 3.11+ and uv.
  • Disk for workspace directories (source files, aggregates, metadata). The aggregate store is compact relative to raw data, but source files dominate until they are archived.
  • Install with all extras (ai for MCP, api for FastAPI):
uv sync --all-extras

Workspace Placement

Place each workspace on storage the host can read and write, e.g. /data/valuestream/<workspace>. Keep catalog/ under source control and deploy catalog changes through the normal validate-then-run loop. The data/, aggregates/, and meta/ folders are runtime state.

Scheduled Ingestion

valuestream run is cron-friendly: it exits non-zero on failure, skips already-processed chunks, and is safe to re-run. A minimal cron entry:

15 * * * * cd /opt/value_stream && uv run valuestream run /data/valuestream/prod >> /var/log/valuestream/run.log 2>&1

Schedule vacuum less frequently (e.g. daily) and only after report checks:

30 3 * * * cd /opt/value_stream && uv run valuestream vacuum /data/valuestream/prod >> /var/log/valuestream/vacuum.log 2>&1

Serving the UI

uv run valuestream serve /data/valuestream/prod --port 8501 --headless

Streamlit itself provides no authentication. For anything beyond a trusted network, put the UI behind a reverse proxy that terminates TLS and enforces access (e.g. nginx with SSO), and treat the host as single-tenant.

The revised top-level Build entry is enabled by default. During a measured authoring rollout, set VALUESTREAM_AUTHORING_V2=0 to hide that entry and keep the two authoring pages under Settings. See the configuration authoring rollout runbook; the flag does not change YAML, transaction, validation, or ingestion semantics.

Serving the API and MCP

export VALUESTREAM_API_TOKEN=replace-me
uv run valuestream serve-api /data/valuestream/prod --host 127.0.0.1 --port 8000
uv run valuestream serve-mcp /data/valuestream/prod
  • Prefer a loopback bind with a reverse proxy in front; a non-loopback bind requires a bearer token (see Security).
  • Add --enable-sql only when governed SQL is genuinely needed.
  • MCP defaults to stdio for local clients on the same host. Use --transport http for a separately supervised server with a mandatory VALUESTREAM_MCP_TOKEN, one workspace, and endpoint /mcp. Follow the HTTP connection guide for launch, HTTPS proxy, and client verification.

Long-lived API/MCP servers reload the catalog automatically when its YAML files change on disk, so catalog deploys do not require a restart.

Process Supervision

Run serve, serve-api, or serve-mcp --transport http under a supervisor (systemd, supervisor, or a container orchestrator) with restart-on-failure. A minimal systemd unit:

[Unit]
Description=Value Stream UI
After=network.target

[Service]
WorkingDirectory=/opt/value_stream
ExecStart=/usr/local/bin/uv run valuestream serve /data/valuestream/prod --port 8501 --headless
Restart=on-failure
User=valuestream

[Install]
WantedBy=multi-user.target

Publishing the Docs Site

uv run mkdocs build --strict   # gate
uv run mkdocs serve            # local preview

CI deploys the MkDocs site via the docs.yml GitHub Actions workflow on pushes to main.

Deferred

OIDC/multi-user permissions and managed hosted service operation are deferred. HTTP MCP is available for one workspace with a shared bearer token. Treat every deployment as single-tenant; use the HTTPS and access rules above.