Deploy CodeGraph in customer infrastructure

Choose how to install CodeGraph in your organization’s infrastructure, prepare storage and network access, then verify the API and a project analysis. This guide helps platform administrators connect installation, upgrades, backups and recovery in one operating plan.

For an initial Ubuntu installation, start with the installation guide. The sections below cover deployment options and checks after startup.

Supported profiles

Choose one profile and record it in the deployment plan:

The Helm chart creates Deployment, Service, Ingress, HPA, PVC, Secret and ConfigMap objects from the selected settings. The cluster administrator prepares network policies, monitoring, the external database, secret store, ingress controller and storage class.

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

Use PowerShell from the approved CodeGraph source checkout, with its Python dependencies installed. These commands apply to the local integration stack, not a customer production service. restart stops and starts local processes; logs can contain sensitive data.

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, use the production configuration from the selected release. Validate it before starting the containers:

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

Run these commands from the selected release checkout. Install Docker Engine and the Compose plugin, then prepare a protected .env. config --quiet validates without printing resolved secrets. A successful check exits with code 0. If Docker warns that an unset variable defaults to a blank string, fill in the corresponding .env value and repeat the check before up -d. Inspect the effective configuration only in a protected session. The files include latest image defaults: bind the deployed images to the approved immutable release and record their digests. After startup, verify login, project import and CPG freshness using the sections below.

Prepare Kubernetes values

1. Copy deploy/helm/codegraph/values.yaml from the selected release to a new protected customer-values.yaml. Preserve any existing values file separately before preparing a replacement.
2. Set image.registry, image.repository and image.tag to the API image in the approved registry and immutable release. Verify cluster pull access; use imagePullSecrets for a private registry.
3. Configure resources, persistence.cpgData and its storage class for the corpus and infrastructure. For OpenViking, set openviking.configSecretName and openviking.dataPersistence. The Secret must exist in the target namespace and contain the file named by openviking.configFileName, which defaults to ov.conf.
4. Prepare external services and set secrets.databaseUrl, secrets.jwtSecret and the chosen model provider’s credentials. The chart writes these secrets values to a Kubernetes Secret. Restrict file access to the operators deploying the system.
5. For ingress, enable ingress.enabled and set ingress.className, ingress.hosts and ingress.tls for the public API origin. Verify the selected Kubernetes context and namespace.

For Kubernetes, render the chart with the prepared 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

Run Helm from the checkout root with a configured Kubernetes context and namespace. Use a protected customer-values.yaml prepared for that cluster. If openviking.enabled is true, set openviking.configSecretName to the name of the prepared OpenViking configuration Secret in the target namespace. The chart mounts that Secret into the sidecar. Rendering can write base64-encoded Secret values to rendered.yaml; base64 is not encryption. Restrict access to both files and keep them out of Git and public artifacts. Verify the target context before upgrade --install, then check rollout, readiness, and the application through its approved URL.

The chart deploys the API and an additional OpenViking container when enabled. Provision its other dependencies separately. The image helper uses registry, repository, and tag, not an image.digest field. Set a protected immutable tag and verify the resolved image digest after deployment. Choose storage, network and resource settings for the target cluster.

Review rendered.yaml for image addresses and tags, 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.

Configure OAuth or LDAP login, roles and projects, DLP content checks and SIEM event delivery. These guides provide settings, verification steps and expected results.

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

Check service state and data delivery through these channels:

• /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.

To check application health, set the API address without a trailing slash and run this request from a network that can reach the server:

$api = '<api-base-url>'
$health = Invoke-RestMethod -Uri "$api/api/v1/health" -TimeoutSec 10
$health | Select-Object status, version, timestamp, uptime_seconds
$health.components | ConvertTo-Json -Depth 4

The response includes overall status, application version, the check timestamp, uptime_seconds, and service states in components. Compare each service result with the selected deployment profile. /metrics supplies Prometheus data; configure collection through the internal server address and the agreed network rules.

For background operations such as project import, wait for the task to finish and check its result. For SIEM events, verify receipt in the destination system. Set alert thresholds and retention from the customer SLO and measured pilot baseline.

Readiness evidence

Save the deployment checks so the next administrator can find the release, settings and recovery procedure:

• 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.

Connect automatic project checks

After the first import, follow automatic project setup. Choose the GitHub, GitLab, GitVerse or SourceCraft webhook guide, then verify a CPG update after a commit and the PR/MR review result. Configure scheduled audits and architecture rules. Retain the first run result with the selected settings.