feat(marketplace): command consolidation + 8 new plugins (v8.1.0 → v9.0.0) [BREAKING]
Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action> sub-command pattern. Git-flow consolidated from 8→5 commands (commit variants absorbed into --push/--merge/--sync flags). Dispatch files, name: frontmatter, and cross-reference updates for all plugins. Phase 2: Design documents for 8 new plugins in docs/designs/. Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot, data-seed, ops-release-manager, ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents, skills, README, and claude-md-integration. Marketplace grows from 12→20. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
25
plugins/ops-deploy-pipeline/.claude-plugin/plugin.json
Normal file
25
plugins/ops-deploy-pipeline/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,25 @@
|
||||
{
|
||||
"name": "ops-deploy-pipeline",
|
||||
"version": "1.0.0",
|
||||
"description": "CI/CD deployment pipeline management for Docker Compose and self-hosted infrastructure",
|
||||
"author": {
|
||||
"name": "Leo Miranda",
|
||||
"email": "leobmiranda@gmail.com"
|
||||
},
|
||||
"homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/ops-deploy-pipeline/README.md",
|
||||
"repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"deployment",
|
||||
"docker-compose",
|
||||
"caddy",
|
||||
"ci-cd",
|
||||
"infrastructure",
|
||||
"rollback",
|
||||
"self-hosted"
|
||||
],
|
||||
"commands": [
|
||||
"./commands/"
|
||||
],
|
||||
"domain": "ops"
|
||||
}
|
||||
68
plugins/ops-deploy-pipeline/README.md
Normal file
68
plugins/ops-deploy-pipeline/README.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# ops-deploy-pipeline
|
||||
|
||||
CI/CD deployment pipeline management for Docker Compose and self-hosted infrastructure.
|
||||
|
||||
## Overview
|
||||
|
||||
This plugin provides deployment configuration generation, validation, environment management, and rollback planning for services running on Docker Compose with Caddy reverse proxy. It is designed for self-hosted infrastructure, particularly Raspberry Pi and ARM64 targets.
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/deploy setup` | Interactive setup wizard for deployment configuration |
|
||||
| `/deploy generate` | Generate docker-compose.yml, Caddyfile, and systemd units |
|
||||
| `/deploy validate` | Validate deployment configs for correctness and best practices |
|
||||
| `/deploy env` | Manage environment-specific config files |
|
||||
| `/deploy check` | Pre-deployment health check (disk, memory, ports, DNS, Docker) |
|
||||
| `/deploy rollback` | Generate rollback plan for a deployment |
|
||||
|
||||
## Agents
|
||||
|
||||
| Agent | Model | Mode | Purpose |
|
||||
|-------|-------|------|---------|
|
||||
| deploy-planner | sonnet | default | Configuration generation and rollback planning |
|
||||
| deploy-validator | haiku | plan | Read-only validation and health checks |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| compose-patterns | Docker Compose best practices and multi-service patterns |
|
||||
| caddy-conventions | Caddyfile reverse proxy and subdomain routing patterns |
|
||||
| env-management | Environment variable management across deployment stages |
|
||||
| health-checks | Pre-deployment system health verification |
|
||||
| rollback-patterns | Deployment rollback strategies and data safety |
|
||||
| visual-header | Standard command output header |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
plugins/ops-deploy-pipeline/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── commands/
|
||||
│ ├── deploy.md # Dispatch file
|
||||
│ ├── deploy-setup.md
|
||||
│ ├── deploy-generate.md
|
||||
│ ├── deploy-validate.md
|
||||
│ ├── deploy-env.md
|
||||
│ ├── deploy-check.md
|
||||
│ └── deploy-rollback.md
|
||||
├── agents/
|
||||
│ ├── deploy-planner.md
|
||||
│ └── deploy-validator.md
|
||||
├── skills/
|
||||
│ ├── compose-patterns.md
|
||||
│ ├── caddy-conventions.md
|
||||
│ ├── env-management.md
|
||||
│ ├── health-checks.md
|
||||
│ ├── rollback-patterns.md
|
||||
│ └── visual-header.md
|
||||
├── claude-md-integration.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License - Part of the Leo Claude Marketplace.
|
||||
71
plugins/ops-deploy-pipeline/agents/deploy-planner.md
Normal file
71
plugins/ops-deploy-pipeline/agents/deploy-planner.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: deploy-planner
|
||||
description: Deployment configuration generation and rollback planning for self-hosted services. Use for generating docker-compose.yml, Caddyfile, systemd units, environment configs, and rollback plans.
|
||||
model: sonnet
|
||||
permissionMode: default
|
||||
---
|
||||
|
||||
# Deploy Planner Agent
|
||||
|
||||
You are a deployment engineer specializing in Docker Compose-based self-hosted infrastructure. You generate production-ready configuration files and rollback plans.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/compose-patterns.md`
|
||||
- `skills/caddy-conventions.md`
|
||||
- `skills/env-management.md`
|
||||
- `skills/rollback-patterns.md`
|
||||
|
||||
## Visual Output Requirements
|
||||
|
||||
**MANDATORY: Display header at start of every response.**
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DEPLOY-PIPELINE - [Context] |
|
||||
+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Expertise
|
||||
|
||||
- Docker Compose service orchestration
|
||||
- Caddy reverse proxy configuration
|
||||
- systemd service unit authoring
|
||||
- Environment variable management and secret handling
|
||||
- Blue-green and recreate rollback strategies
|
||||
- ARM64 (Raspberry Pi) deployment constraints
|
||||
|
||||
## Behavior Guidelines
|
||||
|
||||
### Configuration Generation
|
||||
|
||||
1. **Always generate valid YAML/config** - Syntax must be correct and parseable
|
||||
2. **Pin image versions** - Never use `latest` in generated configs; ask user for specific version
|
||||
3. **Include healthchecks** - Every service gets a healthcheck block
|
||||
4. **Network isolation** - Create dedicated bridge networks, never use `host` mode without justification
|
||||
5. **Resource awareness** - Default to conservative memory limits (256MB) for Raspberry Pi targets
|
||||
6. **Document inline** - Add YAML comments explaining non-obvious choices
|
||||
|
||||
### Environment Management
|
||||
|
||||
1. **Never embed secrets** - Always use `env_file` references
|
||||
2. **Provide .env.example** - Template with placeholder values and documentation comments
|
||||
3. **Separate by environment** - .env.development, .env.staging, .env.production
|
||||
4. **Validate completeness** - Cross-reference docker-compose variable references with env files
|
||||
|
||||
### Rollback Planning
|
||||
|
||||
1. **Capture current state** - Always document what is running before proposing changes
|
||||
2. **Backup data first** - Volume backup commands must precede any destructive operations
|
||||
3. **Estimate downtime** - Be explicit about service interruption duration
|
||||
4. **Flag irreversible changes** - Database migrations, deleted volumes, schema changes
|
||||
|
||||
## Available Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/deploy setup` | Initial project setup wizard |
|
||||
| `/deploy generate` | Generate deployment configs |
|
||||
| `/deploy env` | Manage environment files |
|
||||
| `/deploy rollback` | Create rollback plan |
|
||||
79
plugins/ops-deploy-pipeline/agents/deploy-validator.md
Normal file
79
plugins/ops-deploy-pipeline/agents/deploy-validator.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: deploy-validator
|
||||
description: Read-only validation of deployment configs and pre-flight health checks. Use for validating docker-compose.yml, Caddyfile, and running pre-deployment system checks.
|
||||
model: haiku
|
||||
permissionMode: plan
|
||||
disallowedTools: Write, Edit, MultiEdit
|
||||
---
|
||||
|
||||
# Deploy Validator Agent
|
||||
|
||||
You are a deployment validation specialist. You analyze configuration files for correctness, security issues, and best practices without making any modifications.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/compose-patterns.md`
|
||||
- `skills/health-checks.md`
|
||||
|
||||
## Visual Output Requirements
|
||||
|
||||
**MANDATORY: Display header at start of every response.**
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DEPLOY-PIPELINE - [Context] |
|
||||
+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Expertise
|
||||
|
||||
- Docker Compose YAML syntax and semantics validation
|
||||
- Caddyfile directive validation
|
||||
- systemd unit file correctness
|
||||
- Port conflict detection
|
||||
- Environment variable completeness checking
|
||||
- System resource availability assessment
|
||||
- ARM64 image compatibility verification
|
||||
|
||||
## Behavior Guidelines
|
||||
|
||||
### Read-Only Operation
|
||||
|
||||
You MUST NOT modify any files. Your role is strictly analysis and reporting.
|
||||
|
||||
1. **Read configuration files** - Parse and analyze docker-compose.yml, Caddyfile, .env files
|
||||
2. **Run diagnostic commands** - Use Bash to check system state (disk, memory, ports, Docker)
|
||||
3. **Report findings** - Structured output with severity levels
|
||||
4. **Recommend fixes** - Tell the user what to change, but do not change it yourself
|
||||
|
||||
### Validation Severity Levels
|
||||
|
||||
| Level | Meaning | Action |
|
||||
|-------|---------|--------|
|
||||
| Critical | Deployment will fail or cause data loss | Must fix before deploying |
|
||||
| Warning | Deployment may have issues | Should fix before deploying |
|
||||
| Info | Best practice recommendation | Consider improving |
|
||||
|
||||
### Validation Approach
|
||||
|
||||
1. **Syntax first** - Ensure files parse correctly before checking semantics
|
||||
2. **Cross-reference** - Check that docker-compose services match Caddy upstream targets
|
||||
3. **Environment completeness** - Verify all `${VAR}` references have corresponding values
|
||||
4. **Port conflicts** - Check host ports against running services
|
||||
5. **Architecture compatibility** - Verify images support target architecture
|
||||
|
||||
### Report Format
|
||||
|
||||
Always output findings in a structured report:
|
||||
- Group by severity (Critical > Warning > Info)
|
||||
- Include file path and line number when possible
|
||||
- Provide specific fix recommendation for each finding
|
||||
- End with summary counts and overall PASS/FAIL status
|
||||
|
||||
## Available Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/deploy validate` | Validate deployment configs |
|
||||
| `/deploy check` | Pre-deployment health check |
|
||||
27
plugins/ops-deploy-pipeline/claude-md-integration.md
Normal file
27
plugins/ops-deploy-pipeline/claude-md-integration.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Deploy Pipeline Integration
|
||||
|
||||
Add to your project's CLAUDE.md:
|
||||
|
||||
## Deployment Management (ops-deploy-pipeline)
|
||||
|
||||
This project uses the **ops-deploy-pipeline** plugin for Docker Compose deployment configuration, validation, and rollback planning.
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/deploy setup` | Setup deployment configuration for this project |
|
||||
| `/deploy generate` | Generate docker-compose.yml, Caddyfile, systemd units |
|
||||
| `/deploy validate` | Validate configs for correctness and best practices |
|
||||
| `/deploy env` | Manage .env.development / .env.production files |
|
||||
| `/deploy check` | Pre-deployment health check (system resources, ports, Docker) |
|
||||
| `/deploy rollback` | Generate rollback plan with volume backup steps |
|
||||
|
||||
### Usage Guidelines
|
||||
|
||||
- Run `/deploy setup` first to establish project deployment profile
|
||||
- Use `/deploy generate` to create initial configs, then customize
|
||||
- Always run `/deploy validate` before deploying to catch issues
|
||||
- Use `/deploy check` on the target server before `docker compose up`
|
||||
- Generate a `/deploy rollback` plan before any production deployment
|
||||
- Never commit `.env.production` or `.env.staging` to version control
|
||||
110
plugins/ops-deploy-pipeline/commands/deploy-check.md
Normal file
110
plugins/ops-deploy-pipeline/commands/deploy-check.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
name: deploy check
|
||||
description: Pre-deployment health check — verify system readiness before deploying
|
||||
---
|
||||
|
||||
# /deploy check
|
||||
|
||||
Run pre-deployment health checks to verify the target system is ready.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/health-checks.md`
|
||||
|
||||
## Agent
|
||||
|
||||
Delegate to `agents/deploy-validator.md`.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/deploy check [--service=<name>] [--verbose]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--service` - Check readiness for a specific service only
|
||||
- `--verbose` - Show detailed output for each check
|
||||
|
||||
## Instructions
|
||||
|
||||
Execute `skills/visual-header.md` with context "Pre-Deployment Check".
|
||||
|
||||
### Phase 1: System Resources
|
||||
|
||||
Run system checks using Bash tool:
|
||||
|
||||
| Check | Command | Pass Condition |
|
||||
|-------|---------|----------------|
|
||||
| Disk space | `df -h /` | >10% free |
|
||||
| Memory | `free -m` | >256MB available |
|
||||
| CPU load | `uptime` | Load average < CPU count |
|
||||
| Temperature | `vcgencmd measure_temp` (RPi) or `/sys/class/thermal/` | <70C |
|
||||
|
||||
### Phase 2: Docker Environment
|
||||
|
||||
| Check | Command | Pass Condition |
|
||||
|-------|---------|----------------|
|
||||
| Docker daemon | `docker info` | Running |
|
||||
| Docker Compose | `docker compose version` | Installed |
|
||||
| Disk usage | `docker system df` | <80% usage |
|
||||
| Network | `docker network ls` | Expected networks exist |
|
||||
|
||||
### Phase 3: Port Availability
|
||||
|
||||
1. Read `docker-compose.yml` for all host port mappings
|
||||
2. Check each port with `ss -tlnp | grep :<port>`
|
||||
3. If port is in use, identify the process occupying it
|
||||
4. Flag conflicts as Critical
|
||||
|
||||
### Phase 4: DNS and Network
|
||||
|
||||
| Check | Command | Pass Condition |
|
||||
|-------|---------|----------------|
|
||||
| DNS resolution | `nslookup <subdomain>` | Resolves correctly |
|
||||
| Reverse proxy | `curl -s -o /dev/null -w "%{http_code}" http://localhost:80` | Caddy responding |
|
||||
| Tailscale | `tailscale status` | Connected (if applicable) |
|
||||
|
||||
### Phase 5: Image Availability
|
||||
|
||||
1. Parse `docker-compose.yml` for image references
|
||||
2. Run `docker pull --dry-run <image>` or `docker manifest inspect <image>`
|
||||
3. Verify images exist and support the target architecture (arm64 for RPi)
|
||||
4. Report image sizes and estimated pull time
|
||||
|
||||
### Phase 6: Report
|
||||
|
||||
```
|
||||
## Pre-Deployment Check Report
|
||||
|
||||
### System Resources
|
||||
[OK] Disk: 45% used (54GB free)
|
||||
[OK] Memory: 1.2GB available
|
||||
[OK] CPU: Load 0.8 (4 cores)
|
||||
[OK] Temperature: 52C
|
||||
|
||||
### Docker
|
||||
[OK] Docker daemon: Running (v24.0.7)
|
||||
[OK] Compose: v2.21.0
|
||||
[WARN] Docker disk: 72% used — consider pruning
|
||||
|
||||
### Ports
|
||||
[OK] 8080 — Available
|
||||
[FAIL] 3000 — In use by grafana (PID 1234)
|
||||
|
||||
### Network
|
||||
[OK] DNS: myapp.hotport resolves
|
||||
[OK] Caddy: Responding on :80
|
||||
|
||||
### Images
|
||||
[OK] postgres:16-alpine — arm64 available (89MB)
|
||||
[WARN] custom-app:latest — No arm64 manifest found
|
||||
|
||||
### Summary
|
||||
- Passed: 10 | Warnings: 2 | Failed: 1
|
||||
- Status: NOT READY — fix port conflict on 3000
|
||||
```
|
||||
|
||||
## User Request
|
||||
|
||||
$ARGUMENTS
|
||||
91
plugins/ops-deploy-pipeline/commands/deploy-env.md
Normal file
91
plugins/ops-deploy-pipeline/commands/deploy-env.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
name: deploy env
|
||||
description: Manage environment-specific configuration files for deployments
|
||||
---
|
||||
|
||||
# /deploy env
|
||||
|
||||
Create and manage environment-specific configuration files.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/env-management.md`
|
||||
|
||||
## Agent
|
||||
|
||||
Delegate to `agents/deploy-planner.md`.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/deploy env [--action=<create|diff|sync|list>] [--env=<development|staging|production>]
|
||||
```
|
||||
|
||||
**Actions:**
|
||||
- `create` - Create a new environment config from .env.example (default)
|
||||
- `diff` - Show differences between environment configs
|
||||
- `sync` - Sync missing keys from .env.example to all environments
|
||||
- `list` - List all environment files and their variable counts
|
||||
|
||||
## Instructions
|
||||
|
||||
Execute `skills/visual-header.md` with context "Environment Management".
|
||||
|
||||
### Action: create
|
||||
|
||||
1. Check `.env.example` exists as the source template
|
||||
2. If missing, scan `docker-compose.yml` for referenced `${VARIABLES}` and create `.env.example`
|
||||
3. Ask user which environment to create (development, staging, production)
|
||||
4. Copy `.env.example` to `.env.<environment>`
|
||||
5. For production, flag variables that need real values (API keys, passwords)
|
||||
6. For development, suggest sensible defaults (localhost URLs, debug=true)
|
||||
7. Warn user to never commit `.env.production` to version control
|
||||
8. Verify `.gitignore` includes `.env.production` and `.env.staging`
|
||||
|
||||
### Action: diff
|
||||
|
||||
1. Read all `.env.*` files in the project
|
||||
2. Compare variable names across environments
|
||||
3. Report:
|
||||
- Variables present in one environment but not others
|
||||
- Variables with identical values across environments (potential issue)
|
||||
- Variables in docker-compose but missing from all env files
|
||||
4. Display as a comparison table
|
||||
|
||||
### Action: sync
|
||||
|
||||
1. Read `.env.example` as the canonical list of variables
|
||||
2. For each `.env.<environment>` file:
|
||||
- Identify missing variables
|
||||
- Append missing variables with placeholder values
|
||||
- Report what was added
|
||||
3. Do NOT modify existing values
|
||||
|
||||
### Action: list
|
||||
|
||||
1. List all `.env*` files in the project
|
||||
2. For each file, show:
|
||||
- Variable count
|
||||
- Last modified date
|
||||
- Whether all docker-compose referenced variables are present
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Environment Files
|
||||
|
||||
| File | Variables | Coverage | Status |
|
||||
|------|-----------|----------|--------|
|
||||
| .env.example | 12 | 100% | Template |
|
||||
| .env.development | 12 | 100% | OK |
|
||||
| .env.production | 10 | 83% | Missing 2 vars |
|
||||
|
||||
### Missing in .env.production
|
||||
- DATABASE_URL (referenced in docker-compose.yml:15)
|
||||
- REDIS_PASSWORD (referenced in docker-compose.yml:28)
|
||||
```
|
||||
|
||||
## User Request
|
||||
|
||||
$ARGUMENTS
|
||||
102
plugins/ops-deploy-pipeline/commands/deploy-generate.md
Normal file
102
plugins/ops-deploy-pipeline/commands/deploy-generate.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
name: deploy generate
|
||||
description: Generate docker-compose.yml, Caddyfile, and systemd units for a service
|
||||
---
|
||||
|
||||
# /deploy generate
|
||||
|
||||
Generate deployment configuration files from templates and project context.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/compose-patterns.md`
|
||||
- `skills/caddy-conventions.md`
|
||||
- `skills/env-management.md`
|
||||
|
||||
## Agent
|
||||
|
||||
Delegate to `agents/deploy-planner.md`.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/deploy generate [--target=<compose|caddy|systemd|all>] [--service=<name>]
|
||||
```
|
||||
|
||||
**Targets:**
|
||||
- `compose` - Generate docker-compose.yml only
|
||||
- `caddy` - Generate Caddyfile snippet only
|
||||
- `systemd` - Generate systemd service unit only
|
||||
- `all` - Generate all configuration files (default)
|
||||
|
||||
## Instructions
|
||||
|
||||
Execute `skills/visual-header.md` with context "Config Generation".
|
||||
|
||||
### Phase 1: Context Analysis
|
||||
|
||||
1. Read existing project files to determine:
|
||||
- Application language/framework (Dockerfile, package.json, requirements.txt, go.mod)
|
||||
- Required services (database, cache, message queue)
|
||||
- Exposed ports
|
||||
- Volume requirements (data persistence, config files)
|
||||
2. Check if `deploy/` directory exists from previous `/deploy setup`
|
||||
3. Read `.env.example` if present for variable names
|
||||
|
||||
### Phase 2: Docker Compose Generation
|
||||
|
||||
Apply patterns from `skills/compose-patterns.md`:
|
||||
|
||||
1. **Service definition** - Image or build context, restart policy, healthcheck
|
||||
2. **Network isolation** - Create dedicated network for the stack
|
||||
3. **Volume management** - Named volumes for persistence, bind mounts for config
|
||||
4. **Resource limits** - Memory and CPU limits appropriate for target platform
|
||||
5. **Dependency ordering** - `depends_on` with `condition: service_healthy`
|
||||
6. **Environment variables** - Reference `env_file` rather than inline secrets
|
||||
|
||||
### Phase 3: Caddyfile Generation
|
||||
|
||||
Apply patterns from `skills/caddy-conventions.md`:
|
||||
|
||||
1. **Subdomain routing** - `subdomain.hostname` block
|
||||
2. **Reverse proxy** - Point to container:port with Docker network DNS
|
||||
3. **Headers** - Security headers, CORS if needed
|
||||
4. **Rate limiting** - Default rate limit for API endpoints
|
||||
|
||||
### Phase 4: Systemd Unit Generation (optional)
|
||||
|
||||
Generate `systemd/<service>.service` for non-Docker services:
|
||||
1. Unit description and dependencies
|
||||
2. ExecStart/ExecStop commands
|
||||
3. Restart policy and watchdog
|
||||
4. User/Group restrictions
|
||||
|
||||
### Phase 5: Output
|
||||
|
||||
1. Show generated files with syntax highlighting
|
||||
2. Ask user to confirm before writing
|
||||
3. Write files to appropriate locations
|
||||
4. Display validation summary
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Generated Files
|
||||
|
||||
### docker-compose.yml
|
||||
[content with annotations]
|
||||
|
||||
### Caddyfile snippet
|
||||
[content with annotations]
|
||||
|
||||
### Summary
|
||||
- Services: 3 (app, db, redis)
|
||||
- Networks: 1 (app-network)
|
||||
- Volumes: 2 (db-data, redis-data)
|
||||
- Next: /deploy validate
|
||||
```
|
||||
|
||||
## User Request
|
||||
|
||||
$ARGUMENTS
|
||||
126
plugins/ops-deploy-pipeline/commands/deploy-rollback.md
Normal file
126
plugins/ops-deploy-pipeline/commands/deploy-rollback.md
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
name: deploy rollback
|
||||
description: Generate a rollback plan to revert a deployment to the previous state
|
||||
---
|
||||
|
||||
# /deploy rollback
|
||||
|
||||
Generate a rollback plan for reverting a deployment.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/rollback-patterns.md`
|
||||
- `skills/compose-patterns.md`
|
||||
|
||||
## Agent
|
||||
|
||||
Delegate to `agents/deploy-planner.md`.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/deploy rollback [--service=<name>] [--dry-run] [--strategy=<recreate|blue-green>]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--service` - Target a specific service (default: entire stack)
|
||||
- `--dry-run` - Show plan without executing
|
||||
- `--strategy` - Rollback strategy: `recreate` (default) or `blue-green`
|
||||
|
||||
## Instructions
|
||||
|
||||
Execute `skills/visual-header.md` with context "Rollback Planning".
|
||||
|
||||
### Phase 1: Current State Capture
|
||||
|
||||
1. List running containers for the stack:
|
||||
```bash
|
||||
docker compose ps
|
||||
```
|
||||
2. Record current image digests:
|
||||
```bash
|
||||
docker compose images
|
||||
```
|
||||
3. Check for volume data that may need backup:
|
||||
```bash
|
||||
docker volume ls --filter name=<stack>
|
||||
```
|
||||
4. Record current environment variables from `.env`
|
||||
5. Save current `docker-compose.yml` hash for verification
|
||||
|
||||
### Phase 2: Previous State Detection
|
||||
|
||||
Attempt to identify the previous deployment state:
|
||||
|
||||
1. Check git history for previous `docker-compose.yml`:
|
||||
```bash
|
||||
git log --oneline -5 -- docker-compose.yml
|
||||
```
|
||||
2. Check Docker image history for previous tags
|
||||
3. Look for backup files: `docker-compose.yml.bak`, `.env.bak`
|
||||
4. If no previous state found, warn user and ask for target state
|
||||
|
||||
### Phase 3: Rollback Plan Generation
|
||||
|
||||
Apply patterns from `skills/rollback-patterns.md`:
|
||||
|
||||
#### Strategy: recreate (default)
|
||||
1. Stop current containers: `docker compose down`
|
||||
2. Restore previous docker-compose.yml from git
|
||||
3. Restore previous .env file
|
||||
4. Pull previous images if needed
|
||||
5. Start containers: `docker compose up -d`
|
||||
6. Verify health checks pass
|
||||
|
||||
#### Strategy: blue-green
|
||||
1. Start previous version alongside current (different ports)
|
||||
2. Verify previous version health
|
||||
3. Switch reverse proxy to point to previous version
|
||||
4. Stop current version
|
||||
5. Rename previous version to use standard ports
|
||||
|
||||
### Phase 4: Data Considerations
|
||||
|
||||
1. Identify services with persistent volumes (databases, file storage)
|
||||
2. Check if database migrations were run (irreversible changes)
|
||||
3. Recommend volume backup before rollback:
|
||||
```bash
|
||||
docker run --rm -v <volume>:/data -v $(pwd):/backup alpine tar czf /backup/<volume>.tar.gz /data
|
||||
```
|
||||
4. Flag if rollback may cause data loss
|
||||
|
||||
### Phase 5: Output
|
||||
|
||||
```
|
||||
## Rollback Plan
|
||||
|
||||
### Target
|
||||
- Service: myapp-stack
|
||||
- Current: v2.1.0 (deployed 2h ago)
|
||||
- Rollback to: v2.0.3
|
||||
|
||||
### Steps
|
||||
1. Backup database volume (estimated: 2min)
|
||||
docker run --rm -v myapp_db:/data -v $(pwd):/backup alpine tar czf /backup/db-backup.tar.gz /data
|
||||
2. Stop current stack
|
||||
docker compose down
|
||||
3. Restore previous config
|
||||
git checkout HEAD~1 -- docker-compose.yml
|
||||
4. Start previous version
|
||||
docker compose up -d
|
||||
5. Verify health
|
||||
docker compose ps
|
||||
|
||||
### Warnings
|
||||
- Database migration v45 was applied — may need manual revert
|
||||
- Volume myapp_uploads has 230MB of new data since last deploy
|
||||
|
||||
### Estimated Downtime
|
||||
- Strategy: recreate — ~30 seconds
|
||||
- Strategy: blue-green — ~0 seconds (requires port availability)
|
||||
```
|
||||
|
||||
## User Request
|
||||
|
||||
$ARGUMENTS
|
||||
81
plugins/ops-deploy-pipeline/commands/deploy-setup.md
Normal file
81
plugins/ops-deploy-pipeline/commands/deploy-setup.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: deploy setup
|
||||
description: Interactive setup wizard for deployment pipeline configuration
|
||||
---
|
||||
|
||||
# /deploy setup
|
||||
|
||||
Configure the ops-deploy-pipeline plugin for a project.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/compose-patterns.md`
|
||||
|
||||
## Agent
|
||||
|
||||
Delegate to `agents/deploy-planner.md`.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/deploy setup
|
||||
```
|
||||
|
||||
## Instructions
|
||||
|
||||
Execute `skills/visual-header.md` with context "Setup Wizard".
|
||||
|
||||
### Phase 1: Project Detection
|
||||
|
||||
1. Read the current directory for existing configuration files:
|
||||
- `docker-compose.yml` or `docker-compose.yaml`
|
||||
- `Caddyfile` or `caddy/Caddyfile`
|
||||
- `.env`, `.env.example`, `.env.production`, `.env.development`
|
||||
- `systemd/*.service` files
|
||||
2. Report what was found and what is missing
|
||||
|
||||
### Phase 2: Deployment Profile
|
||||
|
||||
Ask user to select deployment profile:
|
||||
|
||||
| Profile | Description |
|
||||
|---------|-------------|
|
||||
| **single-service** | One container, one reverse proxy entry |
|
||||
| **multi-service** | Multiple containers with shared network |
|
||||
| **full-stack** | Application + database + cache + reverse proxy |
|
||||
|
||||
### Phase 3: Infrastructure Target
|
||||
|
||||
Collect target information:
|
||||
1. **Hostname** - Server hostname (e.g., `hotport`)
|
||||
2. **Subdomain** - Service subdomain (e.g., `myapp.hotport`)
|
||||
3. **Port** - Internal service port
|
||||
4. **Network mode** - Tailscale, local, or both
|
||||
|
||||
### Phase 4: Generate Scaffold
|
||||
|
||||
Based on profile and target:
|
||||
1. Create `deploy/` directory if it does not exist
|
||||
2. Generate `.env.example` with documented variables
|
||||
3. Create deployment checklist in `deploy/CHECKLIST.md`
|
||||
4. Report next steps to user
|
||||
|
||||
### Completion Summary
|
||||
|
||||
```
|
||||
DEPLOY-PIPELINE SETUP COMPLETE
|
||||
|
||||
Profile: multi-service
|
||||
Target: myapp.hotport
|
||||
Config Dir: deploy/
|
||||
|
||||
Next steps:
|
||||
- /deploy generate Generate docker-compose.yml and Caddyfile
|
||||
- /deploy env Create environment-specific configs
|
||||
- /deploy validate Validate generated configs
|
||||
```
|
||||
|
||||
## User Request
|
||||
|
||||
$ARGUMENTS
|
||||
103
plugins/ops-deploy-pipeline/commands/deploy-validate.md
Normal file
103
plugins/ops-deploy-pipeline/commands/deploy-validate.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: deploy validate
|
||||
description: Validate deployment configs for correctness, security, and best practices
|
||||
---
|
||||
|
||||
# /deploy validate
|
||||
|
||||
Validate Docker Compose, Caddyfile, and systemd configurations.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- `skills/visual-header.md`
|
||||
- `skills/compose-patterns.md`
|
||||
- `skills/health-checks.md`
|
||||
|
||||
## Agent
|
||||
|
||||
Delegate to `agents/deploy-validator.md`.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/deploy validate [--target=<compose|caddy|systemd|all>] [--strict]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--target` - Which config to validate (default: `all`)
|
||||
- `--strict` - Treat warnings as errors
|
||||
|
||||
## Instructions
|
||||
|
||||
Execute `skills/visual-header.md` with context "Config Validation".
|
||||
|
||||
### Phase 1: File Discovery
|
||||
|
||||
Locate configuration files:
|
||||
- `docker-compose.yml` / `docker-compose.yaml`
|
||||
- `Caddyfile` or `caddy/Caddyfile`
|
||||
- `systemd/*.service`
|
||||
- `.env`, `.env.production`, `.env.development`
|
||||
|
||||
Report any expected files that are missing.
|
||||
|
||||
### Phase 2: Docker Compose Validation
|
||||
|
||||
Check against patterns from `skills/compose-patterns.md`:
|
||||
|
||||
| Check | Severity | Description |
|
||||
|-------|----------|-------------|
|
||||
| Valid YAML syntax | Critical | File must parse correctly |
|
||||
| Image tags pinned | Warning | Avoid `latest` tag in production |
|
||||
| Healthchecks defined | Warning | All services should have healthchecks |
|
||||
| Restart policy set | Warning | Should be `unless-stopped` or `always` |
|
||||
| Resource limits | Info | Memory/CPU limits recommended for constrained hosts |
|
||||
| Network isolation | Warning | Services should use dedicated network, not `host` |
|
||||
| Volume permissions | Warning | Bind mounts should have explicit read/write mode |
|
||||
| No hardcoded secrets | Critical | Secrets must use env_file or Docker secrets |
|
||||
| Port conflicts | Critical | No duplicate host port mappings |
|
||||
| Dependency ordering | Info | Services with depends_on should use health conditions |
|
||||
|
||||
### Phase 3: Caddyfile Validation
|
||||
|
||||
| Check | Severity | Description |
|
||||
|-------|----------|-------------|
|
||||
| Valid syntax | Critical | Directives must be properly formatted |
|
||||
| HTTPS configuration | Info | Automatic HTTPS or explicit cert paths |
|
||||
| Reverse proxy targets | Warning | Target must match docker-compose service names |
|
||||
| Security headers | Info | Recommend X-Frame-Options, CSP, HSTS |
|
||||
| Duplicate routes | Critical | No conflicting route definitions |
|
||||
|
||||
### Phase 4: Environment File Validation
|
||||
|
||||
| Check | Severity | Description |
|
||||
|-------|----------|-------------|
|
||||
| .env.example exists | Warning | Template for required variables |
|
||||
| No secrets in .env.example | Critical | Example file must use placeholders |
|
||||
| All referenced vars defined | Critical | docker-compose env vars must have values |
|
||||
| Consistent across environments | Info | Same keys in dev/staging/prod |
|
||||
|
||||
### Phase 5: Report
|
||||
|
||||
```
|
||||
## Validation Report
|
||||
|
||||
### Critical (must fix)
|
||||
- [file:line] Description of issue
|
||||
Fix: Recommended solution
|
||||
|
||||
### Warnings (should fix)
|
||||
- [file:line] Description of issue
|
||||
Fix: Recommended solution
|
||||
|
||||
### Info (consider)
|
||||
- [file:line] Description of improvement
|
||||
|
||||
### Summary
|
||||
- Critical: X | Warnings: Y | Info: Z
|
||||
- Status: PASS / FAIL
|
||||
```
|
||||
|
||||
## User Request
|
||||
|
||||
$ARGUMENTS
|
||||
18
plugins/ops-deploy-pipeline/commands/deploy.md
Normal file
18
plugins/ops-deploy-pipeline/commands/deploy.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
description: Deployment management — generate configs, validate pipelines, manage environments
|
||||
---
|
||||
|
||||
# /deploy
|
||||
|
||||
CI/CD deployment pipeline management for Docker Compose and self-hosted infrastructure.
|
||||
|
||||
## Sub-commands
|
||||
|
||||
| Sub-command | Description |
|
||||
|-------------|-------------|
|
||||
| `/deploy setup` | Interactive setup wizard for deployment configuration |
|
||||
| `/deploy generate` | Generate docker-compose.yml, Caddyfile, and systemd units |
|
||||
| `/deploy validate` | Validate deployment configs for correctness and best practices |
|
||||
| `/deploy env` | Manage environment-specific config files (.env.development, .env.production) |
|
||||
| `/deploy check` | Pre-deployment health check (disk, memory, ports, DNS, Docker) |
|
||||
| `/deploy rollback` | Generate rollback plan for a deployment |
|
||||
126
plugins/ops-deploy-pipeline/skills/caddy-conventions.md
Normal file
126
plugins/ops-deploy-pipeline/skills/caddy-conventions.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# Caddy Conventions Skill
|
||||
|
||||
Caddyfile patterns for reverse proxy configuration in self-hosted environments.
|
||||
|
||||
## Subdomain Routing
|
||||
|
||||
Each service gets a subdomain of the server hostname:
|
||||
|
||||
```caddyfile
|
||||
myapp.hotport {
|
||||
reverse_proxy app:8080
|
||||
}
|
||||
```
|
||||
|
||||
For services on non-standard ports:
|
||||
```caddyfile
|
||||
myapp.hotport {
|
||||
reverse_proxy app:3000
|
||||
}
|
||||
```
|
||||
|
||||
## Reverse Proxy Directives
|
||||
|
||||
### Basic Reverse Proxy
|
||||
|
||||
```caddyfile
|
||||
subdomain.hostname {
|
||||
reverse_proxy container_name:port
|
||||
}
|
||||
```
|
||||
|
||||
### With Health Checks
|
||||
|
||||
```caddyfile
|
||||
subdomain.hostname {
|
||||
reverse_proxy container_name:port {
|
||||
health_uri /health
|
||||
health_interval 30s
|
||||
health_timeout 10s
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Load Balancing (Multiple Instances)
|
||||
|
||||
```caddyfile
|
||||
subdomain.hostname {
|
||||
reverse_proxy app1:8080 app2:8080 {
|
||||
lb_policy round_robin
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Headers
|
||||
|
||||
Apply to all sites:
|
||||
|
||||
```caddyfile
|
||||
(security_headers) {
|
||||
header {
|
||||
X-Content-Type-Options nosniff
|
||||
X-Frame-Options SAMEORIGIN
|
||||
Referrer-Policy strict-origin-when-cross-origin
|
||||
-Server
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Import in site blocks: `import security_headers`
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
For API endpoints:
|
||||
|
||||
```caddyfile
|
||||
subdomain.hostname {
|
||||
rate_limit {
|
||||
zone api_zone {
|
||||
key {remote_host}
|
||||
events 100
|
||||
window 1m
|
||||
}
|
||||
}
|
||||
reverse_proxy app:8080
|
||||
}
|
||||
```
|
||||
|
||||
## Docker Network Integration
|
||||
|
||||
Caddy must be on the same Docker network as the target service to use container DNS names. The Caddy container needs:
|
||||
|
||||
```yaml
|
||||
networks:
|
||||
- caddy-network
|
||||
- app-network # Join each app's network
|
||||
```
|
||||
|
||||
## CORS Configuration
|
||||
|
||||
```caddyfile
|
||||
subdomain.hostname {
|
||||
header Access-Control-Allow-Origin "*"
|
||||
header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
|
||||
header Access-Control-Allow-Headers "Content-Type, Authorization"
|
||||
|
||||
@options method OPTIONS
|
||||
respond @options 204
|
||||
|
||||
reverse_proxy app:8080
|
||||
}
|
||||
```
|
||||
|
||||
## Automatic HTTPS
|
||||
|
||||
- Caddy provides automatic HTTPS for public domains
|
||||
- For local `.hotport` subdomains, use HTTP only (no valid TLS cert)
|
||||
- For Tailscale access, consider `tls internal` for self-signed certs
|
||||
|
||||
## File Server (Static Assets)
|
||||
|
||||
```caddyfile
|
||||
files.hotport {
|
||||
root * /srv/files
|
||||
file_server browse
|
||||
}
|
||||
```
|
||||
127
plugins/ops-deploy-pipeline/skills/compose-patterns.md
Normal file
127
plugins/ops-deploy-pipeline/skills/compose-patterns.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Docker Compose Patterns Skill
|
||||
|
||||
Best practices and patterns for Docker Compose service definitions targeting self-hosted infrastructure.
|
||||
|
||||
## Service Naming
|
||||
|
||||
- Use lowercase with hyphens: `my-service`
|
||||
- Prefix with stack name for multi-project hosts: `myapp-db`, `myapp-redis`
|
||||
- Container name should match service name: `container_name: myapp-db`
|
||||
|
||||
## Network Isolation
|
||||
|
||||
Every stack should define its own bridge network:
|
||||
|
||||
```yaml
|
||||
networks:
|
||||
app-network:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
Services join the stack network. Only the reverse proxy entry point should be exposed to the host.
|
||||
|
||||
## Volume Management
|
||||
|
||||
- Use **named volumes** for data persistence (databases, uploads)
|
||||
- Use **bind mounts** for configuration files only
|
||||
- Set explicit permissions with `:ro` for read-only mounts
|
||||
- Label volumes with `labels` for identification
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
db-data:
|
||||
labels:
|
||||
com.project: myapp
|
||||
com.service: database
|
||||
```
|
||||
|
||||
## Healthchecks
|
||||
|
||||
Every service MUST have a healthcheck:
|
||||
|
||||
```yaml
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 40s
|
||||
```
|
||||
|
||||
Common healthcheck patterns:
|
||||
- HTTP: `curl -f http://localhost:<port>/health`
|
||||
- PostgreSQL: `pg_isready -U <user>`
|
||||
- Redis: `redis-cli ping`
|
||||
- MySQL: `mysqladmin ping -h localhost`
|
||||
|
||||
## Restart Policies
|
||||
|
||||
| Environment | Policy |
|
||||
|-------------|--------|
|
||||
| Development | `restart: "no"` |
|
||||
| Production | `restart: unless-stopped` |
|
||||
| Critical services | `restart: always` |
|
||||
|
||||
## Resource Limits
|
||||
|
||||
For Raspberry Pi (8GB RAM):
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 256M
|
||||
cpus: '1.0'
|
||||
reservations:
|
||||
memory: 128M
|
||||
```
|
||||
|
||||
## Dependency Ordering
|
||||
|
||||
Use healthcheck-aware dependencies:
|
||||
|
||||
```yaml
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_started
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Never inline secrets. Use `env_file`:
|
||||
|
||||
```yaml
|
||||
env_file:
|
||||
- .env
|
||||
- .env.${DEPLOY_ENV:-development}
|
||||
```
|
||||
|
||||
## Multi-Service Patterns
|
||||
|
||||
### Web App + Database + Cache
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
image: myapp:1.0.0
|
||||
env_file: [.env]
|
||||
depends_on:
|
||||
db: { condition: service_healthy }
|
||||
redis: { condition: service_healthy }
|
||||
networks: [app-network]
|
||||
|
||||
db:
|
||||
image: postgres:16-alpine
|
||||
volumes: [db-data:/var/lib/postgresql/data]
|
||||
healthcheck:
|
||||
test: ["CMD", "pg_isready", "-U", "postgres"]
|
||||
networks: [app-network]
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
healthcheck:
|
||||
test: ["CMD", "redis-cli", "ping"]
|
||||
networks: [app-network]
|
||||
```
|
||||
92
plugins/ops-deploy-pipeline/skills/env-management.md
Normal file
92
plugins/ops-deploy-pipeline/skills/env-management.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Environment Management Skill
|
||||
|
||||
Patterns for managing environment variables across deployment stages.
|
||||
|
||||
## File Naming Convention
|
||||
|
||||
| File | Purpose | Git Tracked |
|
||||
|------|---------|-------------|
|
||||
| `.env.example` | Template with placeholder values | Yes |
|
||||
| `.env` | Local development defaults | No |
|
||||
| `.env.development` | Development-specific overrides | No |
|
||||
| `.env.staging` | Staging environment values | No |
|
||||
| `.env.production` | Production secrets and config | No |
|
||||
|
||||
## .env.example Format
|
||||
|
||||
Document every variable with comments:
|
||||
|
||||
```bash
|
||||
# Application Settings
|
||||
APP_NAME=myapp
|
||||
APP_PORT=8080
|
||||
APP_DEBUG=false
|
||||
|
||||
# Database Configuration
|
||||
# PostgreSQL connection string
|
||||
DATABASE_URL=postgresql://user:password@db:5432/myapp
|
||||
DATABASE_POOL_SIZE=5
|
||||
|
||||
# Redis Configuration
|
||||
REDIS_URL=redis://redis:6379/0
|
||||
|
||||
# External Services
|
||||
# Generate at: https://example.com/api-keys
|
||||
API_KEY=your-api-key-here
|
||||
API_SECRET=your-secret-here
|
||||
```
|
||||
|
||||
## Secret Handling Rules
|
||||
|
||||
1. **Never commit secrets** to version control
|
||||
2. `.env.production` and `.env.staging` MUST be in `.gitignore`
|
||||
3. Use placeholder values in `.env.example`: `your-api-key-here`, `changeme`, `<required>`
|
||||
4. For shared team secrets, use a secrets manager or encrypted vault
|
||||
5. Document where to obtain each secret in comments
|
||||
|
||||
## Docker Compose Integration
|
||||
|
||||
### Single env_file
|
||||
|
||||
```yaml
|
||||
env_file:
|
||||
- .env
|
||||
```
|
||||
|
||||
### Multi-environment
|
||||
|
||||
```yaml
|
||||
env_file:
|
||||
- .env
|
||||
- .env.${DEPLOY_ENV:-development}
|
||||
```
|
||||
|
||||
### Variable Interpolation
|
||||
|
||||
Docker Compose supports `${VAR:-default}` syntax:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
image: myapp:${APP_VERSION:-latest}
|
||||
ports:
|
||||
- "${APP_PORT:-8080}:8080"
|
||||
```
|
||||
|
||||
## Environment Diff Checking
|
||||
|
||||
When comparing environments, check for:
|
||||
|
||||
1. **Missing variables** - Present in .env.example but absent in target
|
||||
2. **Extra variables** - Present in target but not in .env.example (may be stale)
|
||||
3. **Placeholder values** - Production still has `changeme` or `your-*-here`
|
||||
4. **Identical secrets** - Same password used in dev and prod (security risk)
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] All docker-compose `${VAR}` references have corresponding entries
|
||||
- [ ] No secrets in `.env.example`
|
||||
- [ ] `.gitignore` excludes `.env.production` and `.env.staging`
|
||||
- [ ] Production variables have real values (no placeholders)
|
||||
- [ ] Database URLs point to correct hosts per environment
|
||||
- [ ] Debug flags are `false` in production
|
||||
114
plugins/ops-deploy-pipeline/skills/health-checks.md
Normal file
114
plugins/ops-deploy-pipeline/skills/health-checks.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Health Checks Skill
|
||||
|
||||
Pre-deployment system health checks for self-hosted infrastructure.
|
||||
|
||||
## Disk Space Checks
|
||||
|
||||
```bash
|
||||
# Check root filesystem
|
||||
df -h / | awk 'NR==2 {print $5}'
|
||||
|
||||
# Check Docker data directory
|
||||
df -h /var/lib/docker | awk 'NR==2 {print $5}'
|
||||
|
||||
# Docker-specific disk usage
|
||||
docker system df
|
||||
```
|
||||
|
||||
| Threshold | Status |
|
||||
|-----------|--------|
|
||||
| <70% used | OK |
|
||||
| 70-85% used | Warning - consider pruning |
|
||||
| >85% used | Critical - prune before deploying |
|
||||
|
||||
Pruning commands:
|
||||
```bash
|
||||
docker system prune -f # Remove stopped containers, unused networks
|
||||
docker image prune -a -f # Remove unused images
|
||||
docker volume prune -f # Remove unused volumes (CAUTION: data loss)
|
||||
```
|
||||
|
||||
## Memory Checks
|
||||
|
||||
```bash
|
||||
free -m | awk 'NR==2 {printf "Total: %sMB, Used: %sMB, Available: %sMB\n", $2, $3, $7}'
|
||||
```
|
||||
|
||||
| Available Memory | Status |
|
||||
|-----------------|--------|
|
||||
| >512MB | OK |
|
||||
| 256-512MB | Warning - may be tight |
|
||||
| <256MB | Critical - deployment may OOM |
|
||||
|
||||
## Port Availability
|
||||
|
||||
```bash
|
||||
# Check if a specific port is in use
|
||||
ss -tlnp | grep :<PORT>
|
||||
|
||||
# List all listening ports
|
||||
ss -tlnp
|
||||
```
|
||||
|
||||
If a port is occupied:
|
||||
1. Identify the process: `ss -tlnp | grep :<port>` shows PID
|
||||
2. Check if it is the same service being updated (expected)
|
||||
3. If it is a different service, flag as Critical conflict
|
||||
|
||||
## DNS Resolution
|
||||
|
||||
```bash
|
||||
# Check if subdomain resolves
|
||||
nslookup <subdomain>.<hostname>
|
||||
|
||||
# Check /etc/hosts for local resolution
|
||||
grep <subdomain> /etc/hosts
|
||||
```
|
||||
|
||||
For `.hotport` subdomains, DNS is resolved via router hosts file or `/etc/hosts`.
|
||||
|
||||
## Docker Daemon Status
|
||||
|
||||
```bash
|
||||
# Check Docker is running
|
||||
docker info > /dev/null 2>&1 && echo "OK" || echo "FAIL"
|
||||
|
||||
# Check Docker version
|
||||
docker version --format '{{.Server.Version}}'
|
||||
|
||||
# Check Docker Compose
|
||||
docker compose version
|
||||
```
|
||||
|
||||
## Image Pull Verification
|
||||
|
||||
```bash
|
||||
# Check if image exists for target architecture
|
||||
docker manifest inspect <image>:<tag> 2>/dev/null
|
||||
|
||||
# Check available architectures
|
||||
docker manifest inspect <image>:<tag> | grep architecture
|
||||
```
|
||||
|
||||
For Raspberry Pi, required architecture is `arm64` or `arm/v8`.
|
||||
|
||||
## SSL Certificate Checks
|
||||
|
||||
```bash
|
||||
# Check certificate expiry (for HTTPS services)
|
||||
echo | openssl s_client -servername <domain> -connect <domain>:443 2>/dev/null | openssl x509 -noout -dates
|
||||
```
|
||||
|
||||
## Temperature (Raspberry Pi)
|
||||
|
||||
```bash
|
||||
vcgencmd measure_temp
|
||||
# or
|
||||
cat /sys/class/thermal/thermal_zone0/temp # Divide by 1000 for Celsius
|
||||
```
|
||||
|
||||
| Temperature | Status |
|
||||
|-------------|--------|
|
||||
| <60C | OK |
|
||||
| 60-70C | Warning - fan should be active |
|
||||
| >70C | Critical - may throttle |
|
||||
136
plugins/ops-deploy-pipeline/skills/rollback-patterns.md
Normal file
136
plugins/ops-deploy-pipeline/skills/rollback-patterns.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Rollback Patterns Skill
|
||||
|
||||
Strategies for reverting deployments safely with minimal data loss and downtime.
|
||||
|
||||
## Strategy: Recreate (Default)
|
||||
|
||||
Simple stop-and-restart with previous configuration.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Backup current state**
|
||||
```bash
|
||||
cp docker-compose.yml docker-compose.yml.bak
|
||||
cp .env .env.bak
|
||||
docker compose images > current-images.txt
|
||||
```
|
||||
|
||||
2. **Backup volumes with data**
|
||||
```bash
|
||||
docker run --rm -v <volume_name>:/data -v $(pwd)/backups:/backup \
|
||||
alpine tar czf /backup/<volume_name>-$(date +%Y%m%d%H%M).tar.gz /data
|
||||
```
|
||||
|
||||
3. **Stop current deployment**
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
4. **Restore previous config**
|
||||
```bash
|
||||
git checkout <previous_commit> -- docker-compose.yml .env
|
||||
```
|
||||
|
||||
5. **Start previous version**
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
6. **Verify health**
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs --tail=20
|
||||
```
|
||||
|
||||
### Estimated Downtime
|
||||
|
||||
- Small stack (1-3 services): 10-30 seconds
|
||||
- Medium stack (4-8 services): 30-60 seconds
|
||||
- Large stack with DB: 1-3 minutes (depends on DB startup)
|
||||
|
||||
## Strategy: Blue-Green
|
||||
|
||||
Zero-downtime rollback by running both versions simultaneously.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Available ports for the alternate deployment
|
||||
- Reverse proxy that can switch upstream targets
|
||||
- No port conflicts between blue and green instances
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Start previous version on alternate ports**
|
||||
- Modify docker-compose to use different host ports
|
||||
- Start with `docker compose -p <stack>-green up -d`
|
||||
|
||||
2. **Verify previous version health**
|
||||
- Hit health endpoints on alternate ports
|
||||
- Confirm service functionality
|
||||
|
||||
3. **Switch reverse proxy**
|
||||
- Update Caddyfile to point to green deployment
|
||||
- Reload Caddy: `docker exec caddy caddy reload --config /etc/caddy/Caddyfile`
|
||||
|
||||
4. **Stop current (blue) version**
|
||||
```bash
|
||||
docker compose -p <stack>-blue down
|
||||
```
|
||||
|
||||
5. **Rename green to primary**
|
||||
- Restore original ports in docker-compose
|
||||
- Recreate with standard project name
|
||||
|
||||
### Estimated Downtime
|
||||
|
||||
- Near zero: Only the Caddy reload (sub-second)
|
||||
|
||||
## Database Rollback Considerations
|
||||
|
||||
### Safe (Reversible)
|
||||
|
||||
- Data inserts only (can delete new rows)
|
||||
- No schema changes
|
||||
- Configuration changes in env vars
|
||||
|
||||
### Dangerous (May Cause Data Loss)
|
||||
|
||||
- Schema migrations that drop columns
|
||||
- Data transformations (one-way)
|
||||
- Index changes on large tables
|
||||
|
||||
### Mitigation
|
||||
|
||||
1. Always backup database volume before rollback
|
||||
2. Check for migration files between versions
|
||||
3. If schema changed, may need to restore from backup rather than rollback
|
||||
4. Document migration reversibility in deploy notes
|
||||
|
||||
## Volume Backup and Restore
|
||||
|
||||
### Backup
|
||||
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v <volume>:/data:ro \
|
||||
-v $(pwd)/backups:/backup \
|
||||
alpine tar czf /backup/<volume>.tar.gz -C /data .
|
||||
```
|
||||
|
||||
### Restore
|
||||
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v <volume>:/data \
|
||||
-v $(pwd)/backups:/backup \
|
||||
alpine sh -c "rm -rf /data/* && tar xzf /backup/<volume>.tar.gz -C /data"
|
||||
```
|
||||
|
||||
## Post-Rollback Verification
|
||||
|
||||
1. All containers running: `docker compose ps`
|
||||
2. Health checks passing: `docker compose ps --format json | grep -c healthy`
|
||||
3. Logs clean: `docker compose logs --tail=50 --no-color`
|
||||
4. Application responding: `curl -s http://localhost:<port>/health`
|
||||
5. Data integrity: Spot-check recent records in database
|
||||
27
plugins/ops-deploy-pipeline/skills/visual-header.md
Normal file
27
plugins/ops-deploy-pipeline/skills/visual-header.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Visual Header Skill
|
||||
|
||||
Standard visual header for ops-deploy-pipeline commands.
|
||||
|
||||
## Header Template
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DEPLOY-PIPELINE - [Context] |
|
||||
+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Context Values by Command
|
||||
|
||||
| Command | Context |
|
||||
|---------|---------|
|
||||
| `/deploy setup` | Setup Wizard |
|
||||
| `/deploy generate` | Config Generation |
|
||||
| `/deploy validate` | Config Validation |
|
||||
| `/deploy env` | Environment Management |
|
||||
| `/deploy check` | Pre-Deployment Check |
|
||||
| `/deploy rollback` | Rollback Planning |
|
||||
| Agent mode | Deployment Management |
|
||||
|
||||
## Usage
|
||||
|
||||
Display header at the start of every command response before proceeding with the operation.
|
||||
Reference in New Issue
Block a user