From 9bc0d097b467941fe6d8812456e6dd691a7a86bf Mon Sep 17 00:00:00 2001 From: code-be-02 Date: Wed, 2 Sep 2026 13:20:54 -0500 Subject: [PATCH] docs: make Portainer deploy path optional --- packages/mosaic/framework/defaults/TOOLS.md | 2 +- .../mosaic/framework/guides/INFRASTRUCTURE.md | 3 ++- .../framework/skills/mosaic-deploy/SKILL.md | 27 ++++++++++++------- .../skills/mosaic-portainer/SKILL.md | 22 ++++++++------- 4 files changed, 32 insertions(+), 22 deletions(-) diff --git a/packages/mosaic/framework/defaults/TOOLS.md b/packages/mosaic/framework/defaults/TOOLS.md index 77e775ea..cd16d7f0 100644 --- a/packages/mosaic/framework/defaults/TOOLS.md +++ b/packages/mosaic/framework/defaults/TOOLS.md @@ -46,7 +46,7 @@ whitelisted — see the tool header. | tmux | `tools/tmux/agent-send.sh` | inter-agent messaging (see "Most-used" above) | | git | `tools/git/*.sh` | issues, PRs, milestones, CI queue guard (platform-auto-detected) | | woodpecker | `tools/woodpecker/*.sh` | CI pipelines (`-a mosaic`\|`usc`; match git remote host) | -| portainer | `tools/portainer/*.sh` | Docker Swarm stacks (status/redeploy/list) | +| portainer | `tools/portainer/*.sh` | Optional Docker Swarm tools when a Portainer credential is available | | coolify | `tools/coolify/*.sh` | **DEPRECATED** — superseded by Portainer; do not use for new deployments | | authentik | `tools/authentik/*.sh` | identity (users/groups/apps/flows) | | cloudflare | `tools/cloudflare/*.sh` | DNS (zones/records; `-a` instance) | diff --git a/packages/mosaic/framework/guides/INFRASTRUCTURE.md b/packages/mosaic/framework/guides/INFRASTRUCTURE.md index 48dc1b97..5356388b 100644 --- a/packages/mosaic/framework/guides/INFRASTRUCTURE.md +++ b/packages/mosaic/framework/guides/INFRASTRUCTURE.md @@ -136,7 +136,8 @@ The human is escalation-only for missing access, hard policy conflicts, or irrev ### Supported Targets -- **Portainer**: Deploy via `~/.config/mosaic/tools/portainer/stack-redeploy.sh`, then verify with `stack-status.sh`. +- **Docker Swarm**: If a stack README documents `docker stack deploy` on the manager, use that deploy path and its stated verification procedure. +- **Portainer (optional)**: Use only when the estate holds a Portainer credential. Do not propose Portainer otherwise. Deploy via `~/.config/mosaic/tools/portainer/stack-redeploy.sh`, then verify with `stack-status.sh`. - **Coolify**: Deploy via `~/.config/mosaic/tools/coolify/deploy.sh -u `, then verify with `service-status.sh`. - **Vercel**: Deploy via `vercel` CLI or connected Git integration, then verify preview/production URL health. - **Other SaaS providers**: Use provider CLI/API/runbook with the same validation and rollback gates. diff --git a/packages/mosaic/framework/skills/mosaic-deploy/SKILL.md b/packages/mosaic/framework/skills/mosaic-deploy/SKILL.md index 2182a033..e48c83ca 100644 --- a/packages/mosaic/framework/skills/mosaic-deploy/SKILL.md +++ b/packages/mosaic/framework/skills/mosaic-deploy/SKILL.md @@ -1,16 +1,16 @@ --- name: mosaic-deploy -description: 'Full end-to-end deploy flow for Mosaic Stack projects: push branch → open PR → wait for CI → merge → redeploy Portainer stack. Use when deploying a feature branch to production or staging, or when asked to ship a completed feature. Orchestrates mosaic-gitea, mosaic-woodpecker, and mosaic-portainer skills.' +description: 'Full end-to-end deployment flow: push branch → open PR → wait for CI → merge → deploy using the path documented by the stack. Use when deploying a feature branch to production or staging, or when asked to ship a completed feature.' --- # mosaic-deploy -End-to-end deployment flow for Mosaic Stack projects. +End-to-end deployment flow. ## Full Deploy Sequence ``` -push branch → open PR → CI passes → merge → portainer redeploy +push branch → open PR → CI passes → merge → documented deploy path ``` ### Step 1: Push branch and open PR @@ -49,25 +49,32 @@ review. Fix the cause; never route around it with a raw API call, a shared credential, or `force_merge`. Exceptional cases go to the operator or the coordinating seat, still merged through the wrapper. -### Step 4: Redeploy Portainer stack +### Step 4: Deploy Through the Documented Path + +Read the stack README before deploying: + +- If it documents `docker stack deploy` on the manager, use that deploy path and its verification procedure. +- Use Portainer only when the estate holds a Portainer credential. Do not propose Portainer otherwise. + +For an authorized Portainer deployment: ```bash source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer ~/.config/mosaic/tools/portainer/stack-redeploy.sh -n -p ``` -Check deployment: +Check a Portainer deployment: ```bash ~/.config/mosaic/tools/portainer/stack-status.sh -n ~/.config/mosaic/tools/portainer/stack-logs.sh -n -l 50 ``` -## Stack Name Map +## Optional Portainer Stack Map -Maintain your estate's project → stack-name mapping in a skills-local override of -this skill (local copies take precedence over the shipped canonical one). Example -shape: +For deployments that use Portainer, maintain a project → stack-name mapping in a +skills-local override of this skill (local copies take precedence over the shipped +canonical one). Example shape: | Project | Stack Name | | ------------ | ----------------- | @@ -77,6 +84,6 @@ shape: ## Notes - Workers open PRs but **never merge** — orchestrator or Merge Guard handles step 3+ -- Docker Swarm image pinning: if `-p` doesn't pull a new image, SSH to the Docker node (e.g. `node-01`) and run `docker pull ` manually, then redeploy +- Docker Swarm image pinning: `-p` does not change a digest-pinned image. Follow the stack README's documented deployment procedure. - Worktrees: all coding work in `~/src/-worktrees/`, never in main checkout - Always clean up worktree after push: `git worktree remove ~/src/-worktrees/` diff --git a/packages/mosaic/framework/skills/mosaic-portainer/SKILL.md b/packages/mosaic/framework/skills/mosaic-portainer/SKILL.md index cdb62b22..1683ee7f 100644 --- a/packages/mosaic/framework/skills/mosaic-portainer/SKILL.md +++ b/packages/mosaic/framework/skills/mosaic-portainer/SKILL.md @@ -1,15 +1,19 @@ --- name: mosaic-portainer -description: Manage Portainer stacks on the Mosaic infrastructure. Use when asked to list, start, stop, redeploy, or check logs of Docker Swarm stacks via Portainer. Wraps scripts in ~/.config/mosaic/tools/portainer/. Requires load_credentials portainer first. +description: Manage Docker Swarm stacks through Portainer when a Portainer credential is available. Use when asked to list, start, stop, redeploy, or check logs through Portainer. --- # mosaic-portainer -Manage Portainer stacks via pre-built Mosaic scripts. +Manage Portainer stacks through supplied scripts. + +## Decision Gate + +Portainer is optional. Use this skill only when the estate holds a Portainer credential. If a stack README documents `docker stack deploy` on the manager, that is the deploy path. Do not propose Portainer otherwise. ## Setup -Always load credentials before running scripts: +After confirming a Portainer credential is available, load it before running scripts: ```bash source ~/.config/mosaic/tools/_lib/credentials.sh @@ -33,11 +37,11 @@ All scripts live in `~/.config/mosaic/tools/portainer/`. ## Common Workflows -**Redeploy a stack with fresh images:** +**Redeploy a stack through Portainer:** ```bash source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer -~/.config/mosaic/tools/portainer/stack-redeploy.sh -n mosaic-stack -p +~/.config/mosaic/tools/portainer/stack-redeploy.sh -n -p ``` **Check all stack statuses:** @@ -51,12 +55,10 @@ source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer ```bash source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer -~/.config/mosaic/tools/portainer/stack-logs.sh -n mosaic-stack -l 100 +~/.config/mosaic/tools/portainer/stack-logs.sh -n -l 100 ``` ## Notes -- Portainer URL: `https://portainer.example.internal:9443` -- Primary Docker host: `node-01`, managed via Portainer agent -- Docker Swarm image updates: `stack-redeploy.sh -p` does NOT guarantee new image pull if digest is pinned; SSH to node and `docker pull` first if needed -- Credentials: `load_credentials portainer` (framework credentials store) +- `stack-redeploy.sh -p` does not override a digest-pinned image. Follow the stack README's documented deployment procedure for pinned images. +- Credentials are loaded through `load_credentials portainer`. -- 2.54.0