Coolify Admin Guide

This guide is the operational and architectural reference for Coolify — an open-source, self-hostable Platform-as-a-Service. It is written for the administrators, DevOps engineers, and architects who run a Coolify instance: how it is built, how to configure every knob, how to secure it, how to operate it day to day, and how its deployment engine works internally. End-user, task-oriented documentation (deploying apps, creating databases, using services) lives in the companion User Guide.

1. Executive Summary

Coolify is a control plane that turns one or more Linux servers into a private application platform. It connects to servers over SSH, manages a reverse proxy on each, and runs user workloads (applications, databases, and pre-packaged services) as Docker containers. It provides Git-push deployments, automatic Let's Encrypt TLS, scheduled backups, preview environments, a full REST API, and an MCP server for AI agents.

Note

Coolify is a mixed PHP/Laravel monolith plus a small Node.js real-time sidecar. The Laravel app serves both the Livewire dashboard and the JSON REST API; background work (deployments, backups, health checks) runs as queued jobs under Horizon.

2. Architecture

2.1 Runtime topology

                          ┌──────────────────────────────────────────────┐
   Browser / API client   │            Coolify host (control plane)       │
        │  HTTPS           │                                              │
        ▼                  │   ┌─────────────┐   ┌────────────────────┐   │
   ┌──────────┐  :8000     │   │  coolify    │   │ coolify-realtime   │   │
   │  proxy   │───────────▶│   │ (PHP-FPM +  │   │ (websockets +      │   │
   │ (Traefik)│            │   │  nginx,     │   │  in-browser term., │   │
   └──────────┘  :6001/2   │   │  Laravel 12)│   │  node-pty)         │   │
                ──────────▶│   │  + Horizon  │   └────────────────────┘   │
                           │   │  + scheduler│                            │
                           │   └─────┬───────┘                            │
                           │         │                                    │
                           │   ┌─────▼──────┐   ┌───────────────┐         │
                           │   │ coolify-db │   │ coolify-redis │         │
                           │   │ (Postgres) │   │ (queue+cache) │         │
                           │   └────────────┘   └───────────────┘         │
                           └──────────────────────┬───────────────────────┘
                                                  │ SSH (phpseclib, mux)
                              ┌───────────────────┼────────────────────┐
                              ▼                   ▼                    ▼
                       ┌────────────┐      ┌────────────┐      ┌────────────┐
                       │ Managed    │      │ Managed    │      │ Managed    │
                       │ server #1  │      │ server #2  │ ...  │ server #N  │
                       │  Docker +  │      │  Docker +  │      │  Docker +  │
                       │  proxy +   │      │  proxy +   │      │  proxy +   │
                       │  workloads │      │  workloads │      │  Sentinel  │
                       └────────────┘      └────────────┘      └────────────┘

The control-plane host can also be a managed server (the "localhost" destination), so a single-box install is fully functional.

2.2 Control-plane containers

Important

A single coolify container runs PHP-FPM, Horizon queue workers, and the Laravel scheduler together, orchestrated by s6-overlay service definitions (db-migration, init-seeder, horizon, scheduler-worker, nightwatch-agent). This is why the container does meaningful work even with no inbound requests.

2.3 Host data layout

All persistent state lives under /data/coolify (configurable via BASE_CONFIG_PATH) and is bind-mounted into the container:

2.4 Source-tree map

3. Requirements

4. Configuration Mastery

