Install CodeGraph on a customer Ubuntu server

The supported customer path installs the core Compose stack on a customer-owned Ubuntu 22.04/24.04 VM. Run it as a professional system administrator with an approved immutable release ref, backup destination, network policy, and secret-management procedure.

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.

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.

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 only MCP 2026-07-28, native JSON arrays/objects, authorization, and either stdio or Streamable HTTP POST /mcp. Legacy HTTP+SSE, protocol fallback, and JSON-encoded containers are not supported. 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; the retired Codex 0.147 root-manifest workaround is archived.
• 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

Treat the two model choices independently: the CodeGraph server model performs generation and embedding inside the runtime, while the Codex/OpenCode agent model plans steps and invokes MCP.

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 and pass an acceptance scenario.

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.

Exact browser versions, production ARM64 support, HA/Kubernetes, and one universal context-window floor are outside this single-VM contract and require a separate deployment decision.

1. Inspect the plan

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

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

Before starting the service, edit /opt/codegraph/.env through the customer’s protected secret procedure. At minimum, replace the empty values for:

• POSTGRES_PASSWORD;
• API_JWT_SECRET with a random value of at least 64 characters;
• API_ADMIN_PASSWORD with a unique initial administrator credential;
• the approved LLM-provider credential;
• every additional required key identified by the release .env.example.

Keep the file root-owned with restricted permissions. Do not record secret values in tickets, shell history, screenshots, or 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.

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.

Related external documentation

Configuration · Quick start · MCP · LLM security · OpenCode