Install CodeGraph on a customer Ubuntu server

The customer profile installs the core Compose stack on a dedicated Ubuntu 22.04/24.04 VM. This guide is for system administrators. Prepare the approved release tag or commit, backup destination, network policy, and procedure for handling secrets.

This profile does not enable the CodeGraph public domains, leads service, self-hosted Sentry, or GitHub autodeploy by default.

Prerequisites

• a dedicated Ubuntu 22.04/24.04 VM with administrative access;
• access to an approved CodeGraph repository or clean release checkout;
• an immutable tag or commit approved for the pilot;
• outbound access or an internal mirror for required packages and images;
• customer-owned DNS, TLS, backup, and secret storage decisions.

Never place a username, token, or password in the repository URL or command line. Use an SSH agent or the host credential helper for a private mirror.

Server, client, and AI model requirements

The following baseline covers the supported single-VM customer deployment. Select a VM profile for the expected CPG size, concurrent imports, and workflow load. The smallest profile verifies an installation; production workload sizing starts with the recommended or large profile.

Before production, test the selected VM size with representative imports and concurrent workflows. Measure import duration, CPU load, memory use, and disk use; adjust resources from these results.

CodeGraph server

The supported server OS is Ubuntu 22.04/24.04 on x86_64. ARM64 production support requires a deployment-specific validation of images and GoCPG artifacts. Install Docker Engine with the Compose plugin, Git, Bash, curl, openssl, time synchronization, and access to the immutable release ref. A GPU is not required when the deployment uses a remote LLM provider. Size local inference separately for the selected model’s VRAM, RAM, and disk needs.

Normally expose only HTTPS 443. HTTP 80 is optional for redirects or certificate issuance, and SSH 22 must be limited to the administrative network. Treat API 8000, dashboard 3100, MCP 27495, GoCPG 50051, OpenViking 1933/8020, and Temporal 7233/8233 as internal ports unless the approved network design explicitly says otherwise. The server needs egress or internal mirrors for packages, containers, and the repository, plus approved routes to the model provider, DNS, and NTP.

Published Docker ports can bypass UFW rules. Check Compose port bindings and the host/network firewall from an external machine; UFW configuration alone does not establish isolation. See Docker firewall prerequisites.

Storage must cover Docker volumes, PostgreSQL, workspace files, CPGs, OpenViking, logs, and upgrade headroom. Before the pilot, provision a separate backup target and prove restore for .env, config.yaml, projects.yaml, application data, workspace data, OpenViking, and persistent volumes. Secret, TLS, CORS, and host controls are defined in the configuration guide.

Client software

• The dashboard requires a current vendor-supported browser with JavaScript, HTTPS, and WSS. Provision the URL, user account, tenant/project scope, and required role before onboarding.
• An MCP client must support MCP 2026-07-28, native JSON arrays/objects, authorization, and either stdio or Streamable HTTP POST /mcp. Configure and verify a tool call with the MCP operator guide.
• Codex requires Windows 10/11 with PowerShell 5+ or Linux/macOS with Bash 4+, Git, recommended Python 3.11+, at least 1 GB free for client home/cache/logs, Codex 0.149.1+, and a native Codex plugin package. The client needs CodeGraph API/MCP connectivity; OpenViking connectivity is required when durable memory is enabled. Use the current Codex installation and plugin package flow.
• OpenCode requires a runtime with @opencode-ai/plugin >=1.2.0, the opencode-codegraph 0.1.38 npm package, and CodeGraph API connectivity. The current launcher defaults to openai/gpt-5.4; replace it only through supported configuration with an approved model. Follow the OpenCode quick start and the integration guide.

AI models

Choose models for two tasks. The CodeGraph server model generates responses and data embeddings. The Codex/OpenCode agent model plans steps and calls MCP tools.

The server runtime supports the local, codex_subscription, gigachat, openai, and yandex provider types. A remote provider needs an approved tenant endpoint and credential, TLS, quotas, and support for UTF-8 system/user prompts. The model must handle English and Russian text, code, diffs, and CPG summaries; accept temperature, max_tokens, and timeout controls; and return diagnosable errors. Provider-specific setup is documented for Yandex AI Studio and GigaChat.

Choose at least a 32K context window for an initial pilot; 64K+ is preferred for large repositories and multi-step tasks. The actual prompt, response, and safety margin must fit the selected model. Verify this with a representative pilot task.

The agent model must reliably call tools from JSON Schema, preserve exact story/task/project identifiers and source refs, execute multi-step loops, and report a refusal or unavailable tool explicitly. The embedding model must cover English, Russian, and source code, support batching, and keep a stable vector dimension within an index. Changing the embedding model or dimension requires an explicit reindex; do not mix incompatible vectors in one index.

Before enabling an external model, record its endpoint, tenant, processing region, training use, retention, TLS, access logs, quotas, cost, fallback, and incident path. See the LLM security guide for the data-egress boundary and DLP verification.

Acceptance checks

Accept the deployment only after six independent checks:

