Portainer Deployment Management

Manage Docker stack deployments via Portainer API.

Configuration

Before using, ensure these are available:

• PORTAINER_URL: Portainer instance URL (e.g., https://portainer.example.com)
• PORTAINER_TOKEN: API token from Portainer (User Settings > Access Tokens)

Store sensitive config in environment or prompt user when needed.

Available Operations

1. List All Stacks

curl -s -X GET "$PORTAINER_URL/api/stacks" \
  -H "X-API-Key: $PORTAINER_TOKEN" | jq '.[] | {Id, Name, Status, CreationDate}'

Status codes: 1 = active, 2 = inactive

2. Check Stack Status

# Get specific stack by name
STACK_NAME="my-stack"
curl -s -X GET "$PORTAINER_URL/api/stacks" \
  -H "X-API-Key: $PORTAINER_TOKEN" | jq ".[] | select(.Name==\"$STACK_NAME\")"

3. Get Stack Containers/Services

STACK_ID=24
ENDPOINT_ID=1
curl -s -X GET "$PORTAINER_URL/api/endpoints/$ENDPOINT_ID/docker/containers/json?all=true" \
  -H "X-API-Key: $PORTAINER_TOKEN" | jq '.[] | select(.Labels["com.docker.compose.project"]=="STACK_NAME") | {Id: .Id[:12], Name: .Names[0], State, Status}'

4. Create Stack from Git Repository

Required parameters:

• name: Stack name (lowercase, hyphens allowed)
• repositoryURL: Git repo URL
• repositoryReferenceName: Branch (e.g., refs/heads/main)
• composeFile: Path to compose file in repo
• env: Array of environment variables

ENDPOINT_ID=$(curl -s "$PORTAINER_URL/api/endpoints" -H "X-API-Key: $PORTAINER_TOKEN" | jq '.[0].Id')

curl -X POST "$PORTAINER_URL/api/stacks/create/standalone/repository?endpointId=$ENDPOINT_ID" \
  -H "X-API-Key: $PORTAINER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-stack",
    "repositoryURL": "https://github.com/user/repo.git",
    "repositoryReferenceName": "refs/heads/main",
    "composeFile": "docker-compose.yml",
    "repositoryAuthentication": true,
    "repositoryUsername": "USERNAME",
    "repositoryPassword": "GITHUB_TOKEN",
    "env": [
      {"name": "VAR_NAME", "value": "value"}
    ],
    "autoUpdate": {
      "interval": "5m"
    }
  }'

For private repos, set repositoryAuthentication: true and provide credentials. Get GitHub token via: gh auth token

5. Redeploy/Update Stack

STACK_ID=24
ENDPOINT_ID=1
curl -X PUT "$PORTAINER_URL/api/stacks/$STACK_ID/git/redeploy?endpointId=$ENDPOINT_ID" \
  -H "X-API-Key: $PORTAINER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pullImage": true, "prune": false}'

6. Delete Stack

STACK_ID=24
ENDPOINT_ID=1
curl -X DELETE "$PORTAINER_URL/api/stacks/$STACK_ID?endpointId=$ENDPOINT_ID" \
  -H "X-API-Key: $PORTAINER_TOKEN"

7. View Container Logs

CONTAINER_ID="abc123"
ENDPOINT_ID=1
curl -s "$PORTAINER_URL/api/endpoints/$ENDPOINT_ID/docker/containers/$CONTAINER_ID/logs?stdout=true&stderr=true&tail=100" \
  -H "X-API-Key: $PORTAINER_TOKEN"

Workflow Instructions

When user asks to deploy to Portainer:

1. Gather requirements:

   • Portainer URL and API token
   • Git repository URL
   • Compose file path
   • Environment variables needed
   • Target branch

2. Check if repo is private:

   bashCopy

   curl -s -o /dev/null -w "%{http_code}" https://github.com/USER/REPO
   

   If 404, need GitHub credentials.

3. Get endpoint ID:

   bashCopy

   curl -s "$PORTAINER_URL/api/endpoints" -H "X-API-Key: $TOKEN" | jq '.[0].Id'
   

4. Check for existing stack:

   bashCopy

   curl -s "$PORTAINER_URL/api/stacks" -H "X-API-Key: $TOKEN" | jq -r '.[] | select(.Name=="STACK_NAME") | .Id'
   

5. Create or update based on whether stack exists.

6. Verify deployment by checking stack status after creation.

When user asks about deployment status:

1. List all stacks or get specific stack by name
2. Get container status for the stack
3. Check container health/logs if issues detected
4. Report status in a clear table format

Status Response Format

Present status in a clear format:

| Stack | Status | Containers | Last Updated |
|-------|--------|------------|--------------|
| my-app | Active | 3/3 running | 2 hours ago |

Error Handling

Common errors and solutions:

Security Notes

• Never commit API tokens or passwords to version control
• Use gh auth token for GitHub credentials (auto-refreshes)
• Portainer tokens should be stored securely or prompted at runtime
• Consider using environment variables for sensitive values

Example: Full Deployment Script

See scripts/deploy-portainer.sh in this repository for a complete example.