From aa32454aefb7ad160f50aee51c1c5f5d8491541c Mon Sep 17 00:00:00 2001 From: herbygitea Date: Sat, 25 Apr 2026 04:41:40 +0000 Subject: [PATCH] Create ansible-container-deploy.md via n8n --- Tech/Projects/ansible-container-deploy.md | 211 ++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 Tech/Projects/ansible-container-deploy.md diff --git a/Tech/Projects/ansible-container-deploy.md b/Tech/Projects/ansible-container-deploy.md new file mode 100644 index 0000000..d1e1496 --- /dev/null +++ b/Tech/Projects/ansible-container-deploy.md @@ -0,0 +1,211 @@ +--- +project: ansible-container-deploy +type: project-plan +status: active +path: Tech/Projects +tags: + - pbs + - ansible + - docker + - deployment + - automation +created: 2026-04-25 +updated: 2026-04-25 +--- +# Ansible Container Deploy + +Tag-based per-container Ansible deployment, CLI wizard enhancements, and +GitHub clone integration for the PBS Docker stack. + +## Background + +The wordpress-install repo (pbs-production/) has been refactored from a +loop-based all-or-nothing Docker deployment to a tag-based `import_tasks` +pattern. Each container has its own task wrapper under `tasks/containers/` +that calls `common/deploy.yml` with container-specific variables. The +docker-container repo (pbs-workshop/) houses a CLI wizard that scaffolds +new container files (compose template, task wrapper, env template) but +currently only generates simple-tier containers. + +The tag-based refactor is coded but untested. The wizard needs enhancements +to support medium and complex tier containers. A separate GitHub deploy +refactor (github-deploy-refactor, status: complete) established the +pbsdeploybot machine user pattern for repo cloning — that logic needs to be +absorbed into the dockers role. + +## Repos + +- **wordpress-install (pbs-production/)** — production deployment repo, +tag-based structure in place +- **docker-container (pbs-workshop/)** — tooling repo, CLI wizard and +scaffolding +- **claude-code-scaffolding-skill** — separate project, consumes the +patterns defined here (see Phase 5) + +## Architecture + +### common/deploy.yml Variable Contract + +Required: +- `container_name` (str) — directory name under `files/` and deploy path at +`{{ dockers_path }}//` + +Optional: +- `container_has_env` (bool, default false) — templates +`files//.env.j2` → `.env` +- `container_extra_dirs` (list of str) — additional directories to create +- `container_extra_files` (list of {src, dest, mode}) — static files to copy +- `container_extra_templates` (list of {src, dest, mode}) — Jinja templates +to render + +Global vars (from vars/main.yml and inventory): +- `dockers_path` — base directory (`/opt/docker`) +- `user` — system user for file ownership +- `dockers_lan_name` — Docker network name +- `dockers_domain_name` — primary domain + +### Container Complexity Tiers + +**Simple** (redis, portainer, uptime-kuma): `container_name` only +**Medium** (pbs-api): adds `container_extra_dirs`, `container_extra_files`, +`container_extra_templates` +**Complex** (wordpress): medium plus post-deploy tasks + +### common/github.yml (planned) + +Will sit alongside `common/deploy.yml`. Containers that build from a cloned +repo import `github.yml` first (clone/pull via pbsdeploybot), then +`deploy.yml` (compose up). Uses the same SSH host alias pattern established +in github-deploy-refactor. + +## Phases + +### Phase 1: Validate Tag-Based Deployment + +Test the existing tag-based refactor on staging. + +- [ ] Run `--tags traefik` against staging, verify only traefik deploys +- [ ] Run `--tags wordpress` against staging, verify only wordpress deploys +- [ ] Run `--tags "traefik,wordpress"` to verify multi-tag targeting +- [ ] Run `--skip-tags n8n` to verify exclusion works +- [ ] Run full playbook (no tags) to verify all-container deployment still +works +- [ ] Document any issues or adjustments needed + +### Phase 2: Absorb GitHub Clone Logic + +Migrate the github role's clone logic into the dockers role as +`common/github.yml`. + +- [ ] Create `tasks/common/github.yml` in the dockers role +- [ ] Accept per-invocation vars: `repo_url`, `repo_dest`, `repo_version` +- [ ] Use `become_user: "{{ ansible_user }}"` for SSH config access +- [ ] Default `repo_version` to `main` +- [ ] Update container task wrappers that need repo clones (e.g., pbs-hub) +to import `github.yml` before `deploy.yml` +- [ ] Test on staging with an existing repo-based container +- [ ] Decide whether standalone github role is kept for non-container use +cases or retired entirely + +### Phase 3: Wizard Enhancements + +Extend the CLI wizard to support medium-tier containers and repo-based +builds. + +#### 3a: Dockerfile Support +- [ ] Add wizard prompt: "Does this container need a custom Dockerfile?" +- [ ] If yes, generate a Dockerfile template in the container's files +directory +- [ ] Add Dockerfile to `container_extra_files` in the generated task +wrapper + +#### 3b: Git Repo Support +- [ ] Add wizard prompt: "Is this container built from a git repo?" +- [ ] If yes, prompt for `repo_url` and `repo_version` +- [ ] Generate task wrapper that imports `common/github.yml` before +`common/deploy.yml` + +#### 3c: Extra Files/Dirs/Templates +- [ ] Add wizard prompts for additional directories, static files, and +templates +- [ ] Generate `container_extra_dirs`, `container_extra_files`, +`container_extra_templates` entries in the task wrapper + +#### 3d: Vault Secret References +- [ ] When the wizard detects vars that need secrets (db passwords, API +keys, etc.), generate placeholder references in compose templates using `{{ +vault_ }}` syntax +- [ ] Output a post-scaffold checklist reminding the user which vault vars +need to be manually added to encrypted group vars + +#### 3e: Repo-Context Awareness +- [ ] When the wizard is run inside the production repo, it should read +existing `vars/main.yml`, network configs, and Traefik patterns to inform +prompts and output +- [ ] Wizard should auto-detect available networks, domain name, and base +path from existing config +- [ ] Wizard should append generated vars entries to `vars/main.yml` (or +output them for manual paste) +- [ ] Implementation details deferred to Claude Code — requirement is +stated, approach is flexible + +### Phase 4: Production Rollout + +- [ ] Deploy tag-based structure to production (after staging validation) +- [ ] Test selective deployment on production with a low-risk container +- [ ] Update any runbooks or deployment docs + +### Phase 5: Scaffolding Skill Integration + +Separate project (claude-code-scaffolding-skill), documented here for +dependency tracking. + +Three new scaffold types to add: +- **`ansible-docker-container`** — scaffolds the project structure for a +tag-based Docker container deployment (folder tree, template files, vars +skeleton). The wizard then fills in the details. +- **`ansible-role`** — reusable Galaxy-style role (defaults, handlers, +meta, tasks, templates, Molecule testing) +- **`ansible`** — full playbook project (ansible.cfg, inventory, +group_vars, host_vars, playbooks, roles, requirements.yml, vault setup) + +The scaffold creates project structure; the wizard populates +container-specific content. Scaffold = one-time project start, wizard = +repeated container additions. + +This project provides the reference patterns. The scaffolding skill project +owns implementation. + +## Decisions Made + +- **Wizard vs scaffold split:** Scaffold generates project structure, +wizard fills in container details. Different tools, same conventions. +- **Vault secrets stay manual:** Wizard generates `{{ vault_* }}` +placeholder references and a reminder checklist. Actual vault entries are +hand-added. +- **Context-aware wizard implementation deferred to Claude Code:** +Requirement is that the wizard reads existing repo config when run +in-place. How it does that is an implementation detail. +- **Scaffolding skill: start inside existing skill, separate if it doesn't +fit.** Build assuming merge into claude-code-scaffolding-skill. If +infrastructure types feel forced next to dev tooling types, split into +standalone skill. +- **common/github.yml pattern:** Clone logic absorbed into dockers role, +not kept as a standalone role for container use cases. Matches the +common/deploy.yml pattern. + +## Dependencies + +- github-deploy-refactor (complete) — provides pbsdeploybot auth pattern +- claude-code-scaffolding-skill (separate project) — consumes patterns from +Phase 3+ + +## Open Questions + +- Should the standalone github role be kept for non-container clone use +cases, or is pbsdeploybot + common/github.yml sufficient for everything? +- Final call on scaffolding skill merge vs standalone — deferred until +implementation reveals fit + + +...sent from Jenny & Travis \ No newline at end of file