Orchestrata Ultimate / Specs / 108-environment-installer

108-environment-installer: Environment Replication Installer

• What: A tracked, tested installer suite that replicates the complete orchestrata-ultimate working environment on a fresh machine: the Claude Code global layer (claude-env/install.sh), and the infrastructure fleet (claude-env/install-infra.sh) on either an Incus or a Docker backend, with Terraform as the IaC engine for the Incus path. - Why: The environment previously lived only on one workstation — global ~/.claude tools/hooks, session state, custom test runners,...

At a glance

Reading this spec

This spec defines a tracked, tested installer suite that replicates the complete orchestrata-ultimate working environment on a fresh machine. The environment previously lived on one workstation only: the global ~/.claude tools and hooks, session state, custom test runners and a hand-built 13-node Incus fleet. Nothing outside the repository was reproducible, so a disk failure or a second machine meant rebuilding from memory.

The design is two idempotent bash installers plus tracked assets. claude-env/install.sh sets up the Claude Code global layer and delegates the config layer to deploy/install-claude-config.sh, the SPEC-107 FR-013 deployment of claude/. claude-env/install-infra.sh sets up the infrastructure fleet on either an Incus or a Docker backend, with Terraform as the infrastructure-as-code engine on the Incus path, using the infra/rehearsal/ harness, and infra/docker/infra-compose.yml for the Docker fleet. Four user stories cover a fresh workstation bootstrap, backend choice between Incus and Docker, a safe re-run on a machine with an existing environment, and a raw machine on another network without access to private images.

The 25 requirement IDs (REQ-108-NNN) state the behaviour. The config layer deploys from a pinned git ref and verifies every file byte for byte. A second identical run is a no-op, verified in a clean Ubuntu 24.04 container. --dry-run prints every planned action and changes nothing. The infrastructure installer detects both Incus and Docker and reports both states before choosing. The compose file brings up Redis, a primary Neo4j, three workers and Memgraph with health checks, and waits until all are healthy. Subnet, cloud image and ready-timeout overrides are available through ORCHESTRATA_SUBNET, ORCHESTRATA_CLOUD_IMAGE and ORCHESTRATA_READY_TIMEOUT. No Memgraph-Enterprise artifact appears in any public or tracked binary form, so the Docker path uses the community image and documents the divergence. A semantic-search test fails loudly on an empty semantic graph instead of passing vacuously. Per-service backend selection (mix and match) is declared as a follow-up.

No code module cites this spec, since the deliverables are shell scripts, compose and Terraform files. The requirements traceability matrix lists every ID. The spec's own status line reads Complete and it tracks 2 files. No src/ symbol cites any of the 25 requirements, so measured trace coverage is 0.0%, and in tests/, 0 requirements are cited by a test-side @traces. All 25 requirements have no citing symbol; untraced means no @traces names the ID, and the behaviour may still exist in code that was never annotated.

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

No src/ symbol cites a requirement of this spec.

Checklists

checklists/requirements.md

The requirement list above comes from this file; 23 of 25 checkbox items are ticked.

Full spec text

Verbatim from specs/108-environment-installer/spec.md; headings are pushed down two levels.

SPEC-108: Environment Replication Installer

Metadata

• Spec ID: 108-environment-installer
• Title: Environment Replication Installer (claude-env)
• Author: Mohamed
• Status: Complete
• Created: 2026-07-21
• Last Updated: 2026-07-21
• Priority: P1
• Version: 1.0.0
• Extends: reproducibility plan R5 (plans/reproducibility-plan.md), infra IaC (infra/)

Overview

• What: A tracked, tested installer suite that replicates the complete orchestrata-ultimate working environment on a fresh machine: the Claude Code global layer (claude-env/install.sh), and the infrastructure fleet (claude-env/install-infra.sh) on either an Incus or a Docker backend, with Terraform as the IaC engine for the Incus path.
• Why: The environment previously lived only on one workstation — global ~/.claude tools/hooks, session state, custom test runners, and a hand-built 13-node Incus fleet. Nothing outside the repo was reproducible; a disk failure or second machine meant manual reconstruction from memory.
• How: Two idempotent bash installers plus tracked assets: claude-env/install.sh, which delegates the config layer to deploy/install-claude-config.sh (the SPEC-107 FR-013 deployment of claude/), infra/docker/infra-compose.yml (docker fleet), and the proven infra/rehearsal/ Terraform harness (incus fleet). Both installers are verified end-to-end on clean Ubuntu 24.04 (container for the global layer, VM for the infra layer).

Amended 2026-08-14 — claude-env/global/ is deleted. This spec originally made that directory a second, verbatim copy of the ~/.claude layer, rsynced into place by install.sh. SPEC-107 FR-013 then made claude/ the source of truth, deployed by deploy/install-claude-config.sh from a pinned git ref with a byte-exactness check that refuses success on any mismatch. Two installers were writing $HOME/.claude and only one verified its work; whichever ran last won.