1. the install receipt names the approved commit, required containers are healthy, and shared readiness passes;
2. a user signs in through the HTTPS browser flow, opens the project, and the browser WebSocket works;
3. Codex or OpenCode performs an authorized MCP tool call, not discovery alone;
4. the server model completes a synthetic generation and embedding request;
5. DLP blocks or masks a synthetic canary without using a real secret;
6. a backup restores successfully in a test environment with the project scope preserved.

For ARM64, a highly available cluster, or Kubernetes, prepare a separate installation design and verification procedure.

1. Inspect the plan

From the approved release checkout, run the non-mutating plan first:

The commands below use Bash. Before running them, replace <immutable-tag-or-commit> with the approved tag or full commit hash and <approved-repository-url> with the repository URL authorized for this deployment. Replace the complete placeholder values, including angle brackets, and keep the quotation marks. The checkout must contain scripts/install-ubuntu.sh from that release.

bash scripts/install-ubuntu.sh \
  --profile customer-baremetal \
  --source-ref "<immutable-tag-or-commit>" \
  --plan

Confirm the effective profile and source ref. The customer plan must keep the leads service, port 8001, public CodeGraph nginx hosts, self-hosted Sentry, and autodeploy disabled unless your approved deployment design explicitly adds them.

2. Install the approved release

sudo bash scripts/install-ubuntu.sh \
  --profile customer-baremetal \
  --source-repository "<approved-repository-url>" \
  --source-ref "<immutable-tag-or-commit>"

The installer resolves the ref to a commit and writes the receipt to /opt/codegraph/data/deployment-evidence/install-source.json. Continue when the checkout is clean, the ref is verified, and the resolved commit matches the approved release.

3. Configure secrets

On a fresh installation, the installer generates POSTGRES_PASSWORD, API_JWT_SECRET, API_ADMIN_PASSWORD, and other runtime secrets. It stores .env with owner root, group codegraph, and mode 0640. The customer profile does not print generated credentials. When updating an existing installation, the installer preserves its .env and adds missing runtime defaults. Do not replace existing database passwords or signing keys as part of a routine update: rotate them through a coordinated procedure.

Before starting the service, use the customer’s protected secret procedure to inspect /opt/codegraph/.env, select the approved model provider, and replace that provider’s credential placeholders. Check additional required keys against the release .env.example. Retrieve the initial administrator credential through the protected procedure. Keep secret values out of tickets, shell history, screenshots, and installation evidence. See Configuration.

4. Start and verify

sudo systemctl start codegraph
sudo systemctl status codegraph --no-pager
cd /opt/codegraph
sudo docker compose -f docker-compose.yml ps
sudo docker compose -f docker-compose.yml exec -T api \
  python scripts/run_app_stack_readiness.py --network compose --include-mcp --mcp-auth-required

Installation is ready for user onboarding when the service is active, required containers are healthy, the readiness command passes, the source receipt names the approved commit, and customer access controls have been verified. Record release readiness from this complete checklist.

Once the services pass verification, follow the quick start to sign in to the dashboard and import the first repository. Then configure automatic project checks using the guides below.

Configure automatic project checks

After importing the repository, connect its events. A push webhook supplies new commits for CPG updates; pull request or merge request events start review preparation. Follow the guide for your Git server:

• GitHub: repository connection, webhooks and pull request review.
• GitLab: repository connection, webhooks and merge request review.
• GitVerse: webhooks, synchronization and pull request review publication.
• SourceCraft: repository coordinates, webhooks and merge request review.

Choose events for the branches you use and verify a test push: wait for the synchronization job, then compare the CPG commit with the repository commit. For a PR/MR, inspect the review result and its publication in the target request.

Architecture control explains how to describe components and allowed dependencies in YAML, validate rules and apply them when checking changes.

To run checks regularly, configure automatic project audits: choose the cadence, time zone, service account and missed-run policy. Verify the first run and its saved report.

Update and rollback

Before an update, back up /opt/codegraph/.env, config.yaml, projects.yaml, application data, workspace data, OpenViking data, and persistent Docker volumes. Preserve the receipt for the current revision.

Apply an update with the same installer and a new immutable ref. To roll back, restore the matching backup and run the installer with the previous-known-good immutable ref. Do not request volume cleanup during rollback unless the restore procedure explicitly replaces those volumes.

Verify the restored deployment

Restore the backup into a separate test environment with the same release tag or commit. Prepare a copy of .env, encryption keys, and configuration files. Restore PostgreSQL from its logical backup; preserve directory structure and permissions for project files and CPGs. Include the volumes and OpenViking data used by the deployment.

After startup, run these checks in order:

1. Compare the PostgreSQL migration revision and project list with the backup.
2. Sign in with a restored account and open the project. Check its group, analysis scope, and saved metadata.
3. Query the restored CPG and compare the result with a control query recorded before the backup.
4. Check retrieval from restored OpenViking data when durable memory is enabled.
5. Run the readiness command from step 4 and the client, model, and DLP checks in “Acceptance checks.”

Record the recovery duration, backup creation time, verified release, and results. These records show how long recovery takes and which period of changes the backup covers.

Related guides

Configuration · Quick start · MCP · LLM security · OpenCode