@intentsolutionsio/fairdb-operations-kit 1.0.0

package/commands/fairdb-setup-backup.md

@@ -0,0 +1,420 @@
+---
+name: fairdb-setup-backup
+description: Configure pgBackRest with Wasabi S3 for automated PostgreSQL backups
+model: sonnet
+---
+
+# FairDB pgBackRest Backup Configuration with Wasabi S3
+
+You are configuring pgBackRest with Wasabi S3 storage for automated PostgreSQL backups. Follow SOP-003 precisely.
+
+## Prerequisites Check
+
+Verify before starting:
+1. PostgreSQL 16 is installed and running
+2. Wasabi S3 account is active with bucket created
+3. AWS CLI credentials are available
+4. At least 50GB free disk space for local backups
+
+## Step 1: Install pgBackRest
+
+```bash
+# Add pgBackRest repository
+sudo apt-get install -y software-properties-common
+sudo add-apt-repository -y ppa:pgbackrest/backrest
+sudo apt-get update
+
+# Install pgBackRest
+sudo apt-get install -y pgbackrest
+
+# Verify installation
+pgbackrest version
+```
+
+## Step 2: Configure Wasabi S3 Credentials
+
+```bash
+# Create pgBackRest configuration directory
+sudo mkdir -p /etc/pgbackrest
+sudo mkdir -p /var/lib/pgbackrest
+sudo mkdir -p /var/log/pgbackrest
+sudo mkdir -p /var/spool/pgbackrest
+
+# Set ownership
+sudo chown -R postgres:postgres /var/lib/pgbackrest
+sudo chown -R postgres:postgres /var/log/pgbackrest
+sudo chown -R postgres:postgres /var/spool/pgbackrest
+
+# Store Wasabi credentials (secure these!)
+export WASABI_ACCESS_KEY="YOUR_WASABI_ACCESS_KEY"
+export WASABI_SECRET_KEY="YOUR_WASABI_SECRET_KEY"
+export WASABI_BUCKET="fairdb-backups"
+export WASABI_REGION="us-east-1"  # Or your Wasabi region
+export WASABI_ENDPOINT="s3.us-east-1.wasabisys.com"  # Adjust for your region
+```
+
+## Step 3: Create pgBackRest Configuration
+
+```bash
+# Create main configuration file
+sudo tee /etc/pgbackrest/pgbackrest.conf << EOF
+[global]
+# General Options
+process-max=4
+log-level-console=info
+log-level-file=detail
+start-fast=y
+stop-auto=y
+archive-async=y
+archive-push-queue-max=4GB
+spool-path=/var/spool/pgbackrest
+
+# S3 Repository Configuration
+repo1-type=s3
+repo1-s3-endpoint=${WASABI_ENDPOINT}
+repo1-s3-bucket=${WASABI_BUCKET}
+repo1-s3-region=${WASABI_REGION}
+repo1-s3-key=${WASABI_ACCESS_KEY}
+repo1-s3-key-secret=${WASABI_SECRET_KEY}
+repo1-path=/pgbackrest
+repo1-retention-full=4
+repo1-retention-diff=12
+repo1-retention-archive=30
+repo1-cipher-type=aes-256-cbc
+repo1-cipher-pass=CHANGE_THIS_PASSPHRASE
+
+# Local Repository (for faster restores)
+repo2-type=posix
+repo2-path=/var/lib/pgbackrest
+repo2-retention-full=2
+repo2-retention-diff=6
+
+[fairdb]
+# PostgreSQL Configuration
+pg1-path=/var/lib/postgresql/16/main
+pg1-port=5432
+pg1-user=postgres
+
+# Archive Configuration
+archive-timeout=60
+archive-check=y
+backup-standby=n
+
+# Backup Options
+compress-type=lz4
+compress-level=3
+backup-user=backup_user
+delta=y
+process-max=2
+EOF
+
+# Secure the configuration file
+sudo chmod 640 /etc/pgbackrest/pgbackrest.conf
+sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf
+```
+
+## Step 4: Configure PostgreSQL for pgBackRest
+
+```bash
+# Update PostgreSQL configuration
+sudo tee -a /etc/postgresql/16/main/postgresql.conf << 'EOF'
+
+# pgBackRest Archive Configuration
+archive_mode = on
+archive_command = 'pgbackrest --stanza=fairdb archive-push %p'
+archive_timeout = 60
+max_wal_senders = 3
+wal_level = replica
+wal_log_hints = on
+EOF
+
+# Restart PostgreSQL
+sudo systemctl restart postgresql
+```
+
+## Step 5: Initialize Backup Stanza
+
+```bash
+# Create the stanza
+sudo -u postgres pgbackrest --stanza=fairdb stanza-create
+
+# Verify stanza
+sudo -u postgres pgbackrest --stanza=fairdb check
+```
+
+## Step 6: Create Backup Scripts
+
+```bash
+# Full backup script
+sudo tee /opt/fairdb/scripts/backup-full.sh << 'EOF'
+#!/bin/bash
+set -e
+
+LOG_FILE="/var/log/fairdb/backup-full-$(date +%Y%m%d-%H%M%S).log"
+echo "Starting full backup at $(date)" | tee -a $LOG_FILE
+
+# Perform full backup to both repositories
+sudo -u postgres pgbackrest --stanza=fairdb --type=full --repo=1 backup 2>&1 | tee -a $LOG_FILE
+sudo -u postgres pgbackrest --stanza=fairdb --type=full --repo=2 backup 2>&1 | tee -a $LOG_FILE
+
+# Verify backup
+sudo -u postgres pgbackrest --stanza=fairdb --repo=1 info 2>&1 | tee -a $LOG_FILE
+
+echo "Full backup completed at $(date)" | tee -a $LOG_FILE
+
+# Send notification (implement webhook/email here)
+curl -X POST $FAIRDB_MONITORING_WEBHOOK \
+  -H 'Content-Type: application/json' \
+  -d "{\"text\":\"FairDB full backup completed successfully\"}" 2>/dev/null || true
+EOF
+
+# Incremental backup script
+sudo tee /opt/fairdb/scripts/backup-incremental.sh << 'EOF'
+#!/bin/bash
+set -e
+
+LOG_FILE="/var/log/fairdb/backup-incr-$(date +%Y%m%d-%H%M%S).log"
+echo "Starting incremental backup at $(date)" | tee -a $LOG_FILE
+
+# Perform incremental backup
+sudo -u postgres pgbackrest --stanza=fairdb --type=incr --repo=1 backup 2>&1 | tee -a $LOG_FILE
+
+echo "Incremental backup completed at $(date)" | tee -a $LOG_FILE
+EOF
+
+# Differential backup script
+sudo tee /opt/fairdb/scripts/backup-differential.sh << 'EOF'
+#!/bin/bash
+set -e
+
+LOG_FILE="/var/log/fairdb/backup-diff-$(date +%Y%m%d-%H%M%S).log"
+echo "Starting differential backup at $(date)" | tee -a $LOG_FILE
+
+# Perform differential backup
+sudo -u postgres pgbackrest --stanza=fairdb --type=diff --repo=1 backup 2>&1 | tee -a $LOG_FILE
+
+echo "Differential backup completed at $(date)" | tee -a $LOG_FILE
+EOF
+
+# Make scripts executable
+sudo chmod +x /opt/fairdb/scripts/backup-*.sh
+```
+
+## Step 7: Schedule Automated Backups
+
+```bash
+# Add to root's crontab for automated backups
+cat << 'EOF' | sudo tee /etc/cron.d/fairdb-backups
+# FairDB Automated Backup Schedule
+SHELL=/bin/bash
+PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
+
+# Weekly full backup (Sunday 2 AM)
+0 2 * * 0 root /opt/fairdb/scripts/backup-full.sh
+
+# Daily differential backup (Mon-Sat 2 AM)
+0 2 * * 1-6 root /opt/fairdb/scripts/backup-differential.sh
+
+# Hourly incremental backup (business hours)
+0 9-18 * * 1-5 root /opt/fairdb/scripts/backup-incremental.sh
+
+# Backup verification (daily at 5 AM)
+0 5 * * * postgres pgbackrest --stanza=fairdb --repo=1 check
+
+# Archive expiration (daily at 3 AM)
+0 3 * * * postgres pgbackrest --stanza=fairdb --repo=1 expire
+EOF
+```
+
+## Step 8: Create Restore Procedures
+
+```bash
+# Point-in-time recovery script
+sudo tee /opt/fairdb/scripts/restore-pitr.sh << 'EOF'
+#!/bin/bash
+# FairDB Point-in-Time Recovery Script
+
+if [ $# -ne 1 ]; then
+    echo "Usage: $0 'YYYY-MM-DD HH:MM:SS'"
+    exit 1
+fi
+
+TARGET_TIME="$1"
+BACKUP_PATH="/var/lib/postgresql/16/main"
+
+echo "WARNING: This will restore the database to $TARGET_TIME"
+echo "Current data will be LOST. Continue? (yes/no)"
+read CONFIRM
+
+if [ "$CONFIRM" != "yes" ]; then
+    echo "Restore cancelled"
+    exit 1
+fi
+
+# Stop PostgreSQL
+sudo systemctl stop postgresql
+
+# Clear data directory
+sudo rm -rf ${BACKUP_PATH}/*
+
+# Restore to target time
+sudo -u postgres pgbackrest --stanza=fairdb \
+    --type=time \
+    --target="$TARGET_TIME" \
+    --target-action=promote \
+    restore
+
+# Start PostgreSQL
+sudo systemctl start postgresql
+
+echo "Restore completed. Verify data integrity."
+EOF
+
+sudo chmod +x /opt/fairdb/scripts/restore-pitr.sh
+```
+
+## Step 9: Test Backup and Restore
+
+```bash
+# Perform test backup
+sudo -u postgres pgbackrest --stanza=fairdb --type=full backup
+
+# Check backup info
+sudo -u postgres pgbackrest --stanza=fairdb info
+
+# List backups
+sudo -u postgres pgbackrest --stanza=fairdb info --output=json
+
+# Test restore to alternate location
+sudo mkdir -p /tmp/pgbackrest-test
+sudo chown postgres:postgres /tmp/pgbackrest-test
+sudo -u postgres pgbackrest --stanza=fairdb \
+    --pg1-path=/tmp/pgbackrest-test \
+    --type=latest \
+    restore
+```
+
+## Step 10: Monitor Backup Health
+
+```bash
+# Create monitoring script
+sudo tee /opt/fairdb/scripts/check-backup-health.sh << 'EOF'
+#!/bin/bash
+# FairDB Backup Health Check
+
+# Check last backup time
+LAST_BACKUP=$(sudo -u postgres pgbackrest --stanza=fairdb info --output=json | \
+    jq -r '.[] | .backup[-1].timestamp.stop')
+
+# Convert to seconds
+LAST_BACKUP_EPOCH=$(date -d "$LAST_BACKUP" +%s)
+CURRENT_EPOCH=$(date +%s)
+HOURS_AGO=$(( ($CURRENT_EPOCH - $LAST_BACKUP_EPOCH) / 3600 ))
+
+# Alert if backup is older than 25 hours
+if [ $HOURS_AGO -gt 25 ]; then
+    echo "ALERT: Last backup was $HOURS_AGO hours ago!"
+    # Send alert (implement notification here)
+    exit 1
+fi
+
+echo "Backup health OK - last backup $HOURS_AGO hours ago"
+
+# Check S3 connectivity
+aws s3 ls s3://${WASABI_BUCKET}/pgbackrest/ \
+    --endpoint-url=https://${WASABI_ENDPOINT} > /dev/null 2>&1
+if [ $? -ne 0 ]; then
+    echo "ALERT: Cannot connect to Wasabi S3!"
+    exit 1
+fi
+
+echo "S3 connectivity OK"
+EOF
+
+sudo chmod +x /opt/fairdb/scripts/check-backup-health.sh
+
+# Add to monitoring cron
+echo "*/30 * * * * root /opt/fairdb/scripts/check-backup-health.sh" | \
+    sudo tee -a /etc/cron.d/fairdb-monitoring
+```
+
+## Step 11: Document Backup Configuration
+
+```bash
+cat > /opt/fairdb/configs/backup-info.txt << EOF
+FairDB Backup Configuration
+===========================
+Backup Solution: pgBackRest
+Primary Repository: Wasabi S3 (${WASABI_BUCKET})
+Secondary Repository: Local (/var/lib/pgbackrest)
+Stanza Name: fairdb
+Encryption: AES-256-CBC
+
+Retention Policy:
+- Full Backups: 4 (S3), 2 (Local)
+- Differential: 12 (S3), 6 (Local)
+- WAL Archives: 30 days
+
+Schedule:
+- Full: Weekly (Sunday 2 AM)
+- Differential: Daily (Mon-Sat 2 AM)
+- Incremental: Hourly (9 AM - 6 PM weekdays)
+
+Restore Procedures:
+- Latest: pgbackrest --stanza=fairdb restore
+- PITR: /opt/fairdb/scripts/restore-pitr.sh 'YYYY-MM-DD HH:MM:SS'
+
+Monitoring:
+- Health checks: Every 30 minutes
+- Verification: Daily at 5 AM
+- Expiration: Daily at 3 AM
+EOF
+```
+
+## Verification Checklist
+
+Confirm these items:
+- [ ] pgBackRest installed and configured
+- [ ] Wasabi S3 credentials configured
+- [ ] Stanza created and verified
+- [ ] PostgreSQL archive_command configured
+- [ ] Backup scripts created and executable
+- [ ] Automated schedule configured
+- [ ] Test backup successful
+- [ ] Test restore successful
+- [ ] Monitoring scripts in place
+- [ ] Documentation complete
+
+## Security Notes
+
+- Store Wasabi credentials securely (use AWS Secrets Manager in production)
+- Encrypt backup repository with strong passphrase
+- Regularly test restore procedures
+- Monitor backup logs for failures
+- Keep pgBackRest updated
+
+## Output Summary
+
+Provide the user with:
+1. Backup stanza status: `pgbackrest --stanza=fairdb info`
+2. Next full backup time from cron schedule
+3. Location of backup scripts and logs
+4. Restore procedure documentation
+5. Monitoring webhook configuration needed
+
+## Important Commands
+
+```bash
+# Manual backup commands
+sudo -u postgres pgbackrest --stanza=fairdb --type=full backup      # Full
+sudo -u postgres pgbackrest --stanza=fairdb --type=diff backup      # Differential
+sudo -u postgres pgbackrest --stanza=fairdb --type=incr backup      # Incremental
+
+# Check backup status
+sudo -u postgres pgbackrest --stanza=fairdb info
+sudo -u postgres pgbackrest --stanza=fairdb check
+
+# Restore commands
+sudo -u postgres pgbackrest --stanza=fairdb restore                 # Latest
+sudo -u postgres pgbackrest --stanza=fairdb --type=time --target="2024-01-01 12:00:00" restore  # PITR
+```

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@intentsolutionsio/fairdb-operations-kit",
+  "version": "1.0.0",
+  "description": "Complete operations kit for FairDB PostgreSQL as a Service - VPS setup, PostgreSQL management, customer provisioning, monitoring, and backup automation",
+  "keywords": [
+    "fairdb",
+    "postgresql",
+    "database",
+    "saas",
+    "operations",
+    "devops",
+    "backup",
+    "monitoring",
+    "vps",
+    "contabo",
+    "wasabi",
+    "pgbackrest",
+    "automation",
+    "claude-code",
+    "claude-plugin",
+    "tonsofskills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremylongshore/claude-code-plugins-plus-skills.git",
+    "directory": "plugins/devops/fairdb-operations-kit"
+  },
+  "homepage": "https://tonsofskills.com/plugins/fairdb-operations-kit",
+  "bugs": "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "jeremy@intentsolutions.io"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "commands",
+    "agents"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"console.log(\\\"\\\\n→ This npm package is a tracking/proof artifact. Install the plugin via:\\\\n  ccpi install fairdb-operations-kit\\\\n  or /plugin install fairdb-operations-kit@claude-code-plugins-plus in Claude Code\\\\n\\\")\""
+  }
+}

