# Portainer Skill

Interact with Portainer stacks via API key authentication. Manage stacks, resolve identifiers, update deployments, and clean up old images.

## Overview

This skill provides a comprehensive set of commands for managing Portainer Docker stacks through the API. All stack commands accept stack names and automatically resolve IDs internally.

## Prerequisites

### Auth Configuration

Create a config file at one of these locations:
```
workspace/.clawdbot/credentials/portainer/config.json
~/.clawdbot/credentials/portainer/config.json
```

With the following content:
```json
{
  "base_url": "https://your-portainer-instance.com",
  "api_key": "YOUR_PORTAINER_API_KEY"
}
```

To generate an API key:
1. Log into Portainer
2. Go to User Settings → Access tokens
3. Create a new token with appropriate permissions

## Commands

### Stack Identification

#### Get Stack ID
```bash
bash scripts/get-stack-id.sh "<stack-name>"
```
Resolves a stack name to its numeric ID. Prints only the ID on success.

#### Get Endpoint ID
```bash
bash scripts/get-endpoint-id.sh "<endpoint-name>"
```
Resolves an endpoint (environment) name to its ID.

### Stack Inventory

#### List All Stacks
```bash
bash scripts/list-stacks.sh
```
Lists all stacks with their ID, Name, and Status.

#### Get Stack Status
```bash
bash scripts/get-stack-status.sh "<stack-name>"
```
Returns JSON with stack details: Id, Name, Status, Type, EndpointId, CreationDate, UpdatedDate.

### Stack Lifecycle

#### Stop Stack
```bash
bash scripts/stop-stack.sh "<stack-name>"
```

#### Start Stack
```bash
bash scripts/start-stack.sh "<stack-name>"
```

#### Restart Stack
```bash
bash scripts/restart-stack.sh "<stack-name>"
```

### Stack Configuration

#### Get Environment Variables
```bash
bash scripts/get-stack-env.sh "<stack-name>"
```
Returns JSON array of `{name, value}` objects.

#### Get Compose File
```bash
bash scripts/get-stack-compose.sh "<stack-name>"
```
Returns the raw docker-compose.yml content.

### Stack Updates

#### Update Stack
```bash
bash scripts/update-stack.sh "<stack-name>" "<compose-file>" [options]
```

Options:
- `--pull` — Force pull images and redeploy (like `docker compose down/pull/up`)
- `--env-file <file>` — Path to a file with env vars (format: NAME=value per line)

Notes:
- Without `--env-file`, existing environment variables are preserved
- The `--pull` flag may return HTTP 504 for large images, but the operation completes in the background

#### Prune Stack Images
```bash
bash scripts/prune-stack-images.sh "<stack-name>"
```
Removes dangling images on the endpoint. Run this after `update-stack --pull` completes.

## Typical Workflow

### Updating a Stack with a New Image Version

```bash
# 1. Get the current compose file
bash scripts/get-stack-compose.sh "my-stack" > /tmp/my-stack-compose.yml

# 2. Update the stack (pull new images)
bash scripts/update-stack.sh "my-stack" "/tmp/my-stack-compose.yml" --pull

# 3. Wait for update to complete (even if you see a 504 timeout)

# 4. Clean up old images
bash scripts/prune-stack-images.sh "my-stack"
```

### Modifying a Stack's Compose File

```bash
# 1. Get the current compose file
bash scripts/get-stack-compose.sh "my-stack" > /tmp/my-stack-compose.yml

# 2. Edit the compose file
nano /tmp/my-stack-compose.yml

# 3. Update the stack with the modified file
bash scripts/update-stack.sh "my-stack" "/tmp/my-stack-compose.yml"

# 4. Optionally prune old images if you changed image tags
bash scripts/prune-stack-images.sh "my-stack"
```

## Error Handling

All scripts:
- Exit with code 0 on success
- Exit with non-zero code on failure
- Print error messages to stderr
- Print results to stdout

Common errors:
- **Missing config file**: Create the auth configuration file in the workspace `.clawdbot/credentials/portainer/` path or in `~/.clawdbot/credentials/portainer/`
- **Invalid API key**: Generate a new API key in Portainer
- **Stack not found**: Check the stack name with `list-stacks.sh`
- **504 Gateway Timeout**: The operation is still running in the background; wait and then run the prune command

## API Reference

This skill uses the following Portainer API endpoints:

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/stacks` | GET | List all stacks |
| `/api/stacks/{id}` | GET | Get stack details |
| `/api/stacks/{id}` | PUT | Update stack |
| `/api/stacks/{id}/file` | GET | Get compose file |
| `/api/stacks/{id}/start` | POST | Start stack |
| `/api/stacks/{id}/stop` | POST | Stop stack |
| `/api/stacks/{id}/restart` | POST | Restart stack |
| `/api/endpoints` | GET | List endpoints |
| `/api/endpoints/{id}/docker/containers/json` | GET | List containers |
| `/api/endpoints/{id}/docker/images/json` | GET | List images |
| `/api/endpoints/{id}/docker/images/{id}` | DELETE | Remove image |

## Notes

- All `*-stack.sh` commands resolve the stack ID internally from the name
- Endpoint ID is fetched automatically from stack info for lifecycle and update operations
- The `--pull` flag triggers Portainer to pull new images and recreate containers
- Large image pulls may cause HTTP 504 timeouts, but operations complete server-side
- Use `prune-stack-images.sh` after updates to clean up old dangling images