Appearance
Deploying an app
Every app on the box follows the same contract. The infra:onboard skill walks through it, and the full version is plugin/reference/platform.md in the repo.
The contract
- One Coolify project per repo, with a
productionenvironment. - Deployed from GitHub through Coolify's GitHub App, from branch
main, auto-deploying on push. In a repo with several apps,watch_pathslimits each one to its own folder. - Builds for arm64. The build runs on the server, so it's native ARM. A Dockerfile is preferred. Nixpacks is fine for simple Node or Python apps.
- Listens on
0.0.0.0:$PORT. Coolify's "ports exposes" is set to that port. Never publish host ports, because Traefik routes by hostname. - Health check:
GET /healthreturns 200 once the app is ready, and the image includescurlorwget. - Domain:
https://<app>.stu-bot.uk. Coolify creates the proxied DNS record. - Config comes from env vars only, set in Coolify, never committed:
DATABASE_URL: the app's own PostgresREDIS_URL: the app's own Redis/Valkey, if it needs oneBUS_URL: the shared event bus, only for messages between servicesPUBLIC_URL: its public address
- Logs go to stdout and stderr. Coolify keeps them.
- Every app and database has a memory limit. Apps start at 512 MB and databases at 256 MB, and only go up for a reason.
- Scheduled jobs use Coolify scheduled tasks, not cron inside the container.
Who can reach it
- Public: a proxied DNS record and nothing else.
- Only me: add a Cloudflare Access app for the hostname, allowing my email. If the app receives webhooks, add a bypass app for just that path, and check a secret in the app.
- Internal only: no domain at all (check
fqdnis null), reached by its container name on thecoolifynetwork, and still protected by its own token.
How a deploy runs
- A push to GitHub reaches the webhook.
- Coolify clones the repo, builds the image on the server and starts the new container.
- Once the health check passes, Traefik switches traffic to the new container and the old one stops.
- If the build fails, a Telegram message goes out.
Coolify keeps a few previous images, so rolling back means redeploying the last good one.