186 lines
5.1 KiB
Markdown
186 lines
5.1 KiB
Markdown
# 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
|