Skip to content

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 ​

  1. One Coolify project per repo, with a production environment.
  2. Deployed from GitHub through Coolify's GitHub App, from branch main, auto-deploying on push. In a repo with several apps, watch_paths limits each one to its own folder.
  3. 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.
  4. 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.
  5. Health check: GET /health returns 200 once the app is ready, and the image includes curl or wget.
  6. Domain: https://<app>.stu-bot.uk. Coolify creates the proxied DNS record.
  7. Config comes from env vars only, set in Coolify, never committed:
    • DATABASE_URL: the app's own Postgres
    • REDIS_URL: the app's own Redis/Valkey, if it needs one
    • BUS_URL: the shared event bus, only for messages between services
    • PUBLIC_URL: its public address
  8. Logs go to stdout and stderr. Coolify keeps them.
  9. 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.
  10. 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 fqdn is null), reached by its container name on the coolify network, and still protected by its own token.

How a deploy runs ​

  1. A push to GitHub reaches the webhook.
  2. Coolify clones the repo, builds the image on the server and starts the new container.
  3. Once the health check passes, Traefik switches traffic to the new container and the old one stops.
  4. If the build fails, a Telegram message goes out.

Coolify keeps a few previous images, so rolling back means redeploying the last good one.