Agent-Skills.md

Agent Skills: Caddy Server Management Skill

|

UncategorizedID: terraphim/codex-skills/caddy

Repository

terraphim/codex-skills
terraphimLicense: Apache-2.0
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/terraphim/codex-skills/tree/HEAD/skills/caddy

Skill Files

Browse the full folder contents for caddy.

Download Skill

Loading file tree…

skills/caddy/SKILL.md

Skill Metadata

Name
caddy
Description
|

Caddy Server Management Skill

Version: 1.0.0 Author: Claude Code Purpose: Comprehensive Caddy web server management across multiple environments

Overview and Purpose

This skill provides enterprise-grade Caddy server management across local development and production environments. It handles:

  • Multi-server operations: Manage Caddy on local (macOS), bigbox (production), and registry (production) servers
  • Zero-downtime deployments: Graceful reloads with automatic validation
  • Secret management: Integrated 1Password support for secure credential handling
  • Custom builds: Build Caddy with required plugins (security, cloudflare, cgi, tlsredis)
  • Systemd management: Proper service lifecycle management
  • Log analysis: Parse and analyze JSON logs for troubleshooting
  • Pattern library: Ready-to-use configurations for common use cases

Critical Mandates:

  • Zero-Downtime: Always use graceful reloads, never kill processes
  • Validation-First: Mandatory syntax validation before any deployment
  • Secret Safety: Never display plaintext secrets, always use 1Password
  • Backup-First: Always create timestamped backups before modifications

Prerequisites

Required

  1. Server Access

    • Local: macOS with mdfind available
    • bigbox: SSH access configured (ssh bigbox)
    • registry: SSH access configured (ssh registry)

  2. Caddy Installation

    # Check Caddy on servers
ssh bigbox "which caddy && caddy version"
ssh registry "which caddy && caddy version"

  3. 1Password CLI (for secret management)

    # Verify 1Password skill is available
which op && op --version
# See: ~/.claude/skills/1password-secrets.md

  4. Systemd (on production servers)

    # Verify systemd available
ssh bigbox "systemctl --version"
ssh registry "systemctl --version"

Optional

  • xcaddy: For building custom Caddy binaries
  • jq: For JSON log parsing (usually available)
  • Go toolchain: Required for xcaddy builds

Server Configuration

This skill operates across 3 servers with different characteristics:

Local (Development)

  • Platform: macOS
  • Search: mdfind (fast Spotlight search)
  • Caddy: Not running (development configs only)
  • Use Cases: Testing configs, pattern development

bigbox (Production - Migration Required)

  • Platform: Linux
  • Caddy Version: v2.6.4 (custom build)
  • Binary: /home/alex/caddy_terraphim/caddy
  • Active Config: /home/alex/caddy_terraphim/conf/Caddyfile_auth
  • Status: Currently running in tmux (needs systemd migration)
  • Plugins: caddy-security, caddy-tlsredis, cloudflare, cgi
  • ⚠️ Action Required: Migrate to systemd + 1Password

registry (Production - Best Practice)

  • Platform: Linux
  • Caddy Version: v2.10.2 (standard)
  • Binary: /usr/bin/caddy
  • Active Config: /etc/caddy/Caddyfile
  • Status: Properly managed via systemd
  • ✓ Reference: Clean 41-line config with snippets

Server configuration details: ~/.docs/caddy-skill/servers.json

Workflow 1: Discover Caddyfiles

Purpose: Find all Caddyfiles across servers quickly (<5 seconds).

When to Use

  • Auditing Caddyfile locations
  • Before making configuration changes
  • Identifying active vs backup configs
  • Searching for specific configuration patterns

How It Works

  1. User specifies server(s): local, bigbox, registry, or all
  2. Skill loads server configuration from servers.json
  3. Skill executes fast search command (mdfind locally, find remotely)
  4. Skill filters out backup files (.backup., *.bak)
  5. Skill identifies active configuration (from systemd service)
  6. Skill displays sorted results (active first, then by modification time)

Usage Patterns

Pattern 1: Find on Single Server

User: "Find all Caddyfiles on bigbox"

