feat: rename rails/ to tools/ and add service tool suites

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>
2026-02-22 11:51:39 -06:00
parent 248db8935c
commit 80c3680ccb
158 changed files with 2481 additions and 213 deletions
--- a/tools/portainer/README.md
+++ b/tools/portainer/README.md
@@ -0,0 +1,210 @@
+# 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)