AdvisoryAI Deployment Guide (AIAI-31-008)

This guide covers packaging AdvisoryAI for on-prem / offline environments, toggling remote inference, and recommended scaling settings.

Verified against commit 942a18727c on 2026-09-26 (UTC) for the Artifacts, Build and Frontdoor sections. Re-verify: grep -n "advisoryai-" devops/docker/build-service-publish.sh devops/docker/services-matrix.env. The other sections were not re-verified on 2026-09-26.

Artifacts

• Images: stellaops/advisoryai-web and stellaops/advisoryai-worker, built from devops/docker/Dockerfile.hardened.template by the publish keys advisoryai-web and advisoryai-worker (devops/docker/build-service-publish.sh, devops/docker/services-matrix.env).
• Compose: the family overlay devops/compose/docker-compose.advisoryai.yml (advisoryai-data-init, advisoryai-web, advisoryai-worker). It is not part of the default compose chain and not part of the release bundle.
• Kubernetes and Helm are not a supported Stella Ops release target.

Build and run locally

# Build both images
devops/docker/build-service-publish.sh advisoryai-web advisoryai-worker

# Add the family overlay to the stack
docker compose -f devops/compose/docker-compose.stella-infra.yml   -f devops/compose/docker-compose.stella-services.yml   -f devops/compose/docker-compose.advisoryai.yml up -d advisoryai-web advisoryai-worker

Remote inference toggle

• Default: ADVISORYAI__AdvisoryAI__Inference__Mode=Local (fully offline).
• Remote: set
  • ADVISORYAI__AdvisoryAI__Inference__Mode=Remote
  • ADVISORYAI__AdvisoryAI__Inference__Remote__BaseAddress=https://inference.example.com
  • ADVISORYAI__AdvisoryAI__Inference__Remote__Endpoint=/v1/inference
  • ADVISORYAI__AdvisoryAI__Inference__Remote__ApiKey=<token>
  • Optional: ADVISORYAI__AdvisoryAI__Inference__Remote__Timeout=00:00:30
• Guardrails still enforced locally (see ADVISORYAI__AdvisoryAI__Guardrails__* options); keep secrets in mounted env/secret rather than images.

Evidence retrieval binding