package/skills/fairdb-backup-manager/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: fairdb-backup-manager
+description: |
+  Manage use when you need to work with backup and recovery.
+  This skill provides backup automation and disaster recovery with comprehensive guidance and automation.
+  Trigger with phrases like "create backups", "automate backups",
+  or "implement disaster recovery".
+
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(tar:*), Bash(rsync:*), Bash(aws:s3:*)
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [devops, backup, disaster-recovery]
+---
+# FairDB Backup Manager
+
+## Overview
+
+Automate backup and recovery operations for FairDB database instances. Generate backup scripts, configure retention policies, schedule automated backups to local storage or S3, and produce tested restore procedures with integrity verification.
+
+## Prerequisites
+
+- FairDB instance running and accessible with admin credentials
+- `tar` and `rsync` installed for file-level backups
+- AWS CLI configured with `s3:PutObject` and `s3:GetObject` permissions (if using S3 as backup target)
+- Sufficient storage at backup destination (2-3x database size for rotation)
+- Cron or systemd timer access for scheduling
+- Test environment available for restore verification
+
+## Instructions
+
+1. Assess the FairDB instance: identify data directory location, database size, and write throughput
+2. Select backup method: logical dump for portability, filesystem snapshot for speed, or continuous archiving for minimal RPO
+3. Generate backup script with lock acquisition, data export, compression (`tar czf`), and checksum generation
+4. Configure S3 upload with server-side encryption (`aws s3 cp --sse aws:kms`) for off-site copies
+5. Set up retention policy: keep hourly backups for 24 hours, daily for 7 days, weekly for 4 weeks, monthly for 12 months
+6. Create cleanup script to purge expired backups according to retention schedule
+7. Schedule backups via cron with proper logging to `/var/log/fairdb-backup.log`
+8. Generate restore procedure: download from S3, verify checksum, decompress, and import with validation query
+9. Test restore procedure in a staging environment and document the time-to-recovery
+
+## Output
+
+- Backup shell script with logging, locking, compression, and S3 upload
+- Restore shell script with checksum verification and data validation
+- Cron schedule entries or systemd timer units
+- Retention cleanup script
+- S3 lifecycle policy configuration for long-term archive tiering
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|---------|
+| `Backup lock acquisition failed` | Another backup or maintenance process is running | Check for stale lock files; implement timeout-based lock with `flock` |
+| `tar: Cannot open: No space left on device` | Local backup destination full | Run retention cleanup; check disk usage with `df -h`; increase volume size |
+| `aws s3 cp: upload failed` | Network issue or expired AWS credentials | Retry with `--retry 3`; refresh credentials; check S3 bucket permissions |
+| `Restore failed: checksum mismatch` | Backup file corrupted during transfer or storage | Re-download from S3; verify S3 object integrity; use a different backup copy |
+| `Database inconsistent after restore` | Backup taken during active write without lock | Ensure backup script acquires a consistent snapshot lock before export |
+
+## Examples
+
+- "Create an automated nightly backup for the FairDB production instance, compressed and uploaded to S3 with KMS encryption and 30-day retention."
+- "Generate a restore runbook that pulls the latest backup from S3, verifies integrity, and restores to a staging instance for validation."
+- "Set up backup monitoring that alerts via Slack if a backup job fails or if no successful backup exists within the last 25 hours."
+
+## Resources
+
+- AWS S3 CLI: https://docs.aws.amazon.com/cli/latest/reference/s3/
+- rsync documentation: https://rsync.samba.org/documentation.html
+- Backup automation patterns: https://www.veeam.com/blog/321-backup-rule.html
+- Linux cron scheduling: https://crontab.guru/