Assistant Process:
1. Load bigbox config from servers.json
2. Execute via SSH: find /home/alex/caddy_terraphim /home/alex/infrastructure -name 'Caddyfile*' ! -name '*.backup.*' -type f
3. Identify active config from systemd service
4. Sort results (active first)
5. Display with metadata

Example Output:
Found 14 Caddyfiles on bigbox:

ACTIVE:
  ✓ /home/alex/caddy_terraphim/conf/Caddyfile_auth (324 lines, modified 2 days ago)
    Service: caddy-terraphim (currently tmux-based)
    Status: Running (PID 24566, 35+ days uptime)

INACTIVE:
  /home/alex/infrastructure/atomic-server-turso/Caddyfile.enhanced (112 lines)
  /home/alex/infrastructure/atomic-server-turso/Caddyfile.production (86 lines)
  /home/alex/caddy_terraphim/conf/Caddyfile_auth2 (63 lines)
  ... (10 more files)

💡 Tip: Use 'Validate' workflow to check syntax before deployment

Pattern 2: Find on All Servers

User: "Find all Caddyfiles across all servers"

Assistant Process:
1. Load all server configs
2. Execute searches in parallel (local + SSH to bigbox + SSH to registry)
3. Aggregate results by server
4. Mark active configs
5. Display grouped by server

Example Output:
Found 28 Caddyfiles across 3 servers:

LOCAL (14 files):
  /Users/alex/projects/zestic-ai/charm/charm-impact/infrastructure/Caddyfile.production (167 lines)
  /Users/alex/projects/zestic-ai/charm/charm-impact/infrastructure/Caddyfile_docker (31 lines)
  ... (12 more)

BIGBOX (14 files):
  ✓ ACTIVE: /home/alex/caddy_terraphim/conf/Caddyfile_auth (324 lines)
  /home/alex/infrastructure/atomic-server-turso/Caddyfile.enhanced (112 lines)
  ... (12 more)

REGISTRY (1 file):
  ✓ ACTIVE: /etc/caddy/Caddyfile (41 lines)

⚠️  bigbox: Migration to systemd + 1Password recommended
✓  registry: Properly configured (reference implementation)

Pattern 3: Search with Pattern

User: "Find Caddyfiles with 'auth' in the name on bigbox"

Assistant Process:
1. Load bigbox config
2. Add pattern filter: -name '*auth*'
3. Execute search
4. Display results

Example Output:
Found 3 Caddyfiles matching 'auth' on bigbox:
  ✓ /home/alex/caddy_terraphim/conf/Caddyfile_auth (ACTIVE, 324 lines)
  /home/alex/caddy_terraphim/conf/Caddyfile_auth2 (63 lines)
  /home/alex/caddy_terraphim/conf/Caddyfile_localauth (123 lines)

Implementation Details

Step 1: Load Server Configuration

# Read servers.json
cat ~/.docs/caddy-skill/servers.json | jq -r '.servers.bigbox'

Step 2: Execute Search

For local (macOS):

mdfind -name Caddyfile | grep -v ".backup\." | head -20

For remote servers (Linux):

ssh bigbox "find /home/alex/caddy_terraphim /home/alex/infrastructure \
  -name 'Caddyfile*' ! -name '*.backup.*' ! -name '*~' -type f"

Step 3: Identify Active Configuration

# Check systemd service for active config
ssh bigbox "systemctl show caddy-terraphim --property=ExecStart"
# Parse output to extract config path

Step 4: Get File Metadata

# For each file, get line count and modification time
ssh bigbox "wc -l /path/to/Caddyfile; stat -c %y /path/to/Caddyfile"

Step 5: Sort and Display

  • Active configs first
  • Then by modification time (newest first)
  • Show metadata: lines, modification date, status

Performance Optimization

  • Local search: mdfind is instant (Spotlight index)
  • Remote search: find with path limits (<5 seconds)
  • Parallel execution: Search all servers concurrently
  • Caching: Results cached for 60 seconds (optional)

Error Handling

SSH Connection Failed:

✗ Error: Cannot connect to bigbox
  Check: ssh bigbox "echo test"
  Solution: Verify SSH config and connectivity

No Caddyfiles Found:

