Jason Woltje
80c3680ccb
Rename the `rails/` directory to `tools/` for agent discoverability — agents frequently failed to locate helper scripts due to the non-intuitive directory name. Add backward-compat symlink `rails/ → tools/`. New tool suites: - Authentik: auth-token, user-list, user-create, group-list, app-list, flow-list, admin-status (8 scripts) - Coolify: team-list, project-list, service-list, service-status, deploy, env-set (7 scripts) - Woodpecker: pipeline-list, pipeline-status, pipeline-trigger (3 stubs) - GLPI: session-init, computer-list, ticket-list, ticket-create, user-list (6 scripts) - Health: stack-health.sh — stack-wide connectivity check Infrastructure: - Shared credential loader at tools/_lib/credentials.sh - install.sh creates symlink + chmod on tool scripts - All ~253 rails/ path references updated across 68+ files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
211 lines
4.2 KiB
Markdown
211 lines
4.2 KiB
Markdown
# Portainer CLI Scripts
|
|
|
|
CLI tools for managing Portainer stacks via the API.
|
|
|
|
## Setup
|
|
|
|
### Environment Variables
|
|
|
|
Set these environment variables before using the scripts:
|
|
|
|
```bash
|
|
export PORTAINER_URL="https://portainer.example.com:9443"
|
|
export PORTAINER_API_KEY="your-api-key-here"
|
|
```
|
|
|
|
You can add these to your shell profile (`~/.bashrc`, `~/.zshrc`) or use a `.env` file.
|
|
|
|
### Creating an API Key
|
|
|
|
1. Log in to Portainer
|
|
2. Click your username in the top right corner > "My account"
|
|
3. Scroll to "Access tokens" section
|
|
4. Click "Add access token"
|
|
5. Enter a descriptive name (e.g., "CLI scripts")
|
|
6. Copy the token immediately (you cannot view it again)
|
|
|
|
### Dependencies
|
|
|
|
- `curl` - HTTP client
|
|
- `jq` - JSON processor
|
|
|
|
Both are typically pre-installed on most Linux distributions.
|
|
|
|
## Scripts
|
|
|
|
### stack-list.sh
|
|
|
|
List all Portainer stacks.
|
|
|
|
```bash
|
|
# List all stacks in table format
|
|
stack-list.sh
|
|
|
|
# List stacks in JSON format
|
|
stack-list.sh -f json
|
|
|
|
# List only stack names
|
|
stack-list.sh -f names
|
|
stack-list.sh -q
|
|
|
|
# Filter by endpoint ID
|
|
stack-list.sh -e 1
|
|
```
|
|
|
|
### stack-status.sh
|
|
|
|
Show status and containers for a stack.
|
|
|
|
```bash
|
|
# Show stack status
|
|
stack-status.sh -n mystack
|
|
|
|
# Show status in JSON format
|
|
stack-status.sh -n mystack -f json
|
|
|
|
# Use stack ID instead of name
|
|
stack-status.sh -i 5
|
|
```
|
|
|
|
### stack-redeploy.sh
|
|
|
|
Redeploy a stack. For git-based stacks, this pulls the latest from the repository.
|
|
|
|
```bash
|
|
# Redeploy a stack by name
|
|
stack-redeploy.sh -n mystack
|
|
|
|
# Redeploy and pull latest images
|
|
stack-redeploy.sh -n mystack -p
|
|
|
|
# Redeploy by stack ID
|
|
stack-redeploy.sh -i 5 -p
|
|
```
|
|
|
|
### stack-logs.sh
|
|
|
|
View logs for stack services/containers.
|
|
|
|
```bash
|
|
# List available services in a stack
|
|
stack-logs.sh -n mystack
|
|
|
|
# View logs for a specific service
|
|
stack-logs.sh -n mystack -s webapp
|
|
|
|
# Show last 200 lines
|
|
stack-logs.sh -n mystack -s webapp -t 200
|
|
|
|
# Follow logs (stream)
|
|
stack-logs.sh -n mystack -s webapp -f
|
|
|
|
# Include timestamps
|
|
stack-logs.sh -n mystack -s webapp --timestamps
|
|
```
|
|
|
|
### stack-start.sh
|
|
|
|
Start an inactive stack.
|
|
|
|
```bash
|
|
stack-start.sh -n mystack
|
|
stack-start.sh -i 5
|
|
```
|
|
|
|
### stack-stop.sh
|
|
|
|
Stop a running stack.
|
|
|
|
```bash
|
|
stack-stop.sh -n mystack
|
|
stack-stop.sh -i 5
|
|
```
|
|
|
|
### endpoint-list.sh
|
|
|
|
List all Portainer endpoints/environments.
|
|
|
|
```bash
|
|
# List in table format
|
|
endpoint-list.sh
|
|
|
|
# List in JSON format
|
|
endpoint-list.sh -f json
|
|
```
|
|
|
|
## Common Workflows
|
|
|
|
### CI/CD Redeploy
|
|
|
|
After pushing changes to a git-based stack's repository:
|
|
|
|
```bash
|
|
# Redeploy with latest images
|
|
stack-redeploy.sh -n myapp -p
|
|
|
|
# Check status
|
|
stack-status.sh -n myapp
|
|
|
|
# View logs to verify startup
|
|
stack-logs.sh -n myapp -s api -t 50
|
|
```
|
|
|
|
### Debugging a Failing Stack
|
|
|
|
```bash
|
|
# Check overall status
|
|
stack-status.sh -n myapp
|
|
|
|
# List all services
|
|
stack-logs.sh -n myapp
|
|
|
|
# View logs for failing service
|
|
stack-logs.sh -n myapp -s worker -t 200
|
|
|
|
# Follow logs in real-time
|
|
stack-logs.sh -n myapp -s worker -f
|
|
```
|
|
|
|
### Restart a Stack
|
|
|
|
```bash
|
|
# Stop the stack
|
|
stack-stop.sh -n myapp
|
|
|
|
# Start it again
|
|
stack-start.sh -n myapp
|
|
|
|
# Or just redeploy (pulls latest images)
|
|
stack-redeploy.sh -n myapp -p
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
All scripts:
|
|
- Exit with code 0 on success
|
|
- Exit with code 1 on error
|
|
- Print errors to stderr
|
|
- Validate required environment variables before making API calls
|
|
|
|
## API Reference
|
|
|
|
These scripts use the Portainer CE API. Key endpoints:
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/api/stacks` | GET | List all stacks |
|
|
| `/api/stacks/{id}` | GET | Get stack details |
|
|
| `/api/stacks/{id}/file` | GET | Get stack compose file |
|
|
| `/api/stacks/{id}` | PUT | Update/redeploy stack |
|
|
| `/api/stacks/{id}/git/redeploy` | PUT | Redeploy git-based stack |
|
|
| `/api/stacks/{id}/start` | POST | Start inactive stack |
|
|
| `/api/stacks/{id}/stop` | POST | Stop running stack |
|
|
| `/api/endpoints` | GET | List all environments |
|
|
| `/api/endpoints/{id}/docker/containers/json` | GET | List containers |
|
|
| `/api/endpoints/{id}/docker/containers/{id}/logs` | GET | Get container logs |
|
|
|
|
For full API documentation, see:
|
|
- [Portainer API Access](https://docs.portainer.io/api/access)
|
|
- [Portainer API Examples](https://docs.portainer.io/api/examples)
|
|
- [Portainer API Docs](https://docs.portainer.io/api/docs)
|