Add coolify-setup skill with full setup guide and API integration reference
This commit is contained in:
Hoid
parent
9b4c6f020b
commit
3674e0a96f
2 changed files with 272 additions and 0 deletions
147
skills/coolify-setup/SKILL.md
Normal file
147
skills/coolify-setup/SKILL.md
Normal file
|
|
@ -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@<coolify-mgr-ip>
|
||||||
|
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash
|
||||||
|
```
|
||||||
|
|
||||||
|
- Coolify UI will be at `http://<coolify-mgr-ip>: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
|
||||||
125
skills/coolify-setup/references/api-integration.md
Normal file
125
skills/coolify-setup/references/api-integration.md
Normal file
|
|
@ -0,0 +1,125 @@
|
||||||
|
# Coolify API Integration for CEO Agents
|
||||||
|
|
||||||
|
## API Authentication
|
||||||
|
|
||||||
|
Coolify exposes a REST API at `https://<coolify-domain>/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 <token>" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
https://coolify.cloonar.com/api/v1/<endpoint>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Endpoints
|
||||||
|
|
||||||
|
### Deploy Application
|
||||||
|
```
|
||||||
|
POST /api/v1/deploy
|
||||||
|
Body: { "uuid": "<app-uuid>" }
|
||||||
|
# or by tag:
|
||||||
|
Body: { "tag": "<tag-name>" }
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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=<project-scoped-token>
|
||||||
|
# DOCFAST_APP_UUID=<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.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue