Skip to main content

Configure a CodeGraph deployment

Supported secret, environment, and non-secret configuration boundaries. The page explains the purpose, usage steps, and result checks.

Getting Started

CodeGraph separates protected environment values from versioned non-secret behavior. A professional administrator should apply changes through the customer’s secret-management and change-control procedures, then rerun readiness checks.

Configuration sources

Configuration sources
Source Purpose Customer deployment location
.env.example Version-bound list of supported environment variables Reference only; do not store real secrets in it
.env Secrets and deployment-specific environment values /opt/codegraph/.env
config.yaml Non-secret application behavior and ${VARIABLE} interpolation /opt/codegraph/config.yaml
projects.yaml Declared project configuration where the deployment profile uses it /opt/codegraph/projects.yaml

Do not modify Python source files to configure a deployment. Do not add credentials to config.yaml, Git, command-line arguments, service-unit text, or captured logs.

Required production values

Start from the .env.example shipped with the exact installed release. At minimum, set:

POSTGRES_PASSWORD=<secret-from-approved-store>
API_JWT_SECRET=<random-secret-at-least-64-characters>
API_ADMIN_PASSWORD=<unique-initial-admin-secret>
ENVIRONMENT=production

Also configure every required Eva integrity key and at least one approved model-provider credential listed by that release. Replace placeholders with environment-specific values and keep sample values in the documentation only.

API_JWT_SECRET must be random and at least 64 characters. Rotating it invalidates existing tokens, so coordinate the restart and user reauthentication. Treat the initial admin credential as a bootstrap secret and rotate it under the customer’s identity procedure.

Network and browser origins

Set the externally reachable hosts and browser origins explicitly:

CORS_ALLOWED_ORIGINS=https://codegraph.customer.example
API_ALLOWED_HOSTS=codegraph.customer.example,api,codegraph-api

Do not use a wildcard origin with credentialed browser access. Terminate TLS according to the customer deployment design and expose only approved endpoints. Provider, repository, telemetry, and notification connections remain disabled or blocked until their credentials and network destinations are approved.

Non-secret application settings

Use config.yaml for typed, non-secret behavior such as enabled runtime capabilities, limits, provider selection, and ${VARIABLE} references. Keep the file aligned with the installed release: removed or unknown keys may fail validation, and copying a configuration from another version can silently change behavior only if that version still accepts the key.

For project-specific configuration, use supported project or dashboard surfaces. Raw storage paths are runtime-owned and must not be passed through user- or agent-facing calls.

Apply and verify a change

  1. Back up the current .env, config.yaml, and project declaration.
  2. Change only the approved values; preserve file owner and restricted permissions.
  3. Restart CodeGraph through the service manager.
  4. Run the shared readiness command from the installation guide.
  5. Verify authentication, project visibility, CPG freshness, and the integration that changed.

A successful parser load or /health response proves only part of the configuration. Production acceptance also requires container health, dependency readiness, access control, source provenance, and customer-specific connectivity evidence.

Troubleshooting boundaries

  • Startup rejects the JWT secret: generate a new 64+ character value and update the protected .env file.
  • Browser requests are rejected: compare the exact scheme and host with CORS_ALLOWED_ORIGINS and API_ALLOWED_HOSTS.
  • A provider is unavailable: verify that provider’s secret reference, egress policy, and CA trust; do not disable TLS verification.
  • A setting is unknown: compare it with the exact release’s .env.example and config.yaml instead of editing application source.

Contract sources

  • .env.example — current environment-variable inventory;
  • config.yaml — current non-secret configuration schema instance;
  • src/api/config.py documents implementation details; customers edit the supported configuration files;
  • src/config/unified_core/unified_config.py — YAML discovery and interpolation behavior;
  • scripts/run_app_stack_readiness.py — post-change runtime verification.

Next: Installation · Quick start

Report a documentation issue