Laravel Coolify Laravel Package

Technical Evaluation

Architecture fit: This package is a deployment/provisioning accelerator for Laravel applications targeting self-hosted Coolify. It provides artisan commands, dashboard routes, generated Dockerfiles, env management, and deploy hooks. v3.5.0 is primarily a security-hardening and correctness release, which improves fit for teams that need a tighter production posture but increases the coordination required to adopt it. It fits best when the application is Laravel-native, deployed through Coolify’s Docker build flow, and owned by a team that can manage tokens, generated Docker files, and Coolify API compatibility.

Integration feasibility: Moderate. The package itself is installable via Composer, but this release is not a drop-in upgrade for every environment. Existing provisioned apps may contain an operator COOLIFY_TOKEN, generated Dockerfiles are not rewritten automatically, and the package removes a Kick cache configuration path. Integration requires an inventory and remediation pass: token rotation, minimal-scope dashboard tokens, env cleanup, Dockerfile regeneration, and deploy-script validation. Feasible for a platform team or a Laravel team with Coolify ownership; riskier for decentralized app teams without a shared runbook.

Technical risk: Elevated because the release fixes security issues that may already exist in deployed apps. Key risks include credential exposure from previously copied COOLIFY_TOKEN values, dashboard breakage if tokens are removed without replacement, stale Dockerfiles retaining root entrypoints, deploy automation relying on GET /deploy or cached deploy behavior, and dependency conflicts from the guzzlehttp/guzzle ^7.15.2 requirement. The non-root artisan entrypoint and build-time storage:link improve runtime security but can expose permission issues in custom images. The 30/min non-GET dashboard rate limit and 1–1000 log-line clamp are sensible hardening changes but may affect admin workflows and debugging. Removal of coolify.kick.cache_ttl / COOLIFY_KICK_CACHE_TTL is a behavior change that needs explicit cleanup.

Key questions:

• How many provisioned apps currently contain COOLIFY_TOKEN, and which actually need dashboard access in production?
• Who owns Coolify operator-token rotation and creation of minimal-scope per-app tokens?
• Are Dockerfiles generated by this package or customized? What is the regeneration and rollback procedure?
• What consumes KICK_TOKEN or the removed Kick cache TTL config, and are any env vars still set?
• Do any deploy scripts call GET /deploy or depend on cached deploy responses?
• What Coolify API version is targeted, and does the app’s Composer lockfile accept Guzzle ^7.15.2?
• Are re-provisioning, env updates, APP_KEY preservation, and non-root entrypoints covered by automated tests or canary checks?
• What is the package’s maintenance/support model, and do we need an internal fork or pinning strategy for security-sensitive releases?

Integration Approach

Stack fit: Laravel/PHP application with Composer, deployed via Coolify using Docker build packs. The package adds artisan commands, dashboard routes, generated Dockerfile stubs, env var management, and Coolify API calls. It fits well for standard Laravel apps but less well for apps with hand-maintained Dockerfiles, non-Laravel sidecars, or bespoke deployment automation. Verify Laravel/PHP version support and Coolify API compatibility before rollout.

Migration path:

1. Inventory: Identify all apps provisioned by the package, dashboard exposure, existing COOLIFY_TOKEN values, KICK_* envs, custom Dockerfiles, and deploy scripts.
2. Non-production upgrade: Upgrade the package in a canary app, resolve Guzzle constraints, regenerate Docker files with php artisan coolify:install, rerun coolify:provision, and validate deploy behavior.
3. Secret remediation: Rotate the operator COOLIFY_TOKEN, remove it from apps that do not use the dashboard, and create separate minimal-scope tokens for apps that do. Remove COOLIFY_KICK_CACHE_TTL / config references.
4. Dockerfile regeneration: Run the install command for each app to pick up the non-root entrypoint and build-time storage:link. Treat generated Dockerfiles as owned artifacts and store/compare changes.
5. Production canary: Redeploy a low-risk app, verify dashboard actions, rate limiting, log requests, env updates, and storage permissions.
6. Full rollout: Repeat by app group, monitor failures, then remove legacy tokens and update runbooks.

Compatibility: This release has backward-incompatible operational behavior even if the public API surface is small. Apps provisioned before 3.5.0 may retain embedded operator tokens. Existing Dockerfiles will not be rewritten. The deploy call now uses POST /deploy and must not be cached. Env updates now use key-based PATCH /applications/{uuid}/envs; re-provisioning should update rather than duplicate env vars and must preserve an existing APP_KEY. Dashboard field names changed to is_buildtime and domains, which may fix silent misconfigurations. The removed Kick cache config needs cleanup. Guzzle ^7.15.2 may require lockfile updates or conflict resolution.

Sequencing: Inventory → non-prod upgrade → token rotation and minimal-scope token creation → env/config cleanup → Dockerfile regeneration → production canary → full rollout → legacy credential removal. Do not remove COOLIFY_TOKEN from production dashboard apps before replacement tokens are in place. Regenerate Dockerfiles before redeploying so the non-root entrypoint and storage link actually take effect. Test re-provisioning on an existing app copy before touching production, because idempotency and APP_KEY preservation are critical.

Operational Impact

Maintenance: The package now requires active secret lifecycle management and Dockerfile lifecycle management. Someone must track package releases, Guzzle security advisories, Coolify API changes, and generated Dockerfile drift. The provisioning idempotency fix reduces manual repair, but token rotation and per-app minimal-scope tokens add recurring operational work. Removal of the Kick cache config simplifies one path but requires cleanup. Dashboard rate limits and log clamps should be documented in admin/support runbooks.

Support: Expect a short-term support spike during upgrade: dashboard auth failures after token removal, permission errors from non-root artisan, stale Dockerfiles, deploy failures from GET→POST, and missing env vars after config cleanup. Provide app owners with a clear token-replacement procedure. Verify webhook integrations because the webhook secret is no longer embedded in the URL or printed under --no-interaction. Support staff may need alternate log access because dashboard log requests are clamped to 1–1000 lines.

Scaling: The 30/min non-GET rate limit per user can constrain admin automation or bursty dashboard use; reads are unlimited. Provisioning and deploy throughput remains bound by Coolify API limits. Per-app minimal-scope tokens improve blast-radius control but increase secret-management overhead as app count grows. The non-root runtime may require volume and storage permission planning at scale. Kick lookups now rely on the API response cache, so cache TTL sizing should be reviewed.

Failure modes:

• Dashboard breaks after COOLIFY_TOKEN is removed without a replacement minimal-scope token.
• Old generated Dockerfiles keep root execution or miss public/storage, leaving security/runtime fixes inactive.
• Deploy automation using GET /deploy fails or silently no-ops due to caching assumptions.
• Re-provisioning partially updates envs or replaces APP_KEY if validation is skipped.
• Non-root www-data cannot write storage/cache in custom images.
• Guzzle version conflict blocks upgrade.
• KICK_TOKEN or removed cache TTL consumers fail after config cleanup.
• Rate limiting blocks legitimate admin bursts or automation.
• Log clamping hides diagnostic lines during incidents.
• Operator token remains embedded in older apps, sustaining credential exposure.

Ramp-up: Low for basic artisan usage, moderate for a secure production rollout. Teams need Coolify API familiarity, Docker build/runtime knowledge, Laravel env/config understanding, and a clear secret-rotation process. TPM should treat v3.5.0 as a security remediation workstream, not a routine dependency bump: allocate time for inventory, token rotation, Dockerfile regeneration, canary testing, and runbook updates.