mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 10:59:59 +00:00
kevinveenbirkenbachandClaude Opus 4.7
8e293bd921
Root cause of step-08 deploy failures across all 4 test-development
distros in run 26572559126: `make compose-deploy mode=reinstall
apps=web-app-dashboard INFINITO_SERVICES_DISABLED=matomo` (step 07)
made make export the cmdline var into the recipe's shell env, which
reached `runner.py` → `make setup` → `make dotenv`. The dotenv
generator's `setdefault` then baked the runtime-only value into the
on-disk `.env`. Step 08 sourced that .env, filtered `web-app-matomo`
out of its primary apps, and exited with "All primary apps disabled".
Fix:
- Drop the 7 routing knobs (apps, mode, purge, bundles, disable,
full_cycle, variant) from `passthrough.STATIC_KEYS` and from
`default.env`. They are per-invocation; .env is the persistent SPOT
and must not capture them.
- Switch every consumer from `os.environ["KEY"]` strict access to
`os.environ.get("KEY", "")` so the missing-key path stops at "no
filter" instead of a KeyError.
- Rename the env-var surface to match the make-alias surface 1:1
(lowercase): INFINITO_APPS → apps, INFINITO_SERVICES_DISABLED →
disable, INFINITO_BUNDLES → bundles, INFINITO_FULL_CYCLE →
full_cycle, INFINITO_VARIANT → variant, INFINITO_DEPLOY_MODE → mode,
INFINITO_PURGE_ENTITIES → purge. The make alias was the user-facing
name in every doc; routing-knob env vars now use the same name so
the cmdline form, the recipe env-prefix, and the consumer reads
all line up.
- Collapse the Makefile `compose-deploy` recipe to just the two
knobs whose alias differs from the env name (`type` →
INFINITO_DEPLOY_TYPE, `debug` → INFINITO_DEBUG). GNU Make
auto-exports cmdline variables into the recipe's shell env, so the
identical-name `$(if $(apps),apps="$(apps)")` lines were pure
noise.
- Drop `disable: ${disable}` from compose.yml. The dev CLI builds
`extra_env` per `docker exec` call and forwards `disable` via
`-e`, so the container env never needs the value frozen at
compose-up time.
- Update the 3 actual leak call sites
(07/08/09_deploy_*.sh) to the make-alias form
(`disable=matomo`, `full_cycle=true`, `variant=1`).
- Add `SIM112` to ruff's ignore set: the lowercase env names are
the deliberate make/env parity, not a typo.
Repro before fix: `INFINITO_SERVICES_DISABLED=matomo make dotenv`
wrote `INFINITO_SERVICES_DISABLED=matomo` to `.env`. After fix:
`disable=matomo make dotenv` leaves `.env` untouched.
Tests: `make test` and `make autoformat` green (2711 tests, 8 lint
sub-targets).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
186 lines
3.9 KiB
Markdown
186 lines
3.9 KiB
Markdown
# Infinito.Nexus Inventories
|
|
|
|
This directory contains all deployable bundles for Infinito.Nexus.
|
|
|
|
An inventory in Infinito.Nexus is not just a host definition.
|
|
It represents a complete, declarative infrastructure bundle.
|
|
|
|
Each inventory defines:
|
|
|
|
- Which roles are activated
|
|
- Which host(s) are targeted
|
|
- Metadata required by the Infinito Deployer (title, description, logo, etc.)
|
|
|
|
Deploy target is derived from the folder structure.
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
Inventories are grouped by deploy target:
|
|
|
|
inventories/
|
|
server/
|
|
workstation/
|
|
|
|
Each bundle must live inside one of those directories:
|
|
|
|
inventories/server/<bundle-name>/
|
|
inventories/workstation/<bundle-name>/
|
|
|
|
The folder name represents the bundle identifier.
|
|
|
|
---
|
|
|
|
## Required Files
|
|
|
|
Each bundle directory must contain:
|
|
|
|
- inventory.yml
|
|
|
|
Optional but recommended:
|
|
|
|
- README.md (bundle-specific documentation)
|
|
|
|
No additional bundle manifest files are required.
|
|
|
|
---
|
|
|
|
## Inventory Structure (Bundle-Conform)
|
|
|
|
Each inventory must follow this structure:
|
|
|
|
- all.vars.infinito.bundle metadata
|
|
- one default host
|
|
- role groups under children
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
all:
|
|
vars:
|
|
infinito:
|
|
bundle:
|
|
title: "School Basic"
|
|
description: >
|
|
Basic bundle for a small school setup.
|
|
logo:
|
|
class: "fa-solid fa-graduation-cap"
|
|
tags:
|
|
- education
|
|
- collaboration
|
|
categories:
|
|
- Community
|
|
- Collaboration
|
|
|
|
hosts:
|
|
server:
|
|
|
|
children:
|
|
web-app-nextcloud:
|
|
hosts:
|
|
server:
|
|
|
|
svc-prx-openresty:
|
|
hosts:
|
|
server:
|
|
```
|
|
|
|
---
|
|
|
|
## Rules
|
|
|
|
### 1. Deploy Target
|
|
|
|
Deploy target is derived from the parent folder:
|
|
|
|
- inventories/server → server bundle
|
|
- inventories/workstation → workstation bundle
|
|
|
|
Do not define deploy_target inside the inventory file.
|
|
|
|
---
|
|
|
|
### 2. Host Definition
|
|
|
|
Each bundle must define exactly one default host:
|
|
|
|
server
|
|
|
|
No additional configuration is required.
|
|
|
|
Connection settings may be added later if needed.
|
|
|
|
---
|
|
|
|
### 3. Role Activation
|
|
|
|
Role names must be defined as group names under children.
|
|
|
|
Group name must match the role directory name exactly.
|
|
|
|
Each role group must contain the default host.
|
|
|
|
---
|
|
|
|
### 4. Bundle Metadata
|
|
|
|
Metadata must be defined under:
|
|
|
|
all.vars.infinito.bundle
|
|
|
|
Required fields:
|
|
|
|
- title
|
|
- description
|
|
- logo.class
|
|
- tags
|
|
- categories
|
|
|
|
The logo must use a valid Font Awesome class string, e.g.:
|
|
|
|
fa-solid fa-graduation-cap
|
|
|
|
---
|
|
|
|
### 5. No Role-Specific Configuration
|
|
|
|
Bundles act as skeleton definitions.
|
|
|
|
They must not contain application-specific configuration values.
|
|
|
|
Role configuration belongs inside roles or runtime overlays.
|
|
|
|
---
|
|
|
|
## Philosophy
|
|
|
|
An inventory in Infinito.Nexus is:
|
|
|
|
- a bundle definition
|
|
- a role activation map
|
|
- a deployable unit
|
|
|
|
No additional bundle file format is required.
|
|
|
|
The inventory itself is the bundle.
|
|
|
|
---
|
|
|
|
## Deploying a Bundle
|
|
|
|
The single `make compose-deploy` target resolves one or more bundles into the role groups declared under `all.children` and feeds them into the standard local deploy flow when `bundles=<csv>` is set. The resolver is [`utils.inventory.bundle_apps`](../../utils/inventory/bundle_apps.py); it deduplicates across bundles and preserves declaration order.
|
|
|
|
| Command | Path | Behavior |
|
|
|---|---|---|
|
|
| `make compose-deploy bundles="<a>[,<b>]"` | reinstall | Brings the stack down/up, purges entities, then deploys every role group from the listed bundles. Set `full_cycle=true` to also run the async update pass. |
|
|
| `make compose-deploy mode=update bundles="<a>[,<b>]"` | update | No down/up, no entity purge. Requires a prior initialize/reinstall run that materialized the inventory. |
|
|
|
|
Example:
|
|
|
|
```bash
|
|
make compose-deploy bundles="education-suite,startup-essentials" full_cycle=true
|
|
```
|
|
|
|
See [docs/contributing/tools/make.md](../../docs/contributing/tools/make.md) and [docs/contributing/actions/testing.md](../../docs/contributing/actions/testing.md) for the full deploy-target reference.
|