# Coolify deployment — Production ERPNext (+ HRMS, Lending, LMS)

## Prerequisites

- Coolify v4+ with Docker Compose support
- Jenkins green build → image in Forgejo Packages
- **4 GB+ RAM** (8 GB+ recommended)
- Compose file: `docker-compose.yml`

## 1. Create the Coolify service

| Setting | Value |
|---------|--------|
| Type | Docker Compose |
| Repository | `https://git.aexoradao.com/epistemophiliac/erpnext` |
| Branch | `main` |
| Compose file | `docker-compose.yml` |

## 2. Environment variables (Coolify UI)

Copy from [`coolify.env.example`](../coolify.env.example). **Required before first deploy:**

| Variable | Set in Coolify? | Source |
|----------|----------------|--------|
| `CUSTOM_IMAGE` | yes | Jenkins artifact / `dist/coolify-image.env` |
| `CUSTOM_TAG` | yes | `main` (latest Jenkins build — do not pin commit tags) |
| `PULL_POLICY` | yes | `if_not_present` |
| `DB_PASSWORD` | yes | strong secret |
| `ADMIN_PASSWORD` | yes | Frappe `Administrator` password |
| `INSTALL_APPS` | yes | `erpnext,payments,hrms,lending,lms` |
| `SITE_NAME` | **no** (auto) | From Coolify domain via `SERVICE_FQDN_FRONTEND` |
| `FRAPPE_SITE_NAME_HEADER` | **no** (auto) | Set at frontend start from `sites/currentsite.txt` |

> **Coolify env cache:** If you previously set `SITE_NAME=erp.example.com` in Coolify, **delete it** so compose defaults use your real domain. Changing `docker-compose.yml` defaults alone does not update stored values.

## 3. Domain (before first deploy)

1. Coolify → your service → **Domains**
2. Add domain, e.g. `erp.aexoradao.com`
3. Attach to service **`frontend`**, port **`8080`**
4. Coolify writes `SERVICE_FQDN_FRONTEND=erp.aexoradao.com` into the stack `.env`
5. Compose sets:
   - `create-site` → `SITE_NAME=erp.aexoradao.com`
   - `frontend` → `FRAPPE_SITE_NAME_HEADER=erp.aexoradao.com`

**Order matters:** assign domain **then** deploy. If `create-site` runs with an empty site name, the stack exits with a clear error.

## 4. Image on the Coolify host (before first deploy)

The custom image is **~1.2 GB**. Coolify must find `git.aexoradao.com/epistemophiliac/erpnext:main` on the **host** Docker daemon — not pulled through Cloudflare during deploy.

**Jenkins does this automatically** after each green build (`jenkins-push-image.sh` copies `:main` from internal Forgejo via Skopeo).

**Manual / one-time** on the Coolify server as root:

```bash
export REGISTRY_USER=epistemophiliac
export REGISTRY_PASSWORD='<forgejo-token>'
bash scripts/coolify/sync-main-from-forgejo.sh
```

Coolify env: `CUSTOM_TAG=main` only — no `main-<sha>` pins.

## 5. First deploy

```text
db → redis → configurator
  → create-site (install apps, ~10–20 min)
  → migrator → backend / workers / frontend
```

Login: `https://your-domain` — user `Administrator`, password = `ADMIN_PASSWORD`.

## 6. Upgrades

1. Jenkins builds new image → pushes `:main` and preloads host Docker
2. Redeploy Coolify — `if_not_present` uses the updated local `:main`

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Traefik `404 page not found` / URL unreachable | Domain must be on service `frontend` port **8080**; app `ports_exposes` must be 8080 not 3000 |
| Backend unhealthy / deploy fails after migrator | Healthcheck must send `Host: <site>` — fixed in compose; redeploy |
| `SITE_NAME empty` on create-site | Assign domain on `frontend:8080` before deploy (`SERVICE_FQDN_FRONTEND`) |
| Wrong site / 404 nginx | Delete old `SITE_NAME` in Coolify UI; ensure header matches domain |
| Site created with wrong name | Wipe `sites` volume or rename site manually — env change alone won't rename |
| Deploy log page crashes / blank | First `create-site` is huge — fixed by filtering DocType spam; redeploy after site exists |
| create-site finished but backend/scheduler not running | Deploy timed out during first site install — **redeploy** (site exists, starts in seconds) |
| Image pull failed | Ensure `:main` on host via Jenkins or sync script — do not pull large image through Cloudflare |