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>
4.2 KiB
Development Environment Setup 🛠️
Use the repository's real setup flow. The main source of truth is the Makefile.
Important:
- Some local development commands change host settings such as DNS, AppArmor, and IPv6.
- Some commands use
sudo. - Read the setup guides first if you are new to this environment.
- The local development workflow is mainly tested on Linux.
Platform-Specific Instructions 🖥️
Shared Repository Workflow 🔄
These steps are the shared repository workflow and apply regardless of whether you work on Linux, macOS, or Windows with WSL2.
Bootstrap 🚀
Run these commands from the repository root:
make bootstrap
make environment-bootstrap
make up
make trust-ca
Bootstrap Commands 📋
| Phase | Command | What it does |
|---|---|---|
| Initial setup | make bootstrap |
Installs project dependencies and runs the first repository setup. |
| Host preparation | make environment-bootstrap |
Prepares the local development machine for the project workflow. |
| Start stack | make up |
Starts the local development stack. |
| Browser trust | make trust-ca |
Trusts the generated local CA so *.infinito.example works correctly in your browser. |
Optional Development Marker 🏷️
If you want to mark this checkout as a development environment, run:
make mark-development
This step is optional. It creates an empty env.development file in the repository root.
Several tools (e.g. cli/administration/deploy/development/compose.py, scripts/meta/resolve/apps.sh) pass env.ci as the base env-file to Docker Compose and then, when env.development exists, append it as a second --env-file. Because Docker Compose applies env-files in order, any variable defined in env.development overrides the corresponding value from env.ci. This lets you customize local settings (ports, image tags, flags) without modifying the shared env.ci file.
The pre-commit hooks are installed automatically by make environment-bootstrap and do not depend on this marker.
Teardown 🧹
When you are done, use these commands to stop the stack and clean up the local environment:
make down
make environment-teardown
Teardown Commands 📋
| Phase | Command | What it does |
|---|---|---|
| Stop stack | make down |
Stops the local development stack. |
| Host cleanup | make environment-teardown |
Reverts local development environment changes where supported. |
Full Development Flow 🔁
The repository already contains a modular environment test suite at scripts/tests/environment/. The commands from that suite are explained here as the intended end-to-end flow.
Flow Summary 📋
| Step | Command | Purpose in this flow |
|---|---|---|
| 1 | make install |
Installs the dependencies needed before running the local development flow. |
| 2 | make environment-bootstrap |
Prepares the host machine for local development. |
| 3 | make up |
Starts the development stack. |
| 4 | make test |
Runs the main combined validation flow. |
| 5 | make deploy-fresh-purged-apps APPS=web-app-matomo |
Runs the baseline validation path for one concrete app. For the retry-loop policy, see Role Loop. |
| 6 | make trust-ca |
Makes the generated local certificates trusted by the host browser. |
| 7 | make down |
Stops the running development stack. |
| 8 | make environment-teardown |
Cleans up host-side development environment changes. |
Use this as a practical reference when you want to understand how local development is expected to work.
Minimal Hardware Resources 💾
If you work on a machine with limited CPU, RAM, or disk space, use the guide at hardware.md. The public article with the same topic is here.
For local deploy shortcuts and end-to-end checks, see testing.md.