Deploy CodeGraph in customer infrastructure

This guide defines the supported deployment boundary. It points to maintained artifacts instead of copying Compose files, Kubernetes objects, or capacity figures into prose. Customer-pilot readiness uses revision-bound health, security, backup, restore, rollback, and observability evidence for the selected environment.

Supported profiles

Choose one profile and record it in the deployment plan:

The Helm chart currently owns deployment, service, ingress, HPA, PVC, secret, and config-map templates. NetworkPolicy, ServiceMonitor, Alertmanager, external database, secret-manager, ingress controller, and storage-class objects remain customer-platform responsibilities unless a released artifact explicitly adds them.

Plan before mutation

Capture these inputs before changing customer infrastructure:

• immutable CodeGraph commit, tag, image digest, and package versions;
• selected profile and exact values or environment overlay;
• DNS, TLS termination, ingress, proxy, and outbound-network policy;
• PostgreSQL, OpenViking, GoCPG, model-provider, and object/file-storage dependencies;
• secret ownership, rotation path, and external reference mechanism;
• persistent volumes, retention, backup scope, and restore target;
• resource limits based on a measured pilot corpus rather than a universal sizing table;
• maintenance window, rollback trigger, and accountable operator.

Do not place real secrets in Git, Helm values committed to source, screenshots, tickets, or command history. Resolve them through the customer-approved secret channel.

Validate a source checkout

The maintained local-stack commands are documented in docs/development/reference/operator/CODEGRAPH_RUNTIME_RELEASE_RUNBOOK.md:

python scripts/run_app_stack.py status --local --with-mcp
python scripts/run_app_stack.py restart --local --with-mcp
python scripts/run_app_stack.py logs --local --with-mcp

Run status before mutation. After a restart, wait for the command to finish and verify the same revision through the API, MCP client if enabled, and project-context status. Confirm request serving with an API or MCP health check tied to that revision.

Deploy with Compose or Helm

For Compose, treat the checked-in files as the contract and inspect the effective configuration before startup:

docker compose -f docker-compose.yml -f docker-compose.prod.yml config
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
docker compose -f docker-compose.yml -f docker-compose.prod.yml ps

For Kubernetes, render the maintained chart with the customer values before applying it:

helm template codegraph deploy/helm/codegraph -f customer-values.yaml > rendered.yaml
helm upgrade --install codegraph deploy/helm/codegraph -f customer-values.yaml --atomic

Review rendered.yaml for image digests, namespaces, security contexts, volumes, ingress, and secret references. --atomic helps with Helm release state; it does not restore application data or external services.

Protect network, secrets, and data

At minimum:

• terminate TLS at the approved boundary and restrict administrative routes;
• keep PostgreSQL, GoCPG, OpenViking, and internal service ports off untrusted networks;
• require authentication for API, MCP network transports, ACP, and gRPC as applicable;
• allow outbound access only to approved model, repository, issue, telemetry, and update services;
• enable DLP, audit, and SIEM controls required by the deployment profile;
• use customer-owned encryption, retention, backup, and deletion policies for persistent data.

Direct DuckDB writes and raw database-path arguments are diagnostic or internal boundaries, not supported remote integration mechanisms.

Upgrade and rollback

Before upgrade, capture current health, database/schema state, active configuration, image digest, and a tested restore point. Deploy one immutable candidate and run the agreed acceptance probes.

Rollback means restoring the preceding release artifact and its compatible configuration. If the release includes an irreversible data migration, follow the migration-specific recovery plan; do not assume that changing an image tag reverses stored state.

Trigger rollback on agreed conditions such as failed health dependencies, authorization regression, data-integrity mismatch, unacceptable error rate, or failed pilot acceptance. Record the trigger, decision owner, commands, result, and restored revision.

Backup and restore

The backup scope must cover every stateful dependency used by the selected profile, including PostgreSQL data, project configuration, customer-managed volumes, encryption metadata, and any required OpenViking or graph reconstruction inputs. A verified restore rehearsal creates recovery evidence for the copied data.

Rehearse restore into an approved non-production target or the customer-defined recovery context:

1. verify backup identity, digest, encryption, and retention;
2. restore configuration and data using the version-compatible procedure;
3. start the exact release expected by the backup;
4. run health, authentication, project, graph, and representative query checks;
5. record recovery time, data-loss window, exceptions, and evidence references.

Health and observability

Use the authenticated deployment context and current route contract:

• /api/v1/health for application and dependency health;
• /metrics for the configured Prometheus scrape surface;
• local-stack status and logs for source-checkout diagnosis;
• Kubernetes rollout, pod events, and selected service logs for cluster diagnosis;
• SIEM delivery status and downstream receipt evidence for security events.

Do not equate HTTP success from an intake endpoint with completed background processing or downstream delivery. Alert thresholds and retention must come from the customer SLO and measured pilot baseline.

Readiness evidence

The deployment packet should identify:

• immutable release and effective configuration digests;
• successful install or upgrade output and health probes;
• authentication, authorization, DLP, and secret-publication checks;
• representative project import, CPG freshness, and user workflow results;
• metrics, logs, alert routing, and SIEM receipt evidence;
• backup, restore, and rollback rehearsal references;
• known constraints, unavailable channels, owners, and recovery actions.

Deployment evidence supports the DevOps/SRE lane. Product acceptance, QA, AppSec, documentation, traceability, support, and financial-control closure keep their own evidence.