coolify-image-app

A Coolify application of type Docker Image is the contract between the pipeline and the server: the pipeline moves one field (the image tag) and asks for a deploy; Coolify does the rolling update behind one domain with the container's own probe as the gate. Configure it once, exactly, and let every later deploy be an API call.

Hard rules: never break these

• Creating or saving a Coolify resource is a production action. Confirm with the owner before creating, deploying, changing domains or deleting anything, unless they already authorised it for this task.
• Never publish host ports and never set a custom container name. Port mapping bypasses the firewall; a fixed name breaks rolling updates.
• The image must exist before the first deploy. Push :main from the pipeline (or a manual run) first; Coolify cannot build a Docker Image app.
• Never type or print a token or secret. The owner creates API tokens and pastes secrets; you prefill forms and give click-by-click steps.
• Verify every save by reloading. Coolify's forms sometimes accept input without persisting it; reload the page and read the value back before moving on.

Step 1: Gather the facts

From the repo and the coolify-vps-baseline record: project and environment names, the image reference (ghcr.io/<owner>/<repo>), the container port, the exact domain, the health probe command the image ships (node healthcheck.js or similar), the memory budget, and which environment variables are runtime (build-time ones are baked into the image and must not be set here).

Step 2: Create the application

Coolify UI, the project's environment, New resource, Docker Image: image name without a tag, tag main, Create application. Note the application UUID from the URL; the pipeline needs it.

Step 3: Configure, tab by tab

Coolify rejects shell operators (&&, |, ;) in the health command, and the runtime image has no curl: the probe must be a plain binary call. Number inputs sometimes do not take a typed value; press Enter inside the field to submit, then reload and read it back. Full field notes and the API that moves the tag are in reference/coolify-api.md.

Step 4: Deploy once by hand

Actions, Deploy. Watch the deployment log until Rolling update completed, then from the server:

C=$(sudo docker ps --filter label=coolify.resourceName=<app> --format '{{.Names}}' | head -1)
sudo docker inspect "$C" --format 'health={{.State.Health.Status}} mem={{.HostConfig.Memory}} ports={{.HostConfig.PortBindings}} user={{.Config.User}}'

Expect healthy, the byte value of the limit, map[], and the non-root user. Then hand over to the deploy-verification skill for the certificate, routing and header checks.

Step 5: Wire the pipeline

The owner creates an API token at Keys & Tokens, API Tokens, with Deploy, Read and Write permissions (write to patch the tag, deploy to trigger, read to poll) and stores it as the GitHub secret COOLIFY_TOKEN. Set the repository variables COOLIFY_URL and COOLIFY_APP_UUID yourself with gh variable set. The workflow that uses them is the ghcr-coolify-pipeline skill.

Report the application UUID, every setting as read back after reload, the deployment outcome, and the owner actions still open.