Measured before removal: claude-env/global/ held zero files claude/ did not also have — every path unique to it was a .ruff_cache or .pytest_cache build artifact — and it had already drifted from claude/ on ~22 files within five hours of that tree existing. Its only distinct content was the drift.

Mohamed ruled claude/ canonical. FR-001 and SEC-001 below are amended accordingly; the fresh-machine entry point, the preflight and the infra half are unchanged, which is what this spec uniquely owns.

User Scenarios

US-108-001: Fresh workstation bootstrap

• As a developer with a new machine
• I want to clone the repo and run two scripts
• So that the full working environment (Claude tooling + infra fleet) exists without manual reconstruction
• Acceptance Criteria:
  • bash claude-env/install.sh populates ~/.claude (tools, hooks, commands, skills, settings) by delegating to deploy/install-claude-config.sh, which also creates ~/.claude/.venv on python3.14t and installs the tools' Python deps into it (amended 2026-08-14: the deps go into the deployment's own venv, not pip install --user).
  • bash claude-env/install-infra.sh builds a working infra fleet on the chosen backend.
  • The session CLI passes an init → begin → log-work → status round-trip on the fresh machine.

US-108-002: Backend choice (incus vs docker)

• As a developer on a machine where only one container runtime is viable
• I want to be shown which backends are present and choose one
• So that I am not forced into a runtime my machine cannot host
• Acceptance Criteria:
  • The installer detects BOTH incus and docker and reports each as present/absent.
  • Interactive mode prompts for the choice; --backend incus|docker + --yes is fully non-interactive.
  • The unchosen backend is untouched. Mix-and-match (per-service backend) is a declared follow-up, enabled by per-service .env derivation.

US-108-003: Safe re-run on a machine with an existing environment

• As a developer re-running the installer after an update
• I want existing files backed up and my customized settings never clobbered
• So that re-running is always safe
• Acceptance Criteria:
  • (amended 2026-08-14) Safety comes from the delegate rather than from backups: it deploys from a pinned git ref into a staging dir, then verifies every deployed file byte-for-byte against that commit and REFUSES success on any mismatch. A re-run that would change something says so; one that would not is a no-op.
  • settings.json is merged by claude/scripts/patch_settings.py, which is additive and idempotent and rewrites hook commands to the deployed venv's interpreter — replacing the older settings.json.new write-alongside convention.
  • A second identical run is a no-op (verified).

US-108-004: Raw machine on another network, no private-image access

• As a developer bootstrapping a machine that is NOT the production host
• I want the incus path to build the full public tier from checked-in cloud-init, with the private orchgraph tier's addition path stated
• So that a raw machine reaches a working fleet without any hand provisioning
• Acceptance Criteria:
  • The 8-node public tier (redis, neo4j primary + 3 replicas, 3 prolog/app) builds from infra/rawmachine + infra/cloud-init with zero manual steps.
  • Every service is systemd-supervised and survives a container restart.
  • The installer prints the exact private-release path for adding the orchgraph tier (never bundles it — Memgraph Enterprise License).
  • The build is proven on a machine that CANNOT reach the production fleet (network-enforced isolation, not honor-system).

Data Models

{
  "env_docker": {
    "description": ".env.docker emitted by the docker backend",
    "type": "object",
    "required": ["REDIS_HOST", "REDIS_PORT", "KG_ROUTING_URI", "KG_DATABASE", "MEMGRAPH_URI"],
    "properties": {
      "REDIS_HOST": {"type": "string", "const": "127.0.0.1"},
      "REDIS_PORT": {"type": "string", "const": "6379"},
      "KG_ROUTING_URI": {"type": "string", "pattern": "^bolt://"},
      "KG_DATABASE": {"type": "string", "const": "orchkg"},
      "MEMGRAPH_URI": {"type": "string", "pattern": "^bolt://"},
      "PROLOG_NODES": {"type": "string", "const": "", "description": "empty: janus in-process"}
    }
  }
}

Functional Requirements

