---
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.
---

# mosaic-portainer

Manage Portainer stacks via pre-built Mosaic scripts.

## Setup

Always load credentials before running scripts:

```bash
source ~/.config/mosaic/tools/_lib/credentials.sh
load_credentials portainer
# Exports: PORTAINER_URL, PORTAINER_API_KEY
```

## Scripts

All scripts live in `~/.config/mosaic/tools/portainer/`.

| Script              | Purpose                      | Key flags                      |
| ------------------- | ---------------------------- | ------------------------------ |
| `stack-list.sh`     | List all stacks              | —                              |
| `stack-status.sh`   | Status of a stack            | `-n <name>`                    |
| `stack-redeploy.sh` | Redeploy (file or git-based) | `-n <name> [-p]` (pull images) |
| `stack-start.sh`    | Start a stopped stack        | `-n <name>`                    |
| `stack-stop.sh`     | Stop a running stack         | `-n <name>`                    |
| `stack-logs.sh`     | Tail stack logs              | `-n <name> [-l lines]`         |
| `endpoint-list.sh`  | List Portainer endpoints     | —                              |

## Common Workflows

**Redeploy a stack with fresh images:**

```bash
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
~/.config/mosaic/tools/portainer/stack-redeploy.sh -n mosaic-stack -p
```

**Check all stack statuses:**

```bash
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
~/.config/mosaic/tools/portainer/stack-list.sh
```

**Tail logs for a service:**

```bash
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
~/.config/mosaic/tools/portainer/stack-logs.sh -n mosaic-stack -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)
