---
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