Initial commit

2025-11-29 17:56:41 +08:00
commit 9427ed1eea
40 changed files with 15189 additions and 0 deletions
--- a/skills/hetzner-provisioner/README.md
+++ b/skills/hetzner-provisioner/README.md
@@ -0,0 +1,308 @@
+**Name:** hetzner-provisioner
+**Type:** Infrastructure / DevOps
+**Model:** Claude Sonnet 4.5 (balanced for IaC generation)
+**Status:** Planned
+
+---
+
+## Overview
+
+Automated Hetzner Cloud infrastructure provisioning using Terraform or Pulumi. Generates production-ready IaC code for deploying SaaS applications at $10-15/month instead of $50-100/month on Vercel/AWS.
+
+## When This Skill Activates
+
+**Keywords**: deploy on Hetzner, Hetzner Cloud, budget deployment, cheap hosting, $10/month, cost-effective infrastructure
+
+**Example prompts**:
+- "Deploy my NextJS app on Hetzner"
+- "I want the cheapest possible hosting for my SaaS"
+- "Set up infrastructure on Hetzner Cloud with Postgres"
+- "Deploy for under $15/month"
+
+## What It Generates
+
+### 1. Terraform Configuration
+
+**main.tf**:
+```hcl
+terraform {
+  required_providers {
+    hcloud = {
+      source = "hetznercloud/hcloud"
+      version = "~> 1.45"
+    }
+  }
+}
+
+provider "hcloud" {
+  token = var.hcloud_token
+}
+
+# Server instance
+resource "hcloud_server" "app" {
+  name        = "my-saas-app"
+  server_type = "cx11"
+  image       = "ubuntu-22.04"
+  location    = "nbg1"  # Nuremberg, Germany
+
+  user_data = file("${path.module}/cloud-init.yaml")
+
+  public_net {
+    ipv4_enabled = true
+    ipv6_enabled = true
+  }
+}
+
+# Managed Postgres database
+resource "hcloud_database" "postgres" {
+  name              = "my-saas-db"
+  engine            = "postgresql"
+  version           = "15"
+  size              = "db-1x-small"
+  location          = "nbg1"
+}
+
+# Firewall
+resource "hcloud_firewall" "app" {
+  name = "my-saas-firewall"
+
+  rule {
+    direction = "in"
+    protocol  = "tcp"
+    port      = "80"
+    source_ips = ["0.0.0.0/0", "::/0"]
+  }
+
+  rule {
+    direction = "in"
+    protocol  = "tcp"
+    port      = "443"
+    source_ips = ["0.0.0.0/0", "::/0"]
+  }
+
+  rule {
+    direction = "in"
+    protocol  = "tcp"
+    port      = "22"
+    source_ips = ["0.0.0.0/0", "::/0"]  # Restrict to your IP in production
+  }
+}
+
+# Apply firewall to server
+resource "hcloud_firewall_attachment" "app" {
+  firewall_id = hcloud_firewall.app.id
+  server_ids  = [hcloud_server.app.id]
+}
+
+# Output deployment info
+output "server_ip" {
+  value = hcloud_server.app.ipv4_address
+}
+
+output "database_host" {
+  value = hcloud_database.postgres.host
+}
+
+output "database_port" {
+  value = hcloud_database.postgres.port
+}
+```
+
+### 2. Docker Configuration
+
+**Dockerfile**:
+```dockerfile
+FROM node:20-alpine AS base
+
+# Dependencies
+FROM base AS deps
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+# Builder
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+# Runner
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV production
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT 3000
+
+CMD ["node", "server.js"]
+```
+
+### 3. GitHub Actions CI/CD
+
+**.github/workflows/deploy.yml**:
+```yaml
+name: Deploy to Hetzner
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Terraform Init
+        run: terraform init
+        working-directory: ./terraform
+        env:
+          HCLOUD_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+
+      - name: Terraform Plan
+        run: terraform plan
+        working-directory: ./terraform
+        env:
+          HCLOUD_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+
+      - name: Terraform Apply
+        run: terraform apply -auto-approve
+        working-directory: ./terraform
+        env:
+          HCLOUD_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+
+      - name: Build and Deploy Docker
+        run: |
+          ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} << 'EOF'
+            cd /app
+            git pull
+            docker-compose build
+            docker-compose up -d
+          EOF
+```
+
+### 4. SSL Configuration (Let's Encrypt)
+
+**nginx.conf** (auto-generated):
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+## Cost Breakdown
+
+### Small SaaS (100-1000 users)
+- **CX11** (1 vCPU, 2GB RAM): $5.83/month
+- **Managed Postgres** (2GB): $5.00/month
+- **Storage** (20GB): $0.50/month
+- **SSL** (Let's Encrypt): Free
+- **Total**: ~$11.33/month
+
+### Medium SaaS (1000-10000 users)
+- **CX21** (2 vCPU, 4GB RAM): $6.90/month
+- **Managed Postgres** (4GB): $10.00/month
+- **Storage** (40GB): $1.00/month
+- **Total**: ~$18/month
+
+### Large SaaS (10000+ users)
+- **CX31** (2 vCPU, 8GB RAM): $14.28/month
+- **Managed Postgres** (8GB): $20.00/month
+- **Storage** (80GB): $2.00/month
+- **Total**: ~$36/month
+
+## Test Cases
+
+### Test 1: Basic Provision
+**File**: `test-cases/test-1-basic-provision.yaml`
+**Scenario**: Provision CX11 instance with Docker
+**Expected**: Terraform code generated, cost ~$6/month
+
+### Test 2: Postgres Provision
+**File**: `test-cases/test-2-postgres-provision.yaml`
+**Scenario**: Add managed Postgres database
+**Expected**: Database resource added, cost ~$11/month
+
+### Test 3: SSL Configuration
+**File**: `test-cases/test-3-ssl-config.yaml`
+**Scenario**: Configure SSL with Let's Encrypt
+**Expected**: Nginx + Certbot configuration, HTTPS working
+
+## Verification Steps
+
+See `test-results/README.md` for:
+1. How to run each test case
+2. Expected vs actual output
+3. Manual verification steps
+4. Screenshots of successful deployment
+
+## Integration with Other Skills
+
+- **cost-optimizer**: Recommends Hetzner when budget <$20/month
+- **devops-agent**: Provides strategic infrastructure planning
+- **nextjs-agent**: NextJS-specific deployment configuration
+- **nodejs-backend**: Node.js app deployment
+- **monitoring-setup**: Adds Uptime Kuma monitoring
+
+## Limitations
+
+- **EU-only**: Data centers in Germany/Finland (GDPR-friendly but not global)
+- **No auto-scaling**: Manual scaling only (upgrade instance type)
+- **Single-region**: Multi-region requires manual setup
+- **No serverless**: Traditional VM-based hosting
+
+## Alternatives
+
+When NOT to use Hetzner:
+- **Global audience**: Use Vercel (global edge network)
+- **Auto-scaling needed**: Use AWS/GCP
+- **Serverless preferred**: Use Vercel/Netlify
+- **Enterprise SLA required**: Use AWS/Azure with support plans
+
+## Future Enhancements
+
+- [ ] Kubernetes (k3s) cluster setup
+- [ ] Load balancer configuration
+- [ ] Multi-region deployment
+- [ ] Auto-scaling with Hetzner Cloud API
+- [ ] Monitoring integration (Grafana + Prometheus)
+- [ ] Disaster recovery automation
+
+---
+
+**Status**: Planned (Increment 003)
+**Priority**: P1
+**Tests**: 3+ test cases required
+**Documentation**: `.specweave/docs/guides/hetzner-deployment.md`
--- a/skills/hetzner-provisioner/SKILL.md
+++ b/skills/hetzner-provisioner/SKILL.md
@@ -0,0 +1,251 @@
+---
+name: hetzner-provisioner
+description: Provisions infrastructure on Hetzner Cloud with Terraform/Pulumi. Generates IaC code for CX11/CX21/CX31 instances, managed Postgres, SSL configuration, Docker deployment. Activates for deploy on Hetzner, Hetzner Cloud, budget deployment, cheap hosting, $10/month hosting.
+---
+
+# Hetzner Cloud Provisioner
+
+Automated infrastructure provisioning for Hetzner Cloud - the budget-friendly alternative to Vercel and AWS.
+
+## Purpose
+
+Generate and deploy infrastructure-as-code (Terraform/Pulumi) for Hetzner Cloud, enabling $10-15/month SaaS deployments instead of $50-100/month on other platforms.
+
+## When to Use
+
+Activates when user mentions:
+- "deploy on Hetzner"
+- "Hetzner Cloud"
+- "budget deployment"
+- "cheap hosting"
+- "deploy for $10/month"
+- "cost-effective infrastructure"
+
+## What It Does
+
+1. **Analyzes requirements**:
+   - Application type (NextJS, Node.js, Python, etc.)
+   - Database needs (Postgres, MySQL, Redis)
+   - Expected traffic/users
+   - Budget constraints
+
+2. **Generates Infrastructure-as-Code**:
+   - Terraform configuration for Hetzner Cloud
+   - Alternative: Pulumi for TypeScript-native IaC
+   - Server instances (CX11, CX21, CX31)
+   - Managed databases (Postgres, MySQL)
+   - Object storage (if needed)
+   - Networking (firewall rules, floating IPs)
+
+3. **Configures Production Setup**:
+   - Docker containerization
+   - SSL certificates (Let's Encrypt)
+   - DNS configuration (Cloudflare or Hetzner DNS)
+   - GitHub Actions CI/CD pipeline
+   - Monitoring (Uptime Kuma, self-hosted)
+   - Automated backups
+
+4. **Outputs Deployment Guide**:
+   - Step-by-step deployment instructions
+   - Cost breakdown
+   - Monitoring URLs
+   - Troubleshooting guide
+
+---
+
+## ⚠️ CRITICAL: Secrets Required (MANDATORY CHECK)
+
+**BEFORE generating Terraform/Pulumi code, CHECK for Hetzner API token.**
+
+### Step 1: Check If Token Exists
+
+```bash
+# Check .env file
+if [ -f .env ] && grep -q "HETZNER_API_TOKEN" .env; then
+  echo "✅ Hetzner API token found"
+else
+  # Token NOT found - STOP and prompt user
+fi
+```
+
+### Step 2: If Token Missing, STOP and Show This Message
+
+```
+🔐 **Hetzner API Token Required**
+
+I need your Hetzner API token to provision infrastructure.
+
+**How to get it**:
+1. Go to: https://console.hetzner.cloud/
+2. Click on your project (or create one)
+3. Navigate to: Security → API Tokens
+4. Click "Generate API Token"
+5. Give it a name (e.g., "specweave-deployment")
+6. Permissions: **Read & Write**
+7. Click "Generate"
+8. **Copy the token immediately** (you can't see it again!)
+
+**Where I'll save it**:
+- File: `.env` (gitignored, secure)
+- Format: `HETZNER_API_TOKEN=your-token-here`
+
+**Security**:
+✅ .env is in .gitignore (never committed to git)
+✅ Token is 64 characters, alphanumeric
+✅ Stored locally only (not in source code)
+
+Please paste your Hetzner API token:
+```
+
+### Step 3: Validate Token Format
+
+```bash
+# Hetzner tokens are 64 alphanumeric characters
+if [[ ! "$HETZNER_API_TOKEN" =~ ^[a-zA-Z0-9]{64}$ ]]; then
+  echo "⚠️  Warning: Token format unexpected"
+  echo "Expected: 64 alphanumeric characters"
+  echo "Got: ${#HETZNER_API_TOKEN} characters"
+  echo ""
+  echo "This might not be a valid Hetzner API token."
+  echo "Continue anyway? (yes/no)"
+fi
+```
+
+### Step 4: Save Token Securely
+
+```bash
+# Save to .env
+echo "HETZNER_API_TOKEN=$HETZNER_API_TOKEN" >> .env
+
+# Ensure .env is gitignored
+if ! grep -q "^\.env$" .gitignore; then
+  echo ".env" >> .gitignore
+fi
+
+# Create .env.example for team
+cat > .env.example << 'EOF'
+# Hetzner Cloud API Token
+# Get from: https://console.hetzner.cloud/ → Security → API Tokens
+HETZNER_API_TOKEN=your-hetzner-token-here
+EOF
+
+echo "✅ Token saved to .env (gitignored)"
+echo "✅ Created .env.example for team (commit this)"
+```
+
+### Step 5: Use Token in Terraform
+
+```hcl
+# terraform/variables.tf
+variable "hetzner_token" {
+  description = "Hetzner Cloud API Token"
+  type        = string
+  sensitive   = true
+}
+
+# terraform/provider.tf
+provider "hcloud" {
+  token = var.hetzner_token
+}
+
+# Run Terraform
+# export TF_VAR_hetzner_token=$HETZNER_API_TOKEN
+# terraform apply
+```
+
+---
+
+## Example Usage
+
+**User**: "Deploy my NextJS app on Hetzner with Postgres, as cheaply as possible"
+
+**hetzner-provisioner**:
+```markdown
+I'll provision your NextJS app on Hetzner Cloud for ~$12/month.
+
+Infrastructure:
+- CX11 instance (2 vCPU, 2GB RAM): $5.83/month
+- Managed Postgres (2GB): $5.00/month
+- 20GB storage: $0.50/month
+- SSL (Let's Encrypt): Free
+- Total: ~$11.33/month
+
+Creating Terraform configuration...
+
+✅ Generated files:
+- terraform/main.tf
+- terraform/variables.tf
+- terraform/outputs.tf
+- .github/workflows/deploy.yml
+
+Next steps:
+1. Set HETZNER_API_TOKEN in GitHub secrets
+2. Push to GitHub
+3. GitHub Actions will deploy automatically
+
+Deployment URL: https://your-app.yourdomain.com (after DNS configured)
+```
+
+## Configuration
+
+Supports multiple instance types:
+- **CX11** (1 vCPU, 2GB RAM): $5.83/month - Small apps, 100-1000 users
+- **CX21** (2 vCPU, 4GB RAM): $6.90/month - Medium apps, 1000-10000 users
+- **CX31** (2 vCPU, 8GB RAM): $14.28/month - Larger apps, 10000+ users
+
+Database options:
+- Managed Postgres (2GB): $5/month
+- Managed MySQL (2GB): $5/month
+- Self-hosted (included in instance cost)
+
+## Test Cases
+
+See `test-cases/` for validation scenarios:
+1. **test-1-basic-provision.yaml** - Basic CX11 instance
+2. **test-2-postgres-provision.yaml** - Add managed Postgres
+3. **test-3-ssl-config.yaml** - SSL and DNS configuration
+
+## Cost Comparison
+
+| Platform | Small App | Medium App | Large App |
+|----------|-----------|------------|-----------|
+| **Hetzner** | $12/mo | $15/mo | $25/mo |
+| Vercel | $60/mo | $120/mo | $240/mo |
+| AWS | $25/mo | $80/mo | $200/mo |
+| Railway | $20/mo | $50/mo | $100/mo |
+
+**Savings**: 50-80% vs alternatives
+
+## Technical Details
+
+**Terraform Provider**: `hetznercloud/hcloud`
+**API**: Hetzner Cloud API v1
+**Regions**: Nuremberg, Falkenstein, Helsinki (Germany/Finland)
+**Deployment**: Docker + GitHub Actions
+**Monitoring**: Uptime Kuma (self-hosted, free)
+
+## Integration
+
+Works with:
+- `cost-optimizer` - Recommends Hetzner when budget-conscious
+- `devops-agent` - Strategic infrastructure planning
+- `nextjs-agent` - NextJS-specific deployment
+- Any backend framework (Node.js, Python, Go, etc.)
+
+## Limitations
+
+- EU-only data centers (GDPR-friendly)
+- Requires Hetzner Cloud account
+- Manual DNS configuration needed
+- Not suitable for multi-region deployments (use AWS/GCP for that)
+
+## Future Enhancements
+
+- Kubernetes support (k3s on Hetzner)
+- Load balancer configuration
+- Multi-region deployment
+- Disaster recovery setup
+
+---
+
+**For detailed usage**, see `README.md` and test cases in `test-cases/`