Coolify is configured through environment variables (read in config/*.php) plus instance settings stored in the database and editable from Settings. This section enumerates the configuration surface from source.

4.1 Core application (config/app.php)

Timezone is fixed to UTC at the app level; per-server timezones are stored in settings. Maintenance mode uses the cache driver backed by Redis.

4.2 Coolify constants (config/constants.php)

Pinned component versions (in-source): Coolify 4.1.1, helper 1.0.14, realtime 1.0.15, Railpack 0.23.0.

4.3 SSH tuning (config/constants.php → ssh)

Tip

If you see intermittent SSH or "command execution failed" errors on a flaky network, the retry knobs above give you exponential-backoff headroom. As a last resort, multiplexing can be disabled per server (or globally via ConfigurationRepository::disableSshMux()).

4.4 Database (config/database.php)

The default connection is PostgreSQL (coolify-db):

Read/write splitting is opt-in: set DB_READ_HOST (and optionally DB_WRITE_HOST, DB_READ_PORT, DB_STICKY) to route reads to replicas. Hosts may be comma-separated; Laravel random-picks one. When unset, behavior is identical to a single primary.

4.5 Redis, cache, and broadcasting

4.6 Queues and scheduler (config/horizon.php, config/constants.php)

Horizon trims recent jobs after 60 minutes and failed jobs after 7 days (10080 minutes). The Horizon dashboard is available at /horizon (web-guarded).

4.7 Mail (config/mail.php + ConfigurationRepository)

Mail is configured at runtime from instance settings, not just .env. Two paths:

• Resend — when resend_enabled, Coolify sets mail.default=resend and uses the configured resend_api_key.
• SMTP — when smtp_enabled, Coolify builds the SMTP mailer from smtp_host, smtp_port, smtp_username, smtp_password, smtp_encryption (tls/starttls/none), and smtp_from_*.

Configure these under Settings → Email.

4.8 Filesystems (config/filesystems.php)

4.9 API, rate limits, CORS

CORS (config/cors.php) allows all origins/methods/headers on api/* and sanctum/csrf-cookie with credentials disabled — tighten via a reverse proxy if you expose the API publicly.

4.10 Sentinel, proxy, and monitoring intervals

4.11 Authentication features (config/fortify.php)

Laravel Fortify provides authentication. Enabled features: registration, password reset, profile updates, password updates, and two-factor authentication (with password confirmation). Login throttling defaults to 5 attempts/min per email+IP. Email verification is available but commented off by default.

5. The Deployment Engine (Internals)

The heart of Coolify is app/Jobs/ApplicationDeploymentJob.php (~4,800 lines). It is a queued job (ShouldQueue, ShouldBeEncrypted) that runs on the deployment queue, with tries = 1 and a server-configurable timeout.

5.1 Lifecycle

1. Construct — load the ApplicationDeploymentQueue record, the Application, its settings, source (GitHub/GitLab/other), destination, and target server; compute container name, working directories, and flags (rollback, force-rebuild, restart-only, preview).
2. handle() —
   • Abort early if the deployment was cancelled.
   • Mark the queue row in_progress and record the worker host.
   • Verify the server is functional; fail fast if not.
   • Store the server's private key on disk and build a custom host↔IP map of sibling containers.
   • Select a build server if build-server mode is enabled (else build on the deploy server).
   • Detect BuildKit/buildx capabilities (and Docker build-secret support).
   • Dispatch to the right build path via decide_what_to_do().
3. finally — record finished_at, write deployment configuration, gracefully shut down the build container, and broadcast a status-changed event.

5.2 Build-path dispatch (decide_what_to_do())

After the build path, post_deployment() marks the deployment finished first (so status is correct even if side effects fail), refreshes container status, updates the PR status on GitHub, and runs the post-deployment command.

5.3 Build artifacts and capabilities

• Build scripts and plans live under /artifacts in the build container (build.sh, build-time.env, Nixpacks thegameplan.json).
• Railpack reads railpack.json from the repo and writes .coolify/railpack.generated.json.
• BuildKit is required for Docker ≥ 18.09; buildx is expected on Docker 24.0+. When build secrets are enabled and supported, secrets are passed via --secret rather than build args.

5.4 Health checks and rolling updates

The job starts the new container, polls the configured health check, and only cuts traffic over when healthy — otherwise it rolls back to the previous container. Pre- and post-deployment commands run inside designated containers and fail the deploy if the target container can't be found.

5.5 Other background jobs

6. Security

6.1 Authentication

• Session auth (web guard) for the dashboard, via Fortify, with optional two-factor authentication and rate-limited login.
• OAuth SSO via Socialite providers: Google, Microsoft/Azure, Authentik, Discord, Zitadel, Clerk, Infomaniak (configured in Settings → OAuth).
• API tokens via Laravel Sanctum (personal access tokens) for the REST API and MCP.

6.2 API authorization model

API routes (routes/api.php) are layered:

• auth:sanctum authenticates the token.
• ApiAllowed middleware enforces that the API is enabled for the instance.
• api.ability:{read|write|deploy} (custom ApiAbility middleware) gates each route by token ability.
• api.sensitive (ApiSensitiveData middleware) masks secret fields in responses unless permitted.
• The instance API can be toggled at runtime: GET /api/v1/enable / GET /api/v1/disable (write ability). The MCP server is toggled via POST /api/v1/mcp/enable / /disable.

Important

Treat API tokens like passwords. Scope them to the minimum ability (read for monitoring, deploy for CI that only triggers deploys, write only when managing resources). ApiTokenExpirationWarningJob proactively warns before tokens lapse.

6.3 Authorization (policies)

Every model has a Laravel Policy (app/Policies/): ApplicationPolicy, DatabasePolicy, ServerPolicy, ServicePolicy, ProjectPolicy, TeamPolicy, PrivateKeyPolicy, S3StoragePolicy, and more. Combined with team roles (member < admin < owner), these enforce who can view, create, update, or delete each resource. Web routes add guards like can.update.resource, can.create.resources, and can.access.terminal.

6.4 Secrets at rest

• The Laravel APP_KEY encrypts sensitive model attributes. Migrations explicitly encrypt existing private keys, ClickHouse admin passwords, and webhook secrets (e.g. EncryptExistingPrivateKeys, BackfillAndEncryptWebhookSecrets).
• Deployment jobs implement ShouldBeEncrypted, so queued payloads are encrypted in Redis.
• SSH private keys live on a private-visibility disk under storage/app/ssh/keys.

6.5 Input validation and SSRF protection

Custom validation rules (app/Rules/) defend the deployment surface: SafeExternalUrl, SafeWebhookUrl (SSRF guards), ValidGitRepositoryUrl, ValidGitBranch, DockerImageFormat, ValidServerIp, ValidIpOrCidr, ValidHostname, ValidDnsServers, ValidCloudInitYaml, and ValidProxyConfigFilename. The deployment job additionally validates path fields and Docker build targets against strict patterns and escapes shell arguments.

6.6 Transport security

• Automatic Let's Encrypt certificates via the proxy; renewals are managed (RegenerateSslCertJob). Custom CA certificates are supported for internal TLS (SslHelper, per-server CA cert).
• SSH to managed servers uses phpseclib with multiplexing and retry/backoff.
• Optional Cloudflare Tunnel per server avoids exposing inbound ports.
• HMAC-verified inbound webhooks (Git providers, Stripe).

Caution

The in-browser terminal grants real shell access to servers and containers. It is disabled per server by default (Server → Security → Terminal Access) and gated by CanAccessTerminal. Enable it only where every terminal-permitted user is trusted.

6.7 Malicious-input posture

Coolify deploys arbitrary user-supplied code and Compose files. Treat every managed server as capable of running untrusted workloads: isolate networks, apply resource limits, keep Docker patched, and avoid co-locating sensitive data on servers that run untrusted services.

7. Operations

7.1 Artisan / console commands (app/Console/Commands/)

Run inside the coolify container (docker exec -it coolify php artisan <command>):

7.2 Queue & scheduler operations

• Horizon runs under s6 inside the container; monitor it at /horizon. Workers autoscale between HORIZON_MIN_PROCESSES and HORIZON_MAX_PROCESSES by queue depth.
• The scheduler dispatches periodic work via ScheduledJobManager. Skips and runs are logged to storage/logs/scheduled-*.log and parsed by SchedulerLogParser for the Settings → Scheduled Jobs UI.
• CleanupApplicationDeploymentQueue / CleanupStuckedResources recover deployments and resources stuck in a transient state.

7.3 Backups

• Coolify's own metadata DB is backed up from Settings → Backup.
• Managed-database backups (DatabaseBackupJob) run on cron schedules, store locally and/or to S3, and record per-execution results downloadable from the UI.

7.4 Updating

• Settings → Updates triggers UpdateCoolifyJob; CheckForUpdatesJob polls versions.json. Auto-update is gated by AUTOUPDATE.
• Re-running the installer (curl … install.sh | bash) is the supported manual upgrade.
• Database migrations run automatically on boot when MIGRATION_ENABLED=true.

7.5 Monitoring

• Sentinel is an on-server agent that pushes container state and metrics to POST /api/v1/sentinel/push; CheckAndStartSentinelJob keeps it running and PushServerUpdateJob is force-dispatched at least every SENTINEL_PUSH_FORCE_INTERVAL_SECONDS.
• Server CPU/memory/disk charts come from Sentinel. ServerStorageCheckJob watches disk; ServerPatchCheckJob surfaces OS updates.
• Optional Sentry error reporting (SENTRY_DSN) and Nightwatch (NIGHTWATCH_ENABLED).

7.6 Container status semantics

ContainerStatusAggregator (a priority state machine) collapses many container states into one string (running:healthy, degraded:unhealthy, starting:unknown, paused:unknown, exited, …). Highest priority wins: degraded → restarting → crash-loop (exited with restarts) → mixed running/exited → mixed running/starting → running (by health) → dead → paused → starting → exited. Understanding this helps interpret the dashboard's status badges.

8. Data Model Reference

Coolify's domain is a set of Eloquent models, most extending a BaseModel that adds UUIDs and team scoping.

8.1 Core entities

8.2 Key enumerations (app/Enums/)

8.3 Application configuration model

app/Services/ConfigurationGenerator.php exports an application's full config (and is the best single reference for what an Application stores): build settings (build_pack, static_image, base_directory, publish_directory, dockerfile*, docker_compose*, install/build/start_command, watch_paths), source (git_repository, git_branch, git_commit_sha), domains (fqdn, ports_exposes, ports_mappings, redirect, custom_nginx_configuration), environment variables (production + preview), health-check fields, pre/post-deployment commands, per-provider webhook secrets, resource limits, and Swarm settings. This config is serialized to JSON/YAML and written alongside each deployment.

9. REST API Reference (Admin View)

Base: /api/v1. Auth: Authorization: Bearer <token> (Sanctum). Abilities: read, write, deploy.

A full OpenAPI specification is generated by the instance (zircote/swagger-php) and served for client generation. Unknown API paths return 404 with a pointer to https://coolify.io/docs.

Note

Webhook receivers live outside /api/v1 (routes/webhooks.php): /source/{github,gitlab,bitbucket,gitea}/events[...] for Git auto-deploy, and /payments/stripe/events for cloud billing.

10. Troubleshooting (Operator View)

Server is not functional.

Validation failed or connectivity dropped. Re-run Validate & Install; confirm SSH credentials, Docker ≥ 24.0, and that the proxy container is up. Check ServerConnectionCheckJob results and server reachability notifications.

Command execution failed (exit code N): … Error: …

A remote SSH command failed during deployment (raised by ExecuteRemoteCommand). The redacted command and stderr are logged. Inspect server load/disk, then tune SSH retries (SSH_MAX_RETRIES, backoff) for flaky links.

Deployment stuck in_progress

Run php artisan cleanup:stucked-resources (and cleanup:deployment-queue). Check Horizon (/horizon) for failed/long jobs and confirm HORIZON_ENABLED=true.

StandaloneDocker with id=0 is required before running … Seeder

A required base destination is missing (typically a fresh/partial install). Ensure seeders ran (SEEDER_ENABLED=true) and re-run php artisan app:init.

Realtime/terminal not connecting

Verify the coolify-realtime container is healthy on :6001/:6002, that PUSHER_* values match across containers, and that ports are reachable. The terminal also requires per-server Terminal Access to be enabled.

Emails not sending

Confirm SMTP or Resend is configured in Settings → Email; test with the emails artisan command. SMTP encryption must be one of tls/starttls/none.

Disk filling on a server

Build caches and old images accumulate. Run/schedule Docker Cleanup (DockerCleanupJob); ServerStorageCheckJob reports usage. Consider a dedicated build server.

After upgrade, UI is blank with a yellow loading bar

Stale front-end assets. Hard-refresh the browser; if needed restart the coolify container so assets are republished.

11. Quick Reference

Containers

coolify (app + Horizon + scheduler, s6) · coolify-db (Postgres) · coolify-redis (queue+cache) · coolify-realtime (websockets+terminal)

Key paths

/data/coolify/{source/.env, ssh, applications, databases, services, backups}

Required env

APP_KEY, APP_ID, DB_USERNAME, DB_PASSWORD, REDIS_PASSWORD, PUSHER_APP_{ID,KEY,SECRET}

Ports

8000 dashboard/API · 6001/6002 realtime/terminal · 80/443 workloads

Essential commands

# Health
curl http://127.0.0.1:8000/api/health
# Recover root
docker exec -it coolify php artisan root:reset-password
# Inspect scheduler
docker exec -it coolify php artisan scheduled-job:diagnostics
# Unstick deployments
docker exec -it coolify php artisan cleanup:stucked-resources
# Refresh service catalog
docker exec -it coolify php artisan update:service-versions

Dashboards

/ dashboard · /horizon queues · /admin instance admin · /mcp AI agent endpoint (when enabled)

Build packs

nixpacks (default) · railpack (needs buildx) · dockerfile · dockercompose · static (nginx:alpine) · dockerimage

Proxies

TRAEFIK (default) · CADDY · NGINX · NONE

Databases

PostgreSQL · MySQL · MariaDB · MongoDB · Redis · KeyDB · Dragonfly · ClickHouse