• FR-001 Global-layer install (amended 2026-08-14): install.sh delegates the config layer to deploy/install-claude-config.sh, invoking it as --prefix "$CLAUDE_HOME" — the delegate reads CLAUDE_PREFIX/--prefix, so passing CLAUDE_HOME through the environment would be silently ignored and land every install in $HOME/.claude regardless of the caller's override. The delegate deploys claude/ from a pinned git ref, gives ~/.claude its own uv venv on free-threaded python3.14t, rewrites hook shebangs and settings.json commands to that interpreter, installs no symlinks, and refuses success unless every deployed file is byte-identical to the recorded commit. install.sh no longer copies files, installs Python deps, or merges settings.json: the venv replaces the pip install --user path (platform convention 2 — a deployment owns its venv) and patch_settings.py owns the settings merge.
• FR-002 Tool preflight (amended 2026-08-14): install.sh fails fast, before any mutation, listing every missing required tool (git rsync cmp uv python3) with per-distro install hints, and separately checks for the free-threaded interpreter ($FT_PYTHON, default ~/.local/bin/python3.14t) with a build hint rather than a package hint — on a fresh machine that is the likeliest blocker and the only one whose fix is a build. The list is now what the DELEGATE needs: uv replaced pip, and rsync/cmp are the delegate's copy and drift-check tools rather than this script's. A clean Ubuntu 24.04 container reproduces this path (rsync and git are both absent there).
• FR-003 Dry-run: --dry-run on both installers prints every action and mutates nothing.
• FR-004 Portability of bundled Python: every bundled tool/hook parses on Python ≥ 3.10 (PEP 758 parenthesis-free except is forbidden in the bundle — it is 3.14-only; the parenthesized form is used everywhere).
• FR-005 Backend detection and choice: install-infra.sh detects both incus and docker, reports both, and resolves the backend from --backend, else an interactive prompt, else (with --yes) prefers whichever is installed (incus on ties/none).
• FR-006 Terraform provisioning: terraform is installed (hashicorp apt repo / pacman) when absent, regardless of backend, because infra/terraform is the fleet's source of truth.
• FR-007 Incus fleet (raw machine): the 8-node public tier builds via terraform -chdir=infra/rawmachine apply with cloud-init provisioning (infra/cloud-init/*.yaml) on images:debian/12/cloud — the plain image variant has no cloud-init and MUST NOT be used. Overrides: ORCHESTRATA_SUBNET (default 10.95.0), ORCHESTRATA_CLOUD_IMAGE (locally imported alias for networks where the images: remote stalls), ORCHESTRATA_READY_TIMEOUT (default 1800s — four parallel neo4j tarball pulls dominate first boot). The production host's disaster drill remains infra/rehearsal (exec provisioning) — a separate concern.
• FR-011 Cloud-init service contract: every provisioned service runs under systemd supervision, binds the fleet interface (never localhost-only), and comes back after a container restart. Units that depend on a not-yet-deployed application are ConditionPathExists-guarded — inactive, never crash-looping.
• FR-012 Suite-on-fresh-fleet acceptance (trigger-armed): after the installer plus python scripts/bootstrap_graphs.py --all (the three seed pre-conditions established by the 2026-07-21 seed-data audit: canonical constraints on primary + each worker DB, the AST code-intelligence graph, non-empty Memgraph), the infra-subset suite passes on the machine's own fleet. Trigger: first raw-machine bring-up with the app venv installed (needs uv sync --dev + the FT janus/grpcio builds on that machine).
• FR-008 Docker fleet: infra/docker/infra-compose.yml brings up redis + neo4j primary + 3 workers + memgraph-community with healthchecks; up -d --wait gates on health; .env.docker is emitted pointing at the localhost port map.
• FR-009 License boundary: the orchgraph fork (Memgraph Enterprise) never enters a public artifact: the docker path uses the community image with the divergence documented in-file; the incus path requires the operator to supply the private image.
• FR-010 Session-state replication: context.json/context.md/context.history.md are tracked in the repo; the session CLI's init bootstraps a NEW project from cwd when no root exists (the pre-existing circular "run init → init needs a root" defect is fixed).

Error Conditions

API Contracts

claude-env/install.sh [--dry-run]                 # exit 0 success, 1 preflight/dep failure
claude-env/install-infra.sh
    [--backend incus|docker]                      # else interactive prompt
    [--yes|-y]                                    # non-interactive accept
    [-h|--help]
# env: CLAUDE_HOME (install.sh dest override),
#      ORCHESTRATA_SUBNET (incus fleet subnet, default 10.95.0),
#      ORCHESTRATA_CLOUD_IMAGE (base image override, default images:debian/12/cloud),
#      ORCHESTRATA_READY_TIMEOUT (service gate seconds, default 1800),
#      ORCHESTRATA_MIN_DISK_GB (disk preflight floor, default 12)

Security Requirements

• SEC-001 (amended 2026-08-14): No secret ever enters the deployed config layer — all credentials in claude/ are os.environ references, and deploy/install-claude-config.sh deploys from a pinned git ref, so anything committed is reviewable in a diff. (Formerly scoped to claude-env/global/, which is deleted; the grep sweep it described applied to a bundle that no longer exists.)
• SEC-002: The orchgraph Enterprise binary/image is never published publicly and never enters the docker compose file; the private GitLab release is the only distribution channel.
• SEC-003: .env files (real credentials) stay untracked; only .env.example and the generated .env.docker (localhost, default dev password) are written by tooling.
• SEC-004: install.sh runs unprivileged; install-infra.sh uses sudo only for package installs and runtime enablement.

Verification

The session-250 record previously here overclaimed: the docker run was container-level smoke only (fleet health + docker exec probes), with no app-level config wiring and no network isolation — the suite could have silently reached production infra. Retracted and replaced by the session-251 record below, which enforces isolation at the network layer.

Executed 2026-07-21 (sessions 250-251), all on fresh Ubuntu 24.04 images:

Related

• RTM page for 108-environment-installer
• All specs
• RTM overview
• Gates