package/skills/fairdb-backup-manager/assets/README.md

@@ -0,0 +1,26 @@
+# Skill Assets
+
+This directory contains static assets used by this skill.
+
+## Purpose
+
+Assets can include:
+- Configuration files (JSON, YAML)
+- Data files
+- Templates
+- Schemas
+- Test fixtures
+
+## Guidelines
+
+- Keep assets small and focused
+- Document asset purpose and format
+- Use standard file formats
+- Include schema validation where applicable
+
+## Common Asset Types
+
+- **config.json** - Configuration templates
+- **schema.json** - JSON schemas
+- **template.yaml** - YAML templates
+- **test-data.json** - Test fixtures

package/skills/fairdb-backup-manager/references/README.md

@@ -0,0 +1,26 @@
+# Skill References
+
+This directory contains reference materials that enhance this skill's capabilities.
+
+## Purpose
+
+References can include:
+- Code examples
+- Style guides
+- Best practices documentation
+- Template files
+- Configuration examples
+
+## Guidelines
+
+- Keep references concise and actionable
+- Use markdown for documentation
+- Include clear examples
+- Link to external resources when appropriate
+
+## Types of References
+
+- **examples.md** - Usage examples
+- **style-guide.md** - Coding standards
+- **templates/** - Reusable templates
+- **patterns.md** - Design patterns

package/skills/fairdb-backup-manager/scripts/README.md

@@ -0,0 +1,24 @@
+# Skill Scripts
+
+This directory contains optional helper scripts that support this skill's functionality.
+
+## Purpose
+
+Scripts here can be:
+- Referenced by the skill for automation
+- Used as examples for users
+- Executed during skill activation
+
+## Guidelines
+
+- All scripts should be well-documented
+- Include usage examples in comments
+- Make scripts executable (`chmod +x`)
+- Use `#!/bin/bash` or `#!/usr/bin/env python3` shebangs
+
+## Adding Scripts
+
+1. Create script file (e.g., `analyze.sh`, `process.py`)
+2. Add documentation header
+3. Make executable: `chmod +x script-name.sh`
+4. Test thoroughly before committing

package/skills/skill-adapter/assets/README.md

@@ -0,0 +1,4 @@
+# Assets
+
+Bundled resources for fairdb-operations-kit skill
+

package/skills/skill-adapter/assets/config-template.json

@@ -0,0 +1,32 @@
+{
+  "skill": {
+    "name": "skill-name",
+    "version": "1.0.0",
+    "enabled": true,
+    "settings": {
+      "verbose": false,
+      "autoActivate": true,
+      "toolRestrictions": true
+    }
+  },
+  "triggers": {
+    "keywords": [
+      "example-trigger-1",
+      "example-trigger-2"
+    ],
+    "patterns": []
+  },
+  "tools": {
+    "allowed": [
+      "Read",
+      "Grep",
+      "Bash"
+    ],
+    "restricted": []
+  },
+  "metadata": {
+    "author": "Plugin Author",
+    "category": "general",
+    "tags": []
+  }
+}

package/skills/skill-adapter/assets/skill-schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Skill Configuration",
+  "type": "object",
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "maxLength": 64,
+      "description": "Skill identifier (lowercase, hyphens only)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "What the skill does and when to use it"
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Comma-separated list of allowed tools"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (x.y.z)"
+    }
+  }
+}