Laravel Coolify Laravel Package

Getting Started

laravel-coolify is the glue between a Laravel app and a self-hosted Coolify instance: it generates the container build files, provisions the Coolify application over the API, and mounts a small dashboard for deploys, env vars and logs.

1. composer require stumason/laravel-coolify (v3.5.0 requires guzzlehttp/guzzle ^7.15.2 — if you have an old pin, bump it first).
2. Run php artisan coolify:install. This publishes config/coolify.php and writes the Dockerfile / entrypoint / webserver config into your repo. Those generated files are yours from that moment on.
3. Set the connection details in .env: the Coolify base URL and a token. For local/provisioning work this is an operator token; for a deployed app it should be a scoped token (see Gotchas).
4. Run php artisan coolify:provision against a fresh environment to create the application, wire env vars, and generate the deploy key and webhook secret.

Where to look first: config/coolify.php. Almost every behaviour discussed below — token, app UUID, cache TTL, dashboard enablement — is driven from there, and the 3.5.0 removals/renames all land in this file.

First use case: stand up a staging environment end-to-end — coolify:install, commit the generated files, coolify:provision, push a commit, watch the deploy land. That exercises the whole loop (build args, entrypoint, storage link, API calls) before you attempt production.

Implementation Patterns

Treat coolify:provision as idempotent, and re-run it. Since 3.5.0 it updates existing env vars through Coolify's key-based PATCH /applications/{uuid}/envs instead of blindly re-inserting, so it is safe (and now expected) to re-run after changing .env. It will not overwrite an existing APP_KEY, which makes it a reasonable thing to run from CI on every release.

Split tokens by environment. Provisioning needs an operator token. The deployed app needs a Coolify token only if you actually use the dashboard in production — and 3.5.0 stops copying the operator token into the provisioned app for exactly that reason. Pattern: provision with the operator token from your machine/CI, then create a minimal-scope token in Coolify scoped to that one application and set it on the app manually. Apps that never touch the dashboard should have no COOLIFY_TOKEN at all.

Classify env vars deliberately. Every var except VITE_* is now marked runtime-only, so secrets never become Docker build args. The consequence is architectural: anything needed at build time must be VITE_-prefixed (and is therefore public). If you were relying on APP_KEY or a DB URL being present during the build, move that work to runtime — the entrypoint already runs migrate and optimize as www-data, so config/route caching happens there, not in the image.

Drive deploys from explicit actions, not cached reads. Deploys are POST /deploy and are never cached as of 3.5.0. If you script deploys, hit the endpoint directly or use the dashboard action; do not wrap it in a cached helper, and don't expect a repeat trigger inside the cache window to do anything (that was the bug fixed in #145).

Batch dashboard writes. Non-GET dashboard actions are capped at 30/minute per user; reads are unlimited. Interactive use is fine; automated "sync all env vars then restart" loops through the dashboard will 429. For bulk env work use coolify:provision or the API directly, and handle 429 with backoff.

Tune one TTL, not two. Kick lookups now use the general API response cache (coolify.cache_ttl). coolify.kick.cache_ttl / COOLIFY_KICK_CACHE_TTL are gone. Lowering coolify.cache_ttl to get fresher kick data also makes your dashboard reads chattier — pick the value with both in mind.

Own the generated Docker files. The package only generates them; it never rewrites them. Establish a habit of diffing the generated entrypoint against your committed one after each upgrade (regenerate into a scratch checkout and diff) so you inherit fixes like the non-root runuser artisan invocation and build-time storage:link without silently losing your own edits.

Log tailing: the dashboard clamps to 1–1000 lines. Build tooling around a sane value (200–500) rather than assuming unbounded reads.

Gotchas and Tips

Upgrade checklist for 3.5.0 — do all four:

• Rotate your operator token. Any app provisioned before 3.5.0 has your operator COOLIFY_TOKEN sitting in its Coolify env vars. Remove it, or replace it with a minimal-scope token, then rotate the operator token itself.
• Regenerate Docker files (php artisan coolify:install into a scratch dir, then merge). Your existing entrypoint still runs artisan as root and lacks the build-time storage:link. This is not applied automatically.
• Remove COOLIFY_KICK_CACHE_TTL from .env and any config overlay; it is silently ignored now.
• Verify your guzzle constraint resolves to ^7.15.2 (two advisories).

Non-root artisan means new permission failure modes. The entrypoint restores storage before running db:show/migrate/optimize as www-data via runuser. If you have custom entrypoint steps that write to storage/ or bootstrap cache as root, they can now leave directories that www-data can't write. Symptom: artisan succeeds during build/manual docker run but the container crash-loops. Fix by chowning to www-data in your added steps, not by reverting to root.

Dashboard route params are now [A-Za-z0-9-] only. Encoded .., #, ? are rejected, which is the point — but it also means any app/environment identifier containing . or _ will no longer route. Coolify UUIDs are safe; custom slugs may not be.

--no-interaction no longer reveals the webhook secret. That's a security fix, not a regression — but it breaks naive CI scripts that grepped the output. Read the secret from the Coolify UI (or the API) and feed it in as a variable. The secret is also no longer embedded in the webhook URL, so anything that parsed it out of the URL needs updating.

Re-provisioning rotates Reverb credentials. Production Reverb creds are now generated fresh rather than copied from local. If you re-run coolify:provision on an existing app, expect connected clients to need the new keys.

APP_KEY is immutable via this tool. Existing APP_KEY is never replaced, by design. If you genuinely need to rotate it, do it in Coolify's UI and handle the decrypt fallout yourself — don't expect a re-provision to do it.

Field names matter if you extended the dashboard. The API payloads now send is_buildtime and domains (not is_build_time / fqdn). If you forked any request-building code, mirror the change or env vars and domains will silently fail to stick.

Debugging order when a deploy "does nothing": (1) confirm you're on ≥3.5.0 — pre-3.5.0 deploys used cached GET /deploy and repeat triggers within the TTL were no-ops; (2) check coolify.cache_ttl; (3) check the app's token scope, since a minimal-scope token may not have deploy permission; (4) only then look at Coolify's own deploy logs.

Extension points worth knowing: the config file is the intended surface (token, app UUID, cache TTL, dashboard toggle). Beyond that, the generated Docker files are the supported customisation point, and the dashboard controllers are the place to look if you need to alter action behaviour — but be aware you're now tracking upstream changes by hand, and 3.5.0 changed a lot of them at once.