epistemophiliac
e73912541e
Document exit 255 during multi-hundred-MB layer downloads and default PULL_POLICY to if_not_present after preload.
90 lines
3.8 KiB
Markdown
90 lines
3.8 KiB
Markdown
# 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 | e.g. `main-26933f3` (pin) or `main` |
|
||
| `PULL_POLICY` | yes | `if_not_present` (after host preload; see below) |
|
||
| `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) | Same as domain via `SERVICE_FQDN_FRONTEND` |
|
||
|
||
> **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. Preload image on Coolify host (required once per tag)
|
||
|
||
The custom image is **~1.2 GB**. Coolify deploy can fail with `exit code 255` while pulling large layers through Cloudflare/Traefik (you may see progress stop around ~100 MB).
|
||
|
||
**On the Coolify server as root** (SSH or Coolify terminal):
|
||
|
||
```bash
|
||
git clone https://git.aexoradao.com/epistemophiliac/erpnext.git /tmp/erpnext
|
||
cd /tmp/erpnext
|
||
export REGISTRY_USER=epistemophiliac
|
||
export REGISTRY_PASSWORD='<forgejo-token-with-package-read>'
|
||
export CUSTOM_TAG=main-26933f3 # from Jenkins dist/coolify-image.env
|
||
bash scripts/coolify/preload-image.sh
|
||
```
|
||
|
||
This copies from internal Forgejo (`forgejo-vydgeq365afzmxe4s1d75fwv:3000`) — same path Jenkins uses for push — and tags `git.aexoradao.com/epistemophiliac/erpnext:<tag>` locally.
|
||
|
||
Set `PULL_POLICY=if_not_present` in Coolify so redeploys skip the large pull.
|
||
|
||
## 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 → update `CUSTOM_TAG` in Coolify
|
||
2. Redeploy — `migrator` runs `bench migrate`
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Fix |
|
||
|---------|-----|
|
||
| `SITE_NAME empty` on create-site | Assign domain on `frontend:8080` before deploy |
|
||
| 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 fails at `Downloading …/487MB` / exit 255 | Image is OK — run `scripts/coolify/preload-image.sh` on host, set `PULL_POLICY=if_not_present`, redeploy |
|
||
| Image pull failed | Check `CUSTOM_IMAGE` / `CUSTOM_TAG` in Forgejo Packages; preload on host for private/large registry |
|