• advisoryai-web requires AdvisoryAI:EvidenceRetrieval:BaseAddress in production-like hosts so explanation requests can anchor claims to live Scanner evidence.
• The supported compose setup sets ADVISORYAI__AdvisoryAI__EvidenceRetrieval__BaseAddress=${ADVISORY_AI_EVIDENCE_RETRIEVAL_BASEADDRESS:-http://scanner.stella-ops.local}.
• The binding calls Scanner’s unified triage evidence endpoint (/api/v1/triage/findings/{findingId}/evidence) through the scanner-internal HTTP client, so Authority client-credentials auth and tenant claims follow the same path as the AdvisoryAI live search adapters.
• If this setting is missing outside an explicit Development/Testing local harness, IEvidenceRetrievalService remains fail-closed. Do not use AdvisoryAI:RuntimeBindings:AllowLocalHarnessFakes=true to make a supported compose stack pass.

Frontdoor routing

• advisoryai-web registers with the Router as microservice advisoryai (Router__Enabled in the overlay) and is reachable on the network alias advisoryai.stella-ops.local.
• The gateway route table for AdvisoryAI was not re-verified on 2026-09-26; read the live gateway configuration before relying on any front-door path.

Volume ownership

• The supported compose setup runs advisoryai-data-init before advisoryai-web and advisoryai-worker. It creates /var/lib/advisory-ai/{queue,plans,outputs} on the named volumes, owns them as UID/GID 10001:10001, and restricts permissions to the service user.
• Both hosts mount the same named volumes at /var/lib/advisory-ai/queue, /var/lib/advisory-ai/plans, and /var/lib/advisory-ai/outputs; do not point either host at /tmp in supported setup.
• Without this init step, Docker-created named volumes are root-owned. The web service can still answer read-only explanation requests, but plan creation fails when FileSystemAdvisoryTaskQueue tries to create its .quarantine directory and the worker will not reliably drain shared plans.

Storage & persistence

• File-system queue/cache/output paths default to /app/data/{queue,plans,outputs} and are pre-created at startup.
• Compose mounts separate advisory-ai-queue, advisory-ai-plans, and advisory-ai-outputs volumes. Kubernetes PVC and Helm persistence settings are outside the supported release model.
• In sealed/air-gapped mode, mount guardrail lists/policy knobs under /app/etc and point env vars accordingly.
• Runtime PostgreSQL is required for live consent, attestation, explanation replay, policy-intent, run, conversation, chat-settings, chat-audit, and knowledge-search state. Both roles resolve only STELLAOPS_POSTGRES_ADVISORYAI_CONNECTION (or Postgres:AdvisoryAI:ConnectionString); legacy and generic database keys do not provide a fallback. advisoryai-web is the sole consolidated startup-migration authority, registered before its indexers, while the worker uses runtime DAL only. Live since the AAI-9 window of 2026-09-04.
• Production-like hosts fail closed when durable/runtime bindings are missing. Null*, NoOp*, and InMemory* runtime bindings may only bind in Development or Testing with AdvisoryAI:RuntimeBindings:AllowLocalHarnessFakes=true; do not set that flag in supported release manifests.
• Both roles bind the hub-backed advisory document provider from ADVISORYAI__AdvisoryAI__DocumentProvider__Hub__BaseAddress (and …__DocumentProvider__Tenant). The worker needs it to execute plans; since 2026-09-10 the web role needs it to materialise them: a Production advisoryai-web without the key answers POST /v1/advisory-ai/pipeline/{taskType} with 400 IAdvisoryDocumentProvider is not configured instead of an empty plan. The scratch overlay deliberately points it at an unreachable scratch-local name.
• The dummy LLM provider is also gated by the same explicit local harness switch. Production-like hosts do not register it, so a stray dummy.yaml under etc/llm-providers cannot become an available LLM backend.

In-house model gateway readiness

• Production-like advisoryai-web chat binds the in-house OpenAI-compatible gateway with ADVISORYAI__AdvisoryAI__Chat__Inference__Provider=inhouse-ternary and an operator-supplied ADVISORYAI__AdvisoryAI__Chat__Inference__BaseUrl.
• The default setup example uses microsoft/bitnet-b1.58-2B-4T, an MIT-licensed native 1.58-bit/ternary roughly 2B-parameter model. Stella Ops does not bundle model weights; operators must install/serve the model through an approved local gateway, for example a bitnet.cpp CPU gateway using a locally approved GGUF variant.
• Production validation remains fail-closed. Set ADVISORYAI__AdvisoryAI__Chat__Inference__ModelDigest=sha256:<digest> and ADVISORYAI__AdvisoryAI__Chat__Inference__CapabilityValidation__RequireModelDigestMatch=true once the gateway registry exposes the operator-approved digest or signed model manifest. No release note, benchmark, or support claim should be made until the configured endpoint, digest/manifest, capabilities, JSON mode, and citation behavior pass validation.
• The gateway registry (GET /v1/models) must list the configured model with chat.completions, response_format.json_object, citations.required, seed, and top_k capabilities.
• Supported release probes should use /health/ready for readiness and /health/live for process liveness. /health/model returns the gateway status object for operators.
• Readiness fails closed with a structured diagnostic when the gateway is unreachable, the model is absent, required capabilities are missing, or the digest rule fails. There is no cloud fallback, dummy fallback, sanitized prompt echo, or production prompt-preview behavior.
• Compose and appsettings examples wire these settings explicitly. For a full appsettings sample, see docs/modules/advisory-ai/samples/inhouse-model-gateway.appsettings.json.
• Release guide note: model-selection guidance must be updated before adopting a future custom or larger Stella Ops model, including the new model id, license, local runtime, hardware envelope, digest/manifest requirement, and validation evidence.

PostgreSQL attribution and pooling

• AdvisoryAI knowledge-search and unified-search PostgreSQL traffic now uses a shared pooled NpgsqlDataSource instead of per-operation transient data sources or raw connections.
• Default application_name is stellaops-advisory-ai-web/knowledge-search (the string is set in source and was not renamed with the compose key), which makes pg_stat_activity attribution stable for the web service.
• Default idle-pool retention is 900 seconds so the shared pool stays warm across the 5-minute unified-search refresh cycle instead of re-opening physical sessions each run.
• Override these with:
  • ADVISORYAI__KnowledgeSearch__DatabaseApplicationName
  • ADVISORYAI__KnowledgeSearch__DatabasePoolingEnabled
  • ADVISORYAI__KnowledgeSearch__DatabaseMinPoolSize
  • ADVISORYAI__KnowledgeSearch__DatabaseMaxPoolSize
  • ADVISORYAI__KnowledgeSearch__DatabaseConnectionIdleLifetimeSeconds
• The legacy ADVISORYAI__KnowledgeSearch__ConnectionString is no longer authoritative for host/database/credentials. Pool and attribution settings remain under KnowledgeSearch, but the connection is always overwritten with the service-owned AdvisoryAI DSN.

Scaling guidance

• WebService: start with 1 process, scale horizontally by CPU (tokenization) or queue depth; set ADVISORYAI__AdvisoryAI__Queue__DirectoryPath to shared durable storage only when running multiple web/worker processes on supported hosts.
• Worker: scale independently with compose or service-manager replicas. Workers are CPU-bound; pin CPU/memory in the host supervisor.
• Set rate limiter headers: add X-StellaOps-Client per caller to avoid shared buckets.

Offline posture

• Images build from source without external runtime downloads; keep ADVISORYAI__AdvisoryAI__Inference__Mode=Local to stay offline.
• For registry-mirrored environments, push stellaops-advisoryai-web and stellaops-advisoryai-worker to the allowed registry and reference them from the supported compose/service-manager release path.
• Disable OTEL exporters unless explicitly permitted; logs remain structured JSON to stdout.

Air-gap checklist

• Remote inference disabled (or routed through approved enclave).
• Guardrail phrase list mounted read-only.
• Data volume scoped per tenant/project if multi-tenant; enforce scope via X-StellaOps-Scopes.
• Validate that /app/data volume has backup/retention policy; cache pruning handled by storage options.

Deliverables mapping

• Compose + Dockerfile satisfy on-prem packaging.
• Kubernetes/Helm packaging is out of scope for current Stella Ops releases.
• This guide documents scaling/offline posture required by Sprint 0110 AIAI-31-008.