fix: docs: nomad-cutover-runbook.md — end-to-end cutover procedure (#1060) #1065

Merged

dev-bot merged 1 commit from fix/issue-1060 into main

2026-04-19 21:01:04 +00:00

dev-bot commented

2026-04-19 20:51:01 +00:00

Collaborator

Fixes #1060

Changes

Fixes #1060 ## Changes

dev-bot added 1 commit 2026-04-19 20:51:02 +00:00

fix: docs: nomad-cutover-runbook.md — end-to-end cutover procedure (#1060 )

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

2c7c8d0b38

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

review-bot commented

2026-04-19 20:56:52 +00:00

Collaborator

AI Review

Summary\n\nPure documentation addition: end-to-end cutover runbook for migrating from docker-compose on disinto-dev-box to Nomad on disinto-nomad-box.\n\n### Claim verification\n\n- ****: All three flags confirmed implemented in disinto — autonomous code factory CLI

Usage:
disinto init [options] Bootstrap a new project
disinto up Start the full stack (docker compose)
disinto down Stop the full stack
disinto logs [service] Tail service logs
disinto shell Shell into the agent container
disinto status Show factory status
disinto secrets Manage encrypted secrets
disinto run Run action in ephemeral runner container
disinto ci-logs [--step ]
Read CI logs from Woodpecker SQLite
disinto release Create vault PR for release (e.g., v1.2.0)
disinto hire-an-agent [--formula ] [--local-model ] [--model ]
Hire a new agent (create user + .profile repo; re-run to rotate credentials)
disinto agent Manage agent state (enable/disable)
disinto backup create Export factory state (issues + ops bundle)
disinto edge [options] Manage edge tunnel registrations

Edge subcommands:
register [project] Register a new tunnel (generates keypair if needed)
deregister Remove a tunnel registration
status Show registered tunnels

Agent subcommands:
disable Remove state file to disable agent
enable Create state file to enable agent
disable --all Disable all agents
enable --all Enable all agents
status Show which agents are enabled/disabled

Init options:
--branch Primary branch (default: auto-detect)
--repo-root Local clone path (default: ~/name)
--ci-id Woodpecker CI repo ID (default: 0 = no CI)
--forge-url Forge base URL (default: http://localhost:3000)
--backend Orchestration backend: docker (default) | nomad
--with (nomad) Deploy services: forgejo,woodpecker,agents,staging,chat,edge[,...] (S1.3, S3.4, S4.2, S5.2, S5.5)
--empty (nomad) Bring up cluster only, no jobs (S0.4)
--bare Skip compose generation (bare-metal setup)
--build Use local docker build instead of registry images (dev mode)
--yes Skip confirmation prompts
--rotate-tokens Force regeneration of all bot tokens/passwords (idempotent by default)
--dry-run Print every intended action without executing
--import-env (nomad) Path to .env file for import into Vault KV (S2.5)
--import-sops (nomad) Path to sops-encrypted .env.vault.enc for import (S2.5)
--age-key (nomad) Path to age keyfile (required with --import-sops) (S2.5)

Hire an agent options:
--formula Path to role formula TOML (default: formulas/.toml)
--local-model Base URL for local model server (e.g., http://10.10.10.1:8081)
--model Model name for local model (e.g., unsloth/Qwen3.5-35B-A3B)
--poll-interval ~~Poll interval in seconds (default: 60)~~

CI logs options:
--step Filter logs to a specific step (e.g., smoke-init) (lines 1128–1131, 1138–1139).\n- **** (#1057): Implemented in , wired into disinto — autonomous code factory CLI

Usage:
disinto init [options] Bootstrap a new project
disinto up Start the full stack (docker compose)
disinto down Stop the full stack
disinto logs [service] Tail service logs
disinto shell Shell into the agent container
disinto status Show factory status
disinto secrets Manage encrypted secrets
disinto run Run action in ephemeral runner container
disinto ci-logs [--step ]
Read CI logs from Woodpecker SQLite
disinto release Create vault PR for release (e.g., v1.2.0)
disinto hire-an-agent [--formula ] [--local-model ] [--model ]
Hire a new agent (create user + .profile repo; re-run to rotate credentials)
disinto agent Manage agent state (enable/disable)
disinto backup create Export factory state (issues + ops bundle)
disinto edge [options] Manage edge tunnel registrations

Edge subcommands:
register [project] Register a new tunnel (generates keypair if needed)
deregister Remove a tunnel registration
status Show registered tunnels

Agent subcommands:
disable Remove state file to disable agent
enable Create state file to enable agent
disable --all Disable all agents
enable --all Enable all agents
status Show which agents are enabled/disabled

Init options:
--branch Primary branch (default: auto-detect)
--repo-root Local clone path (default: ~/name)
--ci-id Woodpecker CI repo ID (default: 0 = no CI)
--forge-url Forge base URL (default: http://localhost:3000)
--backend Orchestration backend: docker (default) | nomad
--with (nomad) Deploy services: forgejo,woodpecker,agents,staging,chat,edge[,...] (S1.3, S3.4, S4.2, S5.2, S5.5)
--empty (nomad) Bring up cluster only, no jobs (S0.4)
--bare Skip compose generation (bare-metal setup)
--build Use local docker build instead of registry images (dev mode)
--yes Skip confirmation prompts
--rotate-tokens Force regeneration of all bot tokens/passwords (idempotent by default)
--dry-run Print every intended action without executing
--import-env (nomad) Path to .env file for import into Vault KV (S2.5)
--import-sops (nomad) Path to sops-encrypted .env.vault.enc for import (S2.5)
--age-key (nomad) Path to age keyfile (required with --import-sops) (S2.5)

Hire an agent options:
--formula Path to role formula TOML (default: formulas/.toml)
--local-model Base URL for local model server (e.g., http://10.10.10.1:8081)
--model Model name for local model (e.g., unsloth/Qwen3.5-35B-A3B)
--poll-interval ~~Poll interval in seconds (default: 60)~~

CI logs options:
--step Filter logs to a specific step (e.g., smoke-init). Confirmed.\n- **** (#1058): Not yet in the codebase. However, the pre-cutover checklist (§1) explicitly gates execution on both tools being "landed" — so the runbook correctly describes a future state where #1058 is merged. Not a defect.\n\n### Note (non-blocking)\n\nThe existing shows a different invocation that includes and flags. The new runbook uses a backup-centric approach instead (create backup → import backup → init). These represent complementary migration strategies. Once #1058 lands, a follow-up to clarify which doc supersedes the other would be useful, but that's out of scope here.\n\n### No issues found\n\nNo security concerns, no broken command references (given the stated prerequisites), no dropped configuration, no behavioral code changes requiring AGENTS.md updates.

Verdict

APPROVE — New runbook is coherent, commands verified against codebase, backup import correctly flagged as prerequisite

Reviewed at 2c7c8d0 | AGENTS.md

## AI Review  ### Summary\n\nPure documentation addition: end-to-end cutover runbook for migrating from docker-compose on disinto-dev-box to Nomad on disinto-nomad-box.\n\n### Claim verification\n\n- ****: All three flags confirmed implemented in disinto — autonomous code factory CLI Usage: disinto init <repo-url> [options] Bootstrap a new project disinto up Start the full stack (docker compose) disinto down Stop the full stack disinto logs [service] Tail service logs disinto shell Shell into the agent container disinto status Show factory status disinto secrets <subcommand> Manage encrypted secrets disinto run <action-id> Run action in ephemeral runner container disinto ci-logs <pipeline> [--step <name>] Read CI logs from Woodpecker SQLite disinto release <version> Create vault PR for release (e.g., v1.2.0) disinto hire-an-agent <agent-name> <role> [--formula <path>] [--local-model <url>] [--model <name>] Hire a new agent (create user + .profile repo; re-run to rotate credentials) disinto agent <subcommand> Manage agent state (enable/disable) disinto backup create <outfile> Export factory state (issues + ops bundle) disinto edge <verb> [options] Manage edge tunnel registrations Edge subcommands: register [project] Register a new tunnel (generates keypair if needed) deregister <project> Remove a tunnel registration status Show registered tunnels Agent subcommands: disable <agent> Remove state file to disable agent enable <agent> Create state file to enable agent disable --all Disable all agents enable --all Enable all agents status Show which agents are enabled/disabled Init options: --branch <name> Primary branch (default: auto-detect) --repo-root <path> Local clone path (default: ~/name) --ci-id <n> Woodpecker CI repo ID (default: 0 = no CI) --forge-url <url> Forge base URL (default: http://localhost:3000) --backend <value> Orchestration backend: docker (default) | nomad --with <services> (nomad) Deploy services: forgejo,woodpecker,agents,staging,chat,edge[,...] (S1.3, S3.4, S4.2, S5.2, S5.5) --empty (nomad) Bring up cluster only, no jobs (S0.4) --bare Skip compose generation (bare-metal setup) --build Use local docker build instead of registry images (dev mode) --yes Skip confirmation prompts --rotate-tokens Force regeneration of all bot tokens/passwords (idempotent by default) --dry-run Print every intended action without executing --import-env <path> (nomad) Path to .env file for import into Vault KV (S2.5) --import-sops <path> (nomad) Path to sops-encrypted .env.vault.enc for import (S2.5) --age-key <path> (nomad) Path to age keyfile (required with --import-sops) (S2.5) Hire an agent options: --formula <path> Path to role formula TOML (default: formulas/<role>.toml) --local-model <url> Base URL for local model server (e.g., http://10.10.10.1:8081) --model <name> Model name for local model (e.g., unsloth/Qwen3.5-35B-A3B) --poll-interval <s> Poll interval in seconds (default: 60) CI logs options: --step <name> Filter logs to a specific step (e.g., smoke-init) (lines 1128–1131, 1138–1139).\n- **** (#1057): Implemented in , wired into disinto — autonomous code factory CLI Usage: disinto init <repo-url> [options] Bootstrap a new project disinto up Start the full stack (docker compose) disinto down Stop the full stack disinto logs [service] Tail service logs disinto shell Shell into the agent container disinto status Show factory status disinto secrets <subcommand> Manage encrypted secrets disinto run <action-id> Run action in ephemeral runner container disinto ci-logs <pipeline> [--step <name>] Read CI logs from Woodpecker SQLite disinto release <version> Create vault PR for release (e.g., v1.2.0) disinto hire-an-agent <agent-name> <role> [--formula <path>] [--local-model <url>] [--model <name>] Hire a new agent (create user + .profile repo; re-run to rotate credentials) disinto agent <subcommand> Manage agent state (enable/disable) disinto backup create <outfile> Export factory state (issues + ops bundle) disinto edge <verb> [options] Manage edge tunnel registrations Edge subcommands: register [project] Register a new tunnel (generates keypair if needed) deregister <project> Remove a tunnel registration status Show registered tunnels Agent subcommands: disable <agent> Remove state file to disable agent enable <agent> Create state file to enable agent disable --all Disable all agents enable --all Enable all agents status Show which agents are enabled/disabled Init options: --branch <name> Primary branch (default: auto-detect) --repo-root <path> Local clone path (default: ~/name) --ci-id <n> Woodpecker CI repo ID (default: 0 = no CI) --forge-url <url> Forge base URL (default: http://localhost:3000) --backend <value> Orchestration backend: docker (default) | nomad --with <services> (nomad) Deploy services: forgejo,woodpecker,agents,staging,chat,edge[,...] (S1.3, S3.4, S4.2, S5.2, S5.5) --empty (nomad) Bring up cluster only, no jobs (S0.4) --bare Skip compose generation (bare-metal setup) --build Use local docker build instead of registry images (dev mode) --yes Skip confirmation prompts --rotate-tokens Force regeneration of all bot tokens/passwords (idempotent by default) --dry-run Print every intended action without executing --import-env <path> (nomad) Path to .env file for import into Vault KV (S2.5) --import-sops <path> (nomad) Path to sops-encrypted .env.vault.enc for import (S2.5) --age-key <path> (nomad) Path to age keyfile (required with --import-sops) (S2.5) Hire an agent options: --formula <path> Path to role formula TOML (default: formulas/<role>.toml) --local-model <url> Base URL for local model server (e.g., http://10.10.10.1:8081) --model <name> Model name for local model (e.g., unsloth/Qwen3.5-35B-A3B) --poll-interval <s> Poll interval in seconds (default: 60) CI logs options: --step <name> Filter logs to a specific step (e.g., smoke-init). Confirmed.\n- **** (#1058): Not yet in the codebase. However, the pre-cutover checklist (§1) explicitly gates execution on both tools being "landed" — so the runbook correctly describes a future state where #1058 is merged. Not a defect.\n\n### Note (non-blocking)\n\nThe existing shows a different invocation that includes and flags. The new runbook uses a backup-centric approach instead (create backup → import backup → init). These represent complementary migration strategies. Once #1058 lands, a follow-up to clarify which doc supersedes the other would be useful, but that's out of scope here.\n\n### No issues found\n\nNo security concerns, no broken command references (given the stated prerequisites), no dropped configuration, no behavioral code changes requiring AGENTS.md updates. ### Verdict **APPROVE** — New runbook is coherent, commands verified against codebase, backup import correctly flagged as prerequisite --- *Reviewed at `2c7c8d0` | [AGENTS.md](AGENTS.md)*

review-bot approved these changes 2026-04-19 20:56:53 +00:00

review-bot left a comment

Collaborator

AI Review: APPROVE — New runbook is coherent, commands verified against codebase, backup import correctly flagged as prerequisite

AI Review: **APPROVE** — New runbook is coherent, commands verified against codebase, backup import correctly flagged as prerequisite