kevinveenbirkenbachandClaude Opus 4.7
a26bfc4e94
Module moves (with imports, paths, argv literals, scripts, docs, and
parents[N] formulas updated in lockstep):
- cli/deploy -> cli/administration/deploy
- cli/validate/inventory -> cli/administration/inventory/validate
- cli/vault -> cli/administration/secrets/vault
- cli/administration/inventory/encrypt -> cli/administration/secrets/seal
- cli/mirror -> cli/contributing/mirror
The new cli/administration/secrets cluster collocates the whole-file
ansible-vault wrapper next to the inventory-aware per-field sealer.
The user-facing CLI subcommand paths follow the package layout, e.g.
"infinito administration deploy dedicated <inv>" and
"infinito administration inventory validate <inv>".
Help system redesign in cli/core/{discovery,help,app}.py:
- Discovery now distinguishes runnable commands (directories with
__main__.py) from category folders (directories that only group
further commands). Empty support packages are filtered out.
- Each category folder MAY carry a README.md; its H1 heading is used
as the title and its first paragraph as the one-line description in
the help output.
- "infinito" / "infinito --help" prints only the top-level entries
(one level deep). "infinito <category>" navigates into a folder and
shows its sub-folders and commands one level deep, with the README
title as the page heading and the invocation as a dim subtitle.
- New "--tree [N]" flag walks the tree under the (optional) path
prefix recursively. N caps the depth (1-based); omit N for an
unbounded walk. The output uses Unicode tree connectors, an emoji
per entry (folder for categories, gear for commands), a globally
aligned description column, and multi-line wrapped descriptions
with tree-continuity bars on continuation lines.
- Category and command listings use the full invocation
("infinito meta callorder") rather than the bare leaf name, so the
output is copy-pasteable.
Convention doc + 17 CLI READMEs:
- New docs/contributing/artefact/files/cli/readme_md.md describes the
H1+paragraph layout the help system reads, and how it differs from
role/docs READMEs.
- README.md added for cli/{administration, build, contributing, meta}
and their immediate sub-folders, plus cli/meta/roles/applications
and its resolution sub-folder. Each follows the "title with trailing
emoji + single descriptive paragraph" convention.
Mirror resolver/sync description strings (the help system reads them
from argparse --help output) added so they no longer surface as
"options:" in the global index. cli/mirror/cleanup already had a
description and is unchanged.
Fixes uncovered by the move:
- import unittest.mock added to four dedicated-deploy tests so
unittest.mock.patch resolves under stdlib unittest discovery
(Python 3.13 no longer surfaces unittest.mock through "import
unittest" alone).
- parents[N] index in the new
cli/administration/inventory/validate/__init__.py corrected from
3 to 4 to match the deeper layout.
- test_paths.INVENTORY_VALIDATOR_PATH assertion and test_runner
substring assertions updated to match the new validator path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5.5 KiB
Local Deploy 🚀
Contributor guidance for running deploys against a local development stack on your workstation. For production deploy guidance see the Deploy Guide. For the agent-driven role iteration loop see role.md. For the matrix-variant mechanism that this page references throughout see variants.md.
Entry Points 🧭
Two layers exist for invoking a local deploy:
| Layer | When to use |
|---|---|
make deploy-* targets in the Makefile |
Default. Stable, opinionated wrappers tuned for the local-dev / CI-on-laptop flow. |
infinito administration deploy development <subcommand> (Python CLI) |
Direct invocation when you need a flag the make targets do not expose, or when you script multi-step flows yourself. |
The make targets ultimately call the same CLI, so any behaviour described here applies to both.
First-Run Baseline 📦
Use deploy-fresh-purged-apps to bring up a clean slate:
make deploy-fresh-purged-apps APPS="<role> <role>" FULL_CYCLE=true
FULL_CYCLE=trueadds the async update pass (pass 2) and SHOULD stay on for the baseline. The behaviour, per-variant interleaving, and--full-cycleflag mechanics are documented in variants.md.- The wrapper runs init, then deploy. Init materialises the inventory under
${INVENTORY_DIR}(set by inventory.sh via resolve.sh). - For roles with a
roles/<role>/meta/variants.ymlthe init step produces one inventory folder per variant; the deploy step iterates them. Folder layout, round semantics, cleanup rules, and the link to the file-format reference live in variants.md.
Edit / Fix / Redeploy Loop 🔁
Default redeploy after a local code change:
make deploy-reuse-kept-apps APPS="<role>"
- Reuses the existing inventory, keeps app state, runs the deploy only.
- For multi-variant roles you MUST set
VARIANT=<idx>(see Pinning A Single Variant) so the reuse path targets the round's folder. WithoutVARIANT, the reuse target points at<INVENTORY_DIR>which only exists for single-variant roles.
If the reuse path keeps reproducing the same failure and you want to test whether app entity state is involved:
make deploy-reuse-purged-apps APPS="<role>"
This purges the app's containers + volumes + Ansible-managed state on the host, then re-deploys. Use it once, then return to deploy-reuse-kept-apps. Do NOT loop on deploy-reuse-purged-apps; if the failure survives a single purge it is not a state issue.
Only return to deploy-fresh-purged-apps when you have concrete evidence that the inventory or the host stack itself is broken (for example DNS or network failures during the deploy).
Pinning A Single Variant 🎯
For multi-variant roles you MAY restrict any of the make targets above (and the dev CLI subcommands) to a single matrix round by setting VARIANT=<idx>:
# Variant 1 baseline only (no full matrix):
VARIANT=1 make deploy-fresh-purged-apps APPS="<role>" FULL_CYCLE=true
# Edit-fix-redeploy loop pinned to that variant:
VARIANT=1 make deploy-reuse-kept-apps APPS="<role>"
Pinning is sticky: when iterating with VARIANT=<idx>, you MUST set it on every command in the iteration. Mixing pinned and unpinned commands silently retargets a different folder. The full semantics (single-folder mode, no inter-round cleanup, out-of-range error) live in variants.md.
Direct CLI Invocation ⚙️
When you need a flag the make wrappers do not expose, call the dev CLI directly:
infinito administration deploy development init --inventory-dir "${INVENTORY_DIR}" --apps "<role>"
infinito administration deploy development deploy --inventory-dir "${INVENTORY_DIR}" --apps "<role>" [--variant <idx>] [--debug]
--inventory-diris always the BASE path. The wrapper appends the-<round>suffix internally for matrix folders.--variant <idx>pins to one round (same semantics as theVARIANTenv-var).- The CLI prints the planned folder list at init time and the per-round summary at deploy time, so you can confirm the matrix shape before any work happens.
Inspect Live State 🔍
Use make exec to drop into the running container shell. The repo is mounted at /opt/src/infinito, so code changes are visible immediately. Inspect logs and current state BEFORE redeploying so the failing snapshot stays available.
For TLS-enabled local sites, run make trust-ca once after the first deploy and restart the browser; alternatively use curl -k on the command line.
Reference Files 📌
| File | Purpose |
|---|---|
| Makefile | All deploy-* and make exec / make trust-ca targets. |
| dev CLI tree | Python CLI for init, deploy, up, down, exec, etc. |
| inventory.sh | Resolves INVENTORY_DIR, INVENTORY_FILE, and INVENTORY_VARS_FILE for the dev CLI. |
| local deploy scripts | Bash glue behind the make targets (fresh / reuse / purge variants). |
| variants.md | Matrix-variant deep dive. |
| role.md | Role-iteration loop for agents. Recommended reading even for human contributors. |