From b32ce5ce48e46321da327f41805c948f700de0df Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Fri, 23 Oct 2026 15:04:31 -0400 Subject: [PATCH 1/2] docs: explain retained candidate deployment names Signed-off-by: Magnus Hedemark --- .../experimental-replacement-candidate.md | 53 ++++++++++++++++--- .../mainline-architecture-migration.md | 14 +++++ 2 files changed, 60 insertions(+), 7 deletions(-) diff --git a/docs/runbooks/experimental-replacement-candidate.md b/docs/runbooks/experimental-replacement-candidate.md index eddd9f8a..c1a9bda6 100644 --- a/docs/runbooks/experimental-replacement-candidate.md +++ b/docs/runbooks/experimental-replacement-candidate.md @@ -1,10 +1,49 @@ -# Experimental replacement candidate - -This runbook deploys the `groktocrawl-x` replacement candidate as an isolated -experiment. It does not replace the mainline GroktoCrawl project or switch the -existing production deployment. The candidate has its own Compose project, -containers, images, networks, volumes, database, and separately configurable -published ports. +# Retained candidate deployment topology + +The research architecture developed in GroktoCrawl X was adopted into canonical +GroktoCrawl in [ADR-0069](../adr/0069-adopt-bounded-research-substrate.md) and +[v1.0.0](https://github.com/groktopus/groktocrawl/releases/tag/v1.0.0). +This runbook maintains the isolated deployment topology introduced during that +experiment. Its `groktocrawl-x-candidate` project name and `candidate-*` service +names are retained compatibility identifiers, not a statement that the running +application comes from the former X repository. + +For a new standard deployment, use `docker-compose.yml` and the +[mainline migration runbook](mainline-architecture-migration.md) for its storage +prerequisites. For an existing candidate-topology deployment, preserve its +resolved configuration, project identity, networks, volumes, database, and +published ports. Applying this runbook does not switch an existing deployment +to the standard topology. + +## Where the legacy names come from + +`compose.experimental-candidate.yml` sets `name: groktocrawl-x-candidate` and +names its API service `candidate-agent`. With those defaults, Compose generates +`groktocrawl-x-candidate-candidate-agent-1`. Explicit `-p` or +`COMPOSE_PROJECT_NAME` values can override the project portion of that name. + +The same file points the candidate portal's `AGENT_BASE_URL` and the MCP +transport's `GROKTOCRAWL_URL` at `http://candidate-agent:8080`. +`compose.capture-https.yml` extends that service, and +`deploy/capture-https.cfg` resolves `candidate-agent:8080` through Docker DNS. +These are connected deployment contracts. Changing only a container or service +name can break internal routing; changing the project name can select different +networks and named volumes rather than the existing data. + +Identify application source by its image digest and OCI source/revision labels, +not the container name. Compare the image's platform manifest/config digest with +the release provenance; a Docker image ID is a config digest, not a multi-platform +index digest. If labels are missing or overridden, reconcile the exact build +revision and private resolved deployment configuration before attributing source. +The [v1.0.1 provenance](https://github.com/groktopus/groktocrawl/releases/download/v1.0.1/release-image-provenance.json) +records canonical source, revision, and platform digests for all ten release images. + +Renaming an existing deployment is a separate operator-led migration: inventory +project/service identities, external network attachments, proxy/MCP references, +ports and persistent stores; verify backups and rehearse cutover and rollback +in isolation. Do not rename the project or services, replace volumes, or use +`docker compose down -v` as a cosmetic cleanup. Archiving the former X source +repository does not stop containers or make their stored data disposable. The first candidate uses PostgreSQL as the authority for retained research artifacts and pgvector for semantic serving. Qdrant remains in the candidate as diff --git a/docs/runbooks/mainline-architecture-migration.md b/docs/runbooks/mainline-architecture-migration.md index 1917fd46..a85e0fab 100644 --- a/docs/runbooks/mainline-architecture-migration.md +++ b/docs/runbooks/mainline-architecture-migration.md @@ -19,6 +19,20 @@ project and `.env`. Do not change the Compose project name, rename the existing down -v`. PostgreSQL gets a new volume named from the project and `research_postgres_data`. +## Existing candidate-topology deployments + +A deployment may run canonical GroktoCrawl while retaining the Compose project +`groktocrawl-x-candidate` and service names such as `candidate-agent`. Those +names come from the maintained `compose.experimental-candidate.yml` topology; +they do not identify the source repository of the running application. See +[the candidate-topology naming and provenance guidance](experimental-replacement-candidate.md#where-the-legacy-names-come-from). + +This runbook's standard service names are not drop-in commands for that topology. +First reconcile the active resolved Compose file, image revision, service names, +ports and stores. Keep existing project, network and volume identities during +an application update. Moving to the standard topology or renaming resources +requires its own backed-up, rehearsed migration and rollback plan. + ## Prepare and back up 1. Pull and review the merged mainline release. Confirm the release contains the From a6fb119c49704cea95d5777aa68bce7819eb03e9 Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Fri, 23 Oct 2026 15:06:00 -0400 Subject: [PATCH 2/2] docs: trace active launch inputs before naming migrations Signed-off-by: Magnus Hedemark --- .../experimental-replacement-candidate.md | 15 +++++++++++++-- docs/runbooks/mainline-architecture-migration.md | 6 ++++-- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/docs/runbooks/experimental-replacement-candidate.md b/docs/runbooks/experimental-replacement-candidate.md index c1a9bda6..3e8024a9 100644 --- a/docs/runbooks/experimental-replacement-candidate.md +++ b/docs/runbooks/experimental-replacement-candidate.md @@ -19,8 +19,19 @@ to the standard topology. `compose.experimental-candidate.yml` sets `name: groktocrawl-x-candidate` and names its API service `candidate-agent`. With those defaults, Compose generates -`groktocrawl-x-candidate-candidate-agent-1`. Explicit `-p` or -`COMPOSE_PROJECT_NAME` values can override the project portion of that name. +`groktocrawl-x-candidate-candidate-agent-1`. The update command below also +passes `-p groktocrawl-x-candidate` explicitly. Compose chooses `-p` before +`COMPOSE_PROJECT_NAME`, then the top-level `name` from its loaded files; a +configured `container_name` can replace the generated container name. + +A promoted deployment can load private generated Compose files outside Git +rather than this template. Record the launch arguments and actual file paths, +then reconcile their project name and service definitions with Docker's Compose +labels. Do not assume a historical checkout is still an active input. Updating +the checked-in template cannot rename a deployment that keeps an explicit `-p` +argument or a private resolved file. This repository does not provide a generator +for operator-maintained `promotion.private.json` or launch `command.json` files. +Keep those files private: resolved configuration can contain credentials. The same file points the candidate portal's `AGENT_BASE_URL` and the MCP transport's `GROKTOCRAWL_URL` at `http://candidate-agent:8080`. diff --git a/docs/runbooks/mainline-architecture-migration.md b/docs/runbooks/mainline-architecture-migration.md index a85e0fab..7f21c61e 100644 --- a/docs/runbooks/mainline-architecture-migration.md +++ b/docs/runbooks/mainline-architecture-migration.md @@ -23,8 +23,10 @@ down -v`. PostgreSQL gets a new volume named from the project and A deployment may run canonical GroktoCrawl while retaining the Compose project `groktocrawl-x-candidate` and service names such as `candidate-agent`. Those -names come from the maintained `compose.experimental-candidate.yml` topology; -they do not identify the source repository of the running application. See +names match the retained `compose.experimental-candidate.yml` topology, but the +active inputs may be an explicit `-p` argument and private generated Compose +files outside Git. Neither the names nor an old checkout identify the running +application's source repository or the files currently controlling deployment. See [the candidate-topology naming and provenance guidance](experimental-replacement-candidate.md#where-the-legacy-names-come-from). This runbook's standard service names are not drop-in commands for that topology.