diff --git a/skills/coolify-setup/SKILL.md b/skills/coolify-setup/SKILL.md new file mode 100644 index 0000000..6748afe --- /dev/null +++ b/skills/coolify-setup/SKILL.md @@ -0,0 +1,147 @@ +--- +name: coolify-setup +description: Set up Coolify as a self-hosted container platform on Hetzner for hosting multiple micro-SaaS projects. Use when the user wants to set up Coolify, add servers to Coolify, deploy containers, or manage the container hosting infrastructure. +--- + +# Coolify Container Platform Setup + +Guide for setting up Coolify on Hetzner to host multiple AI-CEO-managed micro-SaaS projects (DocFast, SnapAPI, etc.) with high availability. + +## Architecture + +``` +Coolify Manager (CAX11 €3.89/mo — ARM64, 2 vCPU, 4GB RAM, 40GB) + ├── Worker Node 1 (CAX11 €3.89/mo) — DocFast + SnapAPI + shared DBs + ├── Worker Node 2 (CAX11 €3.89/mo) — replica/failover + └── Future nodes as needed +``` + +- Manager runs Coolify UI + orchestration only (no workloads if possible) +- Worker nodes run actual project containers +- Each project = separate Coolify "project" with isolated API tokens +- CEO agents get project-scoped API tokens (can only manage their own project) +- Total base cost: ~€12/mo for 3 nodes + +## Phase 1: Provision Hetzner Servers + +1. Create 3x CAX11 (ARM64) servers in Hetzner Cloud: + - `coolify-mgr` — Manager node + - `coolify-w1` — Worker 1 + - `coolify-w2` — Worker 2 +2. All in same Hetzner project, same datacenter (fsn1 or nbg1) +3. Use Ubuntu 24.04 LTS +4. Add SSH key from OpenClaw VM (`/home/openclaw/.ssh/id_ed25519.pub` or generate new) +5. Set up private networking between nodes (Hetzner vSwitch or Cloud Network) +6. Firewall rules: + - Manager: 22 (SSH), 80, 443, 8000 (Coolify UI) + - Workers: 22 (SSH from manager only), 80, 443 + - Between nodes: all traffic on private network + +## Phase 2: Install Coolify on Manager + +```bash +ssh root@ +curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash +``` + +- Coolify UI will be at `http://:8000` +- Create admin account +- Set up a domain for Coolify itself (e.g., `coolify.cloonar.com`) +- Enable SSL via Let's Encrypt + +## Phase 3: Add Worker Nodes + +In Coolify UI: +1. Go to Servers → Add Server +2. Add `coolify-w1` and `coolify-w2` as remote servers +3. Coolify needs SSH access to workers — use the SSH key generated in Coolify UI or copy manager's key to workers: + ```bash + # On manager, get coolify's public key: + cat /data/coolify/ssh/keys/id.root@host.docker.internal.pub + # Add to each worker's /root/.ssh/authorized_keys + ``` +4. Validate connection in Coolify UI +5. Docker will be installed automatically on workers by Coolify + +## Phase 4: Set Up Projects + +Create one Coolify "Project" per business: +- **DocFast** — migrate existing Docker setup +- **SnapAPI** — future deployment + +Each project gets: +- Its own environment variables +- Its own domains +- Its own deployment pipeline + +### Migrate DocFast + +1. In Coolify, create project "DocFast" +2. Add application from Forgejo repo `openclawd/docfast` +3. Configure: + - Build: Dockerfile + - Port: 3000 (or whatever DocFast exposes) + - Domain: `docfast.dev` + - Environment variables: copy from current `.env` + - Health check: `/health` +4. Add PostgreSQL database as a Coolify-managed database resource +5. Set up persistent volumes for any stateful data +6. Deploy and verify +7. Update DNS for `docfast.dev` → worker node IP +8. Verify Stripe webhooks still work with new IP + +### Important: DNS per server +Each worker runs its own proxy (Traefik). Point domain DNS to the worker IP where the app is deployed, NOT the manager IP. + +## Phase 5: High Availability + +Coolify's built-in HA approach: +- Deploy same application to multiple workers +- Use Hetzner Load Balancer (€5.39/mo) or DNS-based failover +- Coolify health checks detect failures + +Alternative (cheaper): +- Deploy primary on worker-1, have docker-compose ready on worker-2 +- Uptime monitor detects failure → CEO agent triggers redeploy on worker-2 +- Manual failover via DNS update (Hetzner API can automate this) + +## Phase 6: CEO Agent Integration + +See `references/api-integration.md` for details on: +- Creating project-scoped API tokens +- Deploy triggers from CEO agents +- Monitoring endpoints + +## Phase 7: Backups + +- Coolify has built-in backup for managed databases → configure S3 destination +- Use existing BorgBackup setup for file-level backups +- Storage Box: `u149513-sub11@u149513-sub11.your-backup.de:23` +- Create per-project subdirs: `./coolify-mgr/`, `./coolify-w1/`, etc. + +## Cost Summary + +| Resource | Cost/mo | +|----------|---------| +| coolify-mgr (CAX11) | €3.89 | +| coolify-w1 (CAX11) | €3.89 | +| coolify-w2 (CAX11) | €3.89 | +| Hetzner LB (optional) | €5.39 | +| **Total (without LB)** | **€11.67** | +| **Total (with LB)** | **€17.06** | + +## Checklist + +- [ ] Provision 3 Hetzner CAX11 servers +- [ ] Install Coolify on manager +- [ ] Set up domain for Coolify UI (e.g., coolify.cloonar.com) +- [ ] Add worker nodes +- [ ] Create DocFast project in Coolify +- [ ] Migrate DocFast from current server +- [ ] Test DocFast on new infrastructure +- [ ] Switch DNS for docfast.dev +- [ ] Verify Stripe webhooks +- [ ] Set up backups +- [ ] Create project-scoped API tokens for CEO agents +- [ ] Update DocFast CEO skill with new deploy workflow +- [ ] Decommission old DocFast server diff --git a/skills/coolify-setup/references/api-integration.md b/skills/coolify-setup/references/api-integration.md new file mode 100644 index 0000000..9abaa63 --- /dev/null +++ b/skills/coolify-setup/references/api-integration.md @@ -0,0 +1,125 @@ +# Coolify API Integration for CEO Agents + +## API Authentication + +Coolify exposes a REST API at `https:///api/v1/`. + +### Creating API Tokens + +1. Coolify UI → Settings → Keys & Tokens → API Tokens +2. Create one token per CEO agent/project +3. Tokens can be scoped — create project-level tokens so each CEO only sees its own resources + +### Using the API + +```bash +curl -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + https://coolify.cloonar.com/api/v1/ +``` + +## Key Endpoints + +### Deploy Application +``` +POST /api/v1/deploy +Body: { "uuid": "" } +# or by tag: +Body: { "tag": "" } +``` + +### List Applications +``` +GET /api/v1/applications +``` + +### Get Application +``` +GET /api/v1/applications/{uuid} +``` + +### Update Application Environment +``` +PATCH /api/v1/applications/{uuid}/envs +Body: { "key": "VAR_NAME", "value": "new_value" } +``` + +### Application Actions +``` +POST /api/v1/applications/{uuid}/start +POST /api/v1/applications/{uuid}/stop +POST /api/v1/applications/{uuid}/restart +``` + +### Databases +``` +GET /api/v1/databases +GET /api/v1/databases/{uuid} +POST /api/v1/databases/{uuid}/start +POST /api/v1/databases/{uuid}/stop +``` + +### Servers +``` +GET /api/v1/servers +GET /api/v1/servers/{uuid} +GET /api/v1/servers/{uuid}/resources +``` + +## CEO Agent Integration Pattern + +Each CEO agent should have a CLI helper script (like `bin/docfast-deploy`) that wraps the Coolify API: + +```bash +#!/bin/bash +# Example: bin/docfast-deploy +source ~/.openclaw/workspace/.credentials/coolify.env +# COOLIFY_URL=https://coolify.cloonar.com +# COOLIFY_TOKEN= +# DOCFAST_APP_UUID= + +curl -s -X POST \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"uuid\": \"$DOCFAST_APP_UUID\"}" \ + "$COOLIFY_URL/api/v1/deploy" +``` + +### What CEO Agents Can Do via API +- Trigger deploys after code changes +- Check application status/health +- Restart services if unhealthy +- Update environment variables +- Monitor server resources (disk, memory) +- Scale up/down (start/stop additional instances) + +### What CEO Agents Should NOT Do +- Manage other projects' resources (token scoping prevents this) +- Delete servers or applications +- Modify infrastructure-level settings + +## Webhook Deploys (Alternative) + +Instead of API-triggered deploys, Coolify supports webhook-based deploys: + +1. In Coolify, enable webhook for the application +2. Get the webhook URL (unique per app) +3. Add as Forgejo webhook → auto-deploy on push + +This is simpler for CI/CD but less controllable than API deploys. + +## Monitoring Integration + +CEO agents can check their application's health: + +```bash +# Get app status +curl -s -H "Authorization: Bearer $TOKEN" \ + "$COOLIFY_URL/api/v1/applications/$APP_UUID" | jq '.status' + +# Get server resources +curl -s -H "Authorization: Bearer $TOKEN" \ + "$COOLIFY_URL/api/v1/servers/$SERVER_UUID" | jq '.settings' +``` + +Combine with existing uptime monitoring (health endpoint checks) for comprehensive monitoring.