mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-09 20:26:33 +00:00
kevinveenbirkenbachandClaude Opus 5.5
d92375922d
An inventory group web-app-cst-<name> with applications.<id>.custom: true and
a pinned source {url, version, path} is pulled into roles/ before the play,
read raw (Jinja, Ansible tags and credential URLs refused), placed through a
staging directory under an exclusive lock, and owned by a marker that names
its own directory, so a pull or roles-clean never replaces or removes a
directory it did not place and a failed pull leaves roles/ as it was.
Directory inventories, host lists and non-UTF-8 files behave as Ansible
reads them; generated test deploys pass --skip-pull. make roles-pull,
roles-clean and roles list, INFINITO_EXTRA_MOUNTS for local sources, the
web-app-cst category, the reserved prefix lint and a central
repository_files() that also yields the gitignored custom roles let every
lint scan them like in-tree roles. Supersedes the uncommitted 045 External
Roles draft and reuses its fetch, sync and mount design.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
# Deploy Guide 🚀
|
|
|
|
Use this guide to create inventories, run a full deploy, and redeploy an existing environment with `infinito` commands only. The audience is the operator running deploys against a managed (production or staging) host. Contributors iterating on a local development stack should follow [Local Deploy](../contributing/actions/deploy.md) instead.
|
|
|
|
## Full Deploy 📦
|
|
|
|
Create or refresh the inventory first, then deploy against the generated inventory file.
|
|
|
|
### Create or Refresh the Inventory 📝
|
|
|
|
```bash
|
|
infinito administration inventory provision /etc/infinito.nexus/inventories/production \
|
|
--inventory-file /etc/infinito.nexus/inventories/production/devices.yml \
|
|
--host localhost \
|
|
--vars-file inventories/<env>/default.yml \
|
|
--include 'web-app-nextcloud,web-app-keycloak'
|
|
```
|
|
|
|
### Run the Deploy 🛠️
|
|
|
|
```bash
|
|
infinito administration deploy dedicated /etc/infinito.nexus/inventories/production/devices.yml \
|
|
--password-file /etc/infinito.nexus/inventories/production/.password \
|
|
--log /etc/infinito.nexus/logs \
|
|
--diff \
|
|
-vv
|
|
```
|
|
|
|
## Redeploy 🔁
|
|
|
|
When you need to redeploy after changes, repeat the same two `infinito` commands:
|
|
|
|
1. Re-run `infinito administration inventory provision ...` to refresh the inventory file and included app list.
|
|
2. Re-run `infinito administration deploy dedicated ...` against the same inventory file.
|
|
|
|
## Inventory Notes 📒
|
|
|
|
- Keep one inventory directory per environment.
|
|
- Store the password file next to the inventory file.
|
|
- Update `--include` whenever the target app set changes.
|
|
- Use a `--vars-file` that matches the target environment. Production deploys MUST NOT point at the development sample file.
|
|
|
|
## Custom Roles 🧩
|
|
|
|
An inventory MAY deploy application roles that live in their own, possibly private, repositories.
|
|
|
|
### Declare 📝
|
|
|
|
A custom role is an inventory group named `web-app-cst-<name>`; a host joins it like any `web-app-*` group. Its application values mark it and name its source:
|
|
|
|
```yaml
|
|
applications:
|
|
web-app-cst-security-check:
|
|
custom: true
|
|
source:
|
|
url: git@github.com:infinitonexus/php-landingpage.git
|
|
version: v1.4.0
|
|
path: ansible/roles/web-app-cst-security-check
|
|
```
|
|
|
|
- `url` is a Git URL over HTTPS or SSH. During development an absolute local directory MAY stand in for it; without `version` its working tree is copied, uncommitted changes included.
|
|
- `version` is a tag or a full commit SHA. A branch is refused.
|
|
- `path` is the role directory inside the repository. Its name and the `application_id` in its `vars/main.yml` MUST equal the group.
|
|
- Values MUST be literal strings; Jinja is not rendered.
|
|
|
|
### Pull 🔄
|
|
|
|
`infinito administration deploy dedicated` and `infinito administration deploy swarm` pull the declared roles into `roles/` of the controller's checkout before they read any role. Pass `--skip-pull` to deploy the roles already placed. The same steps run on their own:
|
|
|
|
```bash
|
|
make roles-pull inventory=/etc/infinito.nexus/inventories/production/devices.yml
|
|
infinito administration roles list
|
|
make roles-clean
|
|
```
|
|
|
|
A pull stages every role outside `roles/` and changes `roles/` only when all of them passed, so a refused pull leaves it as it was. It replaces or removes only the directories it placed itself, whose marker names them, and refuses a declared name that meets a symbolic link, a hand-placed directory or a copy of a placed role. `make roles-clean` removes every `roles/web-app-cst-*` directory the pull placed and reports every other one it leaves in place. Git ignores `roles/web-app-cst-*`, so a pulled role never enters a core commit.
|
|
|
|
For the local compose stack, `INFINITO_EXTRA_MOUNTS=<dir>[,<dir>]` mounts each directory read-only at the same path into the `infinito` container, so a local `url` resolves inside it.
|
|
|
|
### Private Repositories 🔐
|
|
|
|
Git fetches with the SSH agent or the SSH configuration of the controller, so a deploy key goes into the agent or into `~/.ssh/config`:
|
|
|
|
```text
|
|
Host github-landingpage
|
|
HostName github.com
|
|
User git
|
|
IdentityFile ~/.ssh/landingpage-deploy-key
|
|
IdentitiesOnly yes
|
|
```
|
|
|
|
The declaration then uses `url: github-landingpage:infinitonexus/php-landingpage.git`. A `url` that embeds a password or token is refused without being echoed, and a fetch that would ask for credentials fails instead of prompting.
|
|
|
|
For CLI installation prerequisites, see the [Installation Guide](installation.md).
|
|
For the local development deploy flow (make targets, matrix variants, single-variant pinning), see [Local Deploy](../contributing/actions/deploy.md).
|