ℹ No Caddyfiles found on local
  Searched paths: /Users/alex/projects/
  Tip: Caddyfiles may be in different locations

Permission Denied:

✗ Error: Permission denied accessing /etc/caddy/Caddyfile
  Solution: Add sudo to remote command or adjust permissions

Security Guarantees

✓ Read-only operations (no file modifications) ✓ SSH uses existing configuration (no password prompts) ✓ No secrets displayed (even if found in configs) ✓ Respects file permissions (won't force access)

Workflow 2: Validate Configuration

Purpose: Validate Caddyfile syntax before deployment to prevent downtime.

When to Use

  • Before deploying configuration changes
  • After editing Caddyfiles
  • When troubleshooting syntax errors
  • As part of CI/CD pipeline

How It Works

  1. User provides Caddyfile path and server
  2. Skill reads server configuration
  3. Skill executes caddy validate --config <path>
  4. Skill parses validation output for errors
  5. Skill checks for environment variables (coordinates with 1Password skill if needed)
  6. Skill reports results with clear error messages

Usage Patterns

Pattern 1: Validate Single File

User: "Validate /home/alex/caddy_terraphim/conf/Caddyfile_auth on bigbox"

Assistant Process:
1. Load bigbox server config
2. Check Caddy binary exists
3. Execute: ssh bigbox "/home/alex/caddy_terraphim/caddy validate --config /home/alex/caddy_terraphim/conf/Caddyfile_auth"
4. Parse output
5. Check for undefined environment variables
6. Report results

Example Output (Valid):
✓ Configuration is valid
  File: /home/alex/caddy_terraphim/conf/Caddyfile_auth
  Lines: 324
  Binary: /home/alex/caddy_terraphim/caddy (v2.6.4)
  Validation time: 0.8s

Environment variables detected:
  ⚠️  GITHUB_CLIENT_ID (defined in caddy_complete.env)
  ⚠️  GITHUB_CLIENT_SECRET (plaintext in caddy_complete.env)
  ⚠️  JWT_SHARED_KEY (plaintext in caddy_complete.env)

Recommendation: Migrate secrets to 1Password
  See: Workflow "Migrate Secrets" or 1Password skill

Pattern 2: Validate with Errors

Example Output (Invalid):
✗ Configuration has errors

Error 1 (Line 45):
  /home/alex/caddy_terraphim/conf/Caddyfile_auth:45
  parsing Caddyfile tokens: missing closing brace

  Context:
  43: reverse_proxy localhost:3000 {
  44:     header_up X-Real-IP {remote_host}
  45:     # Missing closing brace here
  46:
  47: handle /api {

Fix: Add closing brace after line 44

Error 2 (Line 102):
  Unrecognized directive: 'auth_portal'
  Did you mean: 'authentication portal' ?

Recommendation: Fix these 2 errors before deployment

Pattern 3: Validate Before Deployment

User: "Validate the active Caddyfile on bigbox before I deploy changes"

Assistant Process:
1. Identify active config (Workflow 1)
2. Validate current active config
3. If user modified a file, validate that too
4. Compare and report

Example Output:
✓ Current active config is valid
  File: /home/alex/caddy_terraphim/conf/Caddyfile_auth
  Status: Currently running, no errors in logs

✓ Modified config is valid
  File: /home/alex/caddy_terraphim/conf/Caddyfile_auth
  Changes: 15 lines modified (comparing to last backup)

Validation Summary:
  - Syntax: ✓ Valid
  - Directives: ✓ All recognized
  - Env vars: ⚠️  3 plaintext secrets detected
  - Conflicts: ✓ No port conflicts

Ready for deployment: Yes
Recommendation: Deploy with 'Workflow 4: Deploy Changes'

Implementation Details

Step 1: Check Caddy Binary

# Verify Caddy is available
ssh bigbox "which /home/alex/caddy_terraphim/caddy && /home/alex/caddy_terraphim/caddy version"

Step 2: Execute Validation

# Validate Caddyfile
ssh bigbox "/home/alex/caddy_terraphim/caddy validate --config /path/to/Caddyfile --adapter caddyfile"

Step 3: Parse Output

# Validation successful if exit code 0
# Parse stderr for error messages
# Extract line numbers and error types

Step 4: Check Environment Variables

# Scan Caddyfile for {env.VAR_NAME} or {$VAR_NAME} syntax
grep -oP '\{(env\.)?\$?[A-Z_]+\}' Caddyfile

# Check if variables defined in env file or 1Password template
cat caddy_complete.env | grep "VAR_NAME="

Step 5: Detect Secrets

# Coordinate with 1Password skill to detect plaintext secrets
# See: ~/.claude/skills/1password-secrets.md Workflow 1

Validation Checks

Syntax Validation:

  • Valid Caddyfile format
  • Matching braces and brackets
  • Recognized directives
  • Valid matcher syntax
  • Proper nesting

Semantic Validation:

  • No duplicate site blocks
  • No conflicting matchers
  • Valid port bindings (not in use)
  • Valid upstream addresses
  • Proper TLS configuration

Environment Validation:

  • All referenced variables defined
  • No plaintext secrets (warn if found)
  • Env file readable if specified

Security Validation:

  • Secrets in 1Password (recommended)
  • No exposed credentials
  • Proper TLS configuration
  • Security headers present (recommended)

Error Messages

Syntax Errors:

Line 45: Missing closing brace
  Expected '}' to close block started at line 43

  43: reverse_proxy localhost:3000 {
  44:     header_up X-Real-IP {remote_host}
  45:     # Missing '}'

Directive Errors:

Line 102: Unrecognized directive 'auth_portal'
  Available in module: http.handlers.authentication
  Suggestion: authentication portal myportal
  Documentation: https://caddyserver.com/docs/...

Environment Errors:

Line 15: Undefined environment variable 'API_KEY'
  Referenced as: {env.API_KEY}
  Solution 1: Define in caddy_complete.env
  Solution 2: Migrate to 1Password: op://Vault/Item/api_key

Safety Guarantees

✓ Read-only validation (no file changes) ✓ No service disruption (validation only) ✓ No secret exposure (secrets masked in output) ✓ Detailed error reporting (line numbers, context)

Workflow 3: Format Caddyfile

Purpose: Format Caddyfile for consistent style and readability.

When to Use

  • After manual edits
  • Before committing to version control
  • When adopting team style standards
  • After merging configuration changes

How It Works

  1. User provides Caddyfile path and server
  2. Skill creates timestamped backup
  3. Skill executes caddy fmt --overwrite <path>
  4. Skill validates formatted output
  5. Skill shows diff (before/after) if requested
  6. Skill provides rollback instructions

Usage Pattern

User: "Format /home/alex/caddy_terraphim/conf/Caddyfile_auth on bigbox"

Assistant Process:
1. Load bigbox config
2. Create backup: Caddyfile_auth.backup.20251229_143000
3. Execute: caddy fmt --overwrite Caddyfile_auth
4. Validate formatted file
5. Show summary

Example Output:
✓ Caddyfile formatted successfully
  File: /home/alex/caddy_terraphim/conf/Caddyfile_auth
  Backup: /home/alex/caddy_terraphim/conf/Caddyfile_auth.backup.20251229_143000
  Changes: Indentation normalized, spacing adjusted

Validation: ✓ Formatted file is valid

To rollback:
  ssh bigbox "cp /home/alex/caddy_terraphim/conf/Caddyfile_auth.backup.20251229_143000 \
              /home/alex/caddy_terraphim/conf/Caddyfile_auth"

Recommendation: Review changes before deployment

Implementation Details

Step 1: Create Backup

# Timestamped backup
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
cp Caddyfile_auth Caddyfile_auth.backup.$TIMESTAMP

Step 2: Format

# Execute format with overwrite
caddy fmt --overwrite /path/to/Caddyfile

Step 3: Validate

# Ensure formatting didn't break syntax
caddy validate --config /path/to/Caddyfile

Step 4: Show Diff (Optional)

# Compare before/after
diff -u Caddyfile_auth.backup.$TIMESTAMP Caddyfile_auth

Safety Guarantees

✓ Always creates backup before formatting ✓ Validates after formatting to ensure no breakage ✓ Provides rollback instructions immediately ✓ Never formats active config without confirmation

Workflow 4: Deploy Changes (Graceful Reload)

Purpose: Deploy Caddyfile changes with zero downtime using graceful reload.

When to Use

  • After validating configuration changes
  • Deploying new site configurations
  • Updating TLS settings
  • Modifying reverse proxy rules

How It Works

  1. Pre-deployment checks (validation, service status, secret detection)
  2. Create backup of current config
  3. Detect deployment method (systemd reload or caddy reload API)
  4. Execute graceful reload
  5. Post-deployment verification (service status, logs, endpoint tests)
  6. Automatic rollback on failure

Usage Pattern

User: "Deploy Caddyfile changes to bigbox"

Assistant Process:
1. Pre-deployment Checks:
   ✓ Validate configuration
   ✓ Check service is running
   ⚠️  Detect 3 plaintext secrets (recommend 1Password migration)
   ✓ Create backup

2. Deployment:
   Method: systemd reload (zero-downtime)
   Command: ssh bigbox "systemctl reload caddy-terraphim"
   Status: ✓ Reload initiated

3. Verification:
   ✓ Service status: active (running)
   ✓ No errors in logs (last 50 lines)
   ✓ Test endpoint: https://alpha.truthforge.terraphim.cloud/health → 200 OK
   ✓ Requests dropped during reload: 0

Deployment Summary:
  - Status: ✓ Success
  - Duration: 2.3 seconds
  - Downtime: 0 seconds (graceful reload)
  - Backup: Caddyfile_auth.backup.20251229_143500

⚠️  Recommendation: Migrate secrets to 1Password for enhanced security
    See: 1Password skill or Workflow "Migrate Secrets"

Pre-Deployment Checks

Check 1: Validate Configuration

# Must pass validation
caddy validate --config /path/to/Caddyfile

Check 2: Service Running

# Verify Caddy is running
systemctl is-active caddy-terraphim
# Or check process for tmux-based
ps aux | grep caddy | grep -v grep

Check 3: Detect Secrets

# Scan for plaintext secrets (coordinate with 1Password skill)
# Warn user but don't block deployment

Check 4: Create Backup

# Always backup current active config
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
cp /path/to/Caddyfile /path/to/Caddyfile.backup.$TIMESTAMP

Deployment Methods

Method 1: Systemd Reload (Recommended)

# Graceful reload via systemd
systemctl reload caddy-terraphim

# Benefits:
# - Zero downtime (in-place reload)
# - No dropped connections
# - Automatic rollback on failure
# - Logs in journalctl

Method 2: Caddy Reload API

# Direct reload via Caddy admin API
curl -X POST http://localhost:2019/load \
  -H "Content-Type: application/json" \
  -d @config.json

# Benefits:
# - Finer control
# - Can preview config before apply
# - Works without systemd

Method 3: Signal Reload

# Send USR1 signal (for tmux-based or non-systemd)
kill -USR1 $(cat /var/run/caddy.pid)

# Note: Less reliable, use systemd if possible

Post-Deployment Verification

Step 1: Check Service Status

systemctl status caddy-terraphim --no-pager
# Verify: active (running), no recent errors

Step 2: Check Recent Logs

# Last 50 log lines for errors
journalctl -u caddy-terraphim -n 50 --no-pager | grep -i error

Step 3: Test Endpoints

# Test configured domains
curl -f https://alpha.truthforge.terraphim.cloud/health
curl -f https://ci.terraphim.cloud/health

# Verify: 200 OK responses

Step 4: Check Dropped Requests

# Parse logs for any dropped connections during reload
# Caddy's graceful reload should have 0 drops

Rollback on Failure

If deployment fails (validation error, service won't start, endpoints down):

# Automatic rollback process:
1. Restore backup:
   cp Caddyfile.backup.20251229_143500 Caddyfile

2. Reload with backup config:
   systemctl reload caddy-terraphim

3. Verify rollback successful:
   systemctl status caddy-terraphim
   curl -f https://domain.com/health

4. Report failure details to user with logs

Safety Guarantees

✓ Zero-downtime reloads (graceful, no dropped requests) ✓ Always validates before deployment ✓ Always creates backup before changes ✓ Automatic rollback on failure ✓ Post-deployment verification confirms success

Workflow 5: Check Status

Purpose: Check Caddy service health and current configuration.

Usage Pattern

User: "Check Caddy status on bigbox"

Assistant Process:
1. Query systemd service status
2. Check process details (PID, uptime, memory)
3. Verify listening ports
4. Check recent log entries
5. Test configured endpoints

Example Output:
Caddy Status on bigbox:

Service: caddy-terraphim
  Status: ✓ active (running)
  PID: 24566
  Uptime: 35 days 14 hours
  Memory: 27.6 MB
  User: caddy

Configuration:
  Active: /home/alex/caddy_terraphim/conf/Caddyfile_auth (324 lines)
  Loaded: 3 hours ago
  Last reload: 2 hours ago (successful)

Listening Ports:
  ✓ :80 (HTTP)
  ✓ :443 (HTTPS)

Recent Activity (last 10 minutes):
  - 245 requests processed
  - 0 errors
  - Average response time: 45ms

Domains Configured:
  ✓ alpha.truthforge.terraphim.cloud (responding)
  ✓ ci.terraphim.cloud (responding)
  ✓ logs.terraphim.cloud (responding)

Health: ✓ All systems operational

⚠️  Note: Service running in tmux, migration to systemd recommended

Implementation

# Service status
systemctl status caddy-terraphim

# Process details
ps aux | grep caddy | grep -v grep

# Listening ports
ss -tulpn | grep caddy

# Recent logs
journalctl -u caddy-terraphim --since "10 minutes ago"

# Test endpoints
curl -sf https://domain.com/health

Integration with 1Password Skill

This skill coordinates with the 1Password Secret Management Skill for secure credential handling.

Secret Detection

When scanning Caddyfiles, this skill detects:

  • Environment variable references: {env.VAR_NAME}
  • Plaintext secrets in env files
  • Basic auth credentials
  • API keys and tokens

Then coordinates with 1Password skill (Workflow 1: Detect Secrets) to:

  • Identify secret types
  • Calculate confidence scores
  • Recommend migration to op:// references

Secret Migration

For bigbox migration, this skill will:

  1. Detect plaintext secrets in caddy_complete.env
  2. Use 1Password skill (Workflow 2: Generate Template) to create .env.template
  3. Guide user to create 1Password items
  4. Update systemd service to use op run --no-masking
  5. Verify migration successful

See: ~/.claude/skills/1password-secrets.md for detailed secret management workflows.

Quick Reference

Common Commands

# Discovery
"Find all Caddyfiles on bigbox"
"Find Caddyfiles with 'auth' in name on all servers"

# Validation
"Validate /path/to/Caddyfile on bigbox"
"Validate the active Caddyfile before deployment"

# Format
"Format /path/to/Caddyfile on registry"

# Deploy
"Deploy Caddyfile changes to bigbox"

# Status
"Check Caddy status on registry"

Server Names

  • local: Local development machine (macOS)
  • bigbox: Production server (migration needed)
  • registry: Production server (reference implementation)
  • all: All servers

File Locations

  • Local: /Users/alex/projects/*/infrastructure/Caddyfile*
  • bigbox: /home/alex/caddy_terraphim/conf/Caddyfile_auth (active)
  • registry: /etc/caddy/Caddyfile (active)

Related Skills

  • 1Password Secret Management: ~/.claude/skills/1password-secrets.md
  • Systemd Management: For service lifecycle operations
  • SSH Management: For remote server access

Version History:

  • 1.0.0 (2025-12-29): Initial release with core workflows (Discovery, Validation, Format, Deploy, Status)

Maintainer: Claude Code License: MIT Documentation: This file Server Configuration: ~/.docs/caddy-skill/servers.json Pattern Library: ~/.docs/caddy-skill/patterns/ (coming soon)

Next Workflows Coming Soon:

  • Workflow 6: Build Custom Caddy (xcaddy with plugins)
  • Workflow 7: Analyze Logs (JSON parsing, error detection)
  • Workflow 8: Extract Snippets (DRY principle, pattern identification)
  • Workflow 9: Migrate to Systemd (bigbox migration with 1Password)
  • Workflow 10: Pattern Library (reverse proxy, auth, WebSocket, security headers)