Jesse A. Green / notebook

Live demo: the DocCompiler guide library as a static, read-only snapshot (October 2026). No backend, no accounts, nothing to submit.

Coolify User Guide

Generated June 2026 from coollabsio/coolify at 5a27427

AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it.

Coolify is an open-source, self-hostable platform for deploying and managing applications, databases, and services on your own servers. It gives you the convenience of a managed platform like Heroku, Netlify, or Vercel — Git-push deployments, one-click databases, automatic HTTPS, preview environments — while keeping everything on infrastructure you own and control. There is no usage-based billing, no vendor lock-in, and no limit on the number of servers or applications you can manage.

This guide walks you through everything you can do with Coolify: installing it, connecting servers, deploying applications from Git, spinning up databases and pre-packaged services, configuring domains and SSL, scheduling backups and tasks, and driving the whole platform through its REST API. Architecture, configuration internals, and operational hardening live in the companion Admin Guide.

Note

Coolify is licensed under Apache-2.0 and built on PHP 8.4, Laravel 12, and Livewire. It manages your servers over SSH and runs your workloads as Docker containers. You never need to learn Laravel or write PHP to use it.


1. Quick Start

The fastest path from zero to a running application is: install Coolify on a server, point it at a server to deploy onto (the same one is fine), connect a Git repository, and click Deploy.

1.1 Install Coolify

On a fresh Linux server with root (or sudo) SSH access and Docker 24.0 or newer, run the official installer:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

The installer pulls and starts the Coolify stack with Docker Compose. When it finishes, open the URL it prints (your server's IP on port 8000):

http://<your-server-ip>:8000

Important

The installer is also the upgrade mechanism. Coolify stores all of its persistent data under /data/coolify on the host, and runs as a set of Docker containers (coolify, coolify-db, coolify-redis, coolify-realtime). See the Installation section for the exact requirements and a manual Docker Compose alternative.

1.2 Create the first (root) account

The first time you load the dashboard, Coolify asks you to register. The first registered user becomes the root user and instance owner. After registration you are guided through a short onboarding flow that helps you add your first server and create your first project.

Tip

Registration is open by default so you can create the root account. After you have your account, you can disable public registration in Settings so no one else can sign up on your instance.

1.3 Deploy your first application

  1. From the dashboard, create a Project (a logical grouping, e.g. "My Apps").
  2. Inside the project, open the default Environment (e.g. production) and click + New to add a resource.
  3. Choose Public Repository, paste a Git URL (for example a small Node, Python, or static site), and pick a branch.
  4. Coolify auto-detects a build pack (Nixpacks by default). Set the port your app listens on and, optionally, a domain.
  5. Click Deploy.

Coolify clones the repository on the target server, builds an image, starts the container behind its reverse proxy, and — if you set a domain — requests a Let's Encrypt certificate automatically. Watch the live build log stream in the deployment view.

Starting deployment of my-app to my-server.
...
New container is healthy.
Deployment finished. 🎉

Note

You can deploy to the same server that runs Coolify (the "localhost" destination created during onboarding) or to any number of additional remote servers you connect later.


2. Core Concepts

Coolify organizes everything into a small set of objects. Understanding them makes the rest of the platform intuitive.

Concept What it is
Server A machine Coolify manages over SSH. Coolify installs Docker tooling and a reverse proxy on it and runs your workloads there.
Project A top-level container for your work. Holds one or more environments.
Environment A namespace inside a project (e.g. production, staging). Holds the actual resources.
Resource Anything you deploy: an Application, a Database, or a Service.
Application Code deployed from Git, a Dockerfile, or a Docker image, built with a build pack.
Database A managed standalone database (PostgreSQL, MySQL, MariaDB, MongoDB, Redis, KeyDB, Dragonfly, or ClickHouse).
Service A pre-packaged, multi-container application from the one-click catalog (e.g. WordPress, n8n, Supabase) or a custom Docker Compose stack.
Destination The Docker context (network) on a server where a resource runs. Most setups use the default Standalone Docker destination.
Team A group of users who share access to servers and resources. Roles are member, admin, and owner.
Private Key An SSH key Coolify uses to connect to a server or to clone a private Git repository.
Source A connected Git provider (GitHub App, GitLab, Bitbucket, Gitea) used for repository access and webhooks.

Tip

The path you see in the browser mirrors this hierarchy: project → environment → application/database/service. Resources are always scoped to a team, so switching teams changes everything you see.


3. Installation

3.1 Requirements

Requirement Detail
Operating system A 64-bit Linux server you control (a fresh VPS or bare-metal host).
Privileges root or passwordless sudo SSH access.
Docker 24.0 or newer (the installer sets this up if missing).
Open ports 8000 (dashboard), 6001/6002 (real-time/terminal), plus 80/443 for your deployed apps' HTTP/HTTPS traffic.
Resources A small VPS (2 vCPU / 2 GB RAM) is enough to start; size up for heavier workloads.

Caution

Install Coolify on a dedicated server whenever possible. It takes over the host's Docker, manages a reverse proxy, and writes to /data/coolify. Avoid installing it on a machine that already runs unrelated production workloads.

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

This downloads the Coolify images from ghcr.io, writes configuration and persistent data to /data/coolify, and starts the stack. Re-running the same command upgrades an existing installation.

3.3 Manual install with Docker Compose

If you prefer to provision Coolify yourself, it runs from a production Compose file. The services and their persistent paths are:

services:
  coolify:        # the Laravel app (dashboard + API), served on :8000
    image: "ghcr.io/coollabsio/coolify:latest"
    volumes:
      - /data/coolify/source/.env:/var/www/html/.env
      - /data/coolify/ssh:/var/www/html/storage/app/ssh
      - /data/coolify/applications:/var/www/html/storage/app/applications
      - /data/coolify/databases:/var/www/html/storage/app/databases
      - /data/coolify/services:/var/www/html/storage/app/services
      - /data/coolify/backups:/var/www/html/storage/app/backups
  postgres:       # coolify-db: Coolify's own metadata database
  redis:          # coolify-redis: queue + cache
  soketi:         # coolify-realtime: websockets + the in-browser terminal
    image: "ghcr.io/coollabsio/coolify-realtime:1.0.15"

You must supply a /data/coolify/source/.env file with at least APP_KEY, APP_ID, DB_USERNAME, DB_PASSWORD, REDIS_PASSWORD, and the PUSHER_APP_* values. The Admin Guide documents every environment variable in full.

Note

A Windows-specific Compose file (docker-compose.windows.yml) exists for running the Coolify control plane on Docker Desktop for local evaluation. It is not intended for production hosting.

3.4 Verify the installation

Coolify exposes an unauthenticated health endpoint. Check it from the server:

curl http://127.0.0.1:8000/api/health
OK

If the dashboard loads and the health check returns OK, your installation is healthy.


4. Connecting Servers

Coolify deploys workloads onto servers it reaches over SSH. The server running Coolify is added automatically during onboarding; you can add as many more as you like.

4.1 Add a server

  1. Go to Servers → + Add.
  2. Enter the server's IP address, SSH port (default 22), and SSH user (typically root).
  3. Provide a Private Key. You can create a new key pair in Coolify (Security → Private Keys) and add the matching public key to the server's ~/.ssh/authorized_keys, or paste an existing private key.
  4. Click Validate & Install. Coolify connects over SSH, verifies Docker, and installs its reverse proxy and helper tooling.

Important

The SSH user must be able to run Docker. root is the simplest choice. Coolify needs Docker 24.0+ on every managed server, not just the one running Coolify itself.

4.2 What "Validate & Install" does

When you validate a server, Coolify:

  • Confirms SSH connectivity and the Docker version.
  • Creates the coolify Docker network.
  • Installs and starts the reverse proxy (Traefik by default).
  • Marks the server functional so it can accept deployments.

A server must be functional before any deployment will run against it. If a deployment reports Server is not functional, re-run validation from the server's page.

4.3 Server management features

Each server page exposes a rich set of operational tools:

Tab What you can do
General / Advanced Edit connection details, server name, wildcard domain, and timeouts.
Proxy Choose and configure the reverse proxy (Traefik, Caddy, or none), edit dynamic configuration, and view proxy logs.
Destinations Manage the Docker networks workloads deploy into.
Resources See every application, database, and service running on this server.
Metrics View CPU, memory, and disk charts (powered by the on-server Sentinel agent).
Sentinel Enable/configure the metrics + container-state agent.
Private Key Change the SSH key used to reach the server.
CA Certificate Manage a custom certificate authority for internal TLS.
Cloudflare Tunnel Connect the server through a Cloudflare Tunnel instead of exposing ports.
Log Drains Forward container logs to an external collector.
Docker Cleanup Run or schedule pruning of unused images, containers, and volumes.
Security → Patches View and apply OS package updates.
Security → Terminal Access Enable the in-browser terminal for this server.
Danger Remove the server from Coolify.

Tip

Provisioning a brand-new server from a cloud provider? Coolify can create Hetzner Cloud servers directly — see Provisioning cloud servers.

4.4 Reverse proxy and SSL

Coolify runs a reverse proxy on each server to route traffic to your containers and to terminate TLS.

  • Traefik is the default proxy and handles automatic Let's Encrypt certificates.
  • Caddy and Nginx are also supported; you can also choose none if you manage routing yourself.
  • When you assign a domain (FQDN) to an application or service, Coolify configures the proxy and requests a certificate automatically. Certificates renew on their own, and you can also use a custom CA certificate for private/internal hosts.

Note

Docker Swarm support exists but is deprecated and will be removed in Coolify v5. Existing Swarm deployments keep working on v4, but new multi-server setups should use standard servers rather than Swarm.

4.5 Multiple servers and build servers

You can deploy a single application across multiple servers, and you can designate dedicated build servers so that resource-intensive image builds run on a separate machine from the one serving traffic. When build-server mode is enabled for an application, Coolify picks an available build server, builds there, and ships the resulting image to the deployment server. If no build server is available, it falls back to building on the deployment server.

4.6 Provisioning cloud servers (Hetzner)

Coolify integrates with the Hetzner Cloud API so you can create servers without leaving the dashboard:

  1. Add a Cloud Provider Token (Security → Cloud Tokens) containing your Hetzner API token.
  2. When adding a server, choose to provision a new Hetzner server. Coolify lists available locations, server types, and images, uploads an SSH key, and creates the machine.
  3. Optionally attach a Cloud-init Script (Security → Cloud-init Scripts) to run first-boot setup.

The new server is then validated and installed like any other.


5. Deploying Applications

Applications are code that Coolify builds and runs for you. The source can be a public or private Git repository, a raw Dockerfile, or a pre-built Docker image.

5.1 Application source types

When you create a new application, pick the source that matches your code:

Source type Use when
Public Repository The code is in a public Git repo; no credentials needed.
Private Repository (GitHub App) Private GitHub repos, with automatic webhooks and PR previews via a GitHub App.
Private Repository (Deploy Key) Private repos on any provider, authenticated with an SSH deploy key.
Dockerfile You provide a Dockerfile (inline or in the repo) and Coolify builds it.
Docker Image Deploy an existing image from a registry (e.g. nginx:alpine), no build step.

5.2 Build packs

A build pack decides how your source becomes a running container. Coolify supports six:

Build pack How it builds Best for
Nixpacks Auto-detects the language/framework and builds an image with no Dockerfile (the default). Most apps — Node, Python, Go, Ruby, PHP, etc.
Railpack Newer auto-build system (requires the Docker buildx plugin on the build server). Apps where you want Railpack's build behavior.
Dockerfile Builds from a Dockerfile you provide. Full control over the build.
Docker Compose Deploys a multi-container app defined by a docker-compose.yaml in your repo. Apps that ship their own Compose file.
Static Builds the app, then serves the output directory with nginx:alpine. Static sites and SPA front-ends.
Docker Image Pulls and runs an existing image — no build. Deploying released images directly.

Warning

The Railpack build pack requires the Docker buildx CLI plugin on the build server. If it is missing, the deployment fails with Railpack deployments require the Docker buildx CLI plugin on the build server. Install or enable buildx and retry.

Caution

If you choose Nixpacks but your code can't be auto-detected, the deployment fails with Nixpacks failed to detect the application type. Either add the files Nixpacks expects for your stack, or switch to the Dockerfile build pack and provide your own build instructions.

5.3 Configuring an application

Each application has a configuration page organized into tabs. The most-used settings:

Setting group What it controls
General Name, description, build pack, branch, ports exposed, and the public domain (FQDN).
Source The Git repository, branch, and commit, or the Docker image.
Build Base directory, publish directory, install/build/start commands, custom Dockerfile location, Compose file location, and build target.
Environment Variables Runtime and build-time variables, including multiline and "build-only" variables and secrets.
Persistent Storage Volumes and bind mounts that survive redeploys.
Servers Which server(s) the app deploys to.
Domains The FQDN, port mappings, and www/non-www redirect behavior.
Healthcheck Path, port, interval, timeout, retries, expected status code, and start period.
Resource Limits CPU and memory limits for the container.
Pre/Post Deployment Commands to run in a container before or after each deploy.
Scheduled Tasks Cron-style commands run inside the app container.
Webhooks Manual deploy webhook URLs and per-provider secrets.
Preview Deployments Settings for ephemeral per-pull-request environments.
Rollback Redeploy a previous image.
Tags Labels for grouping and bulk actions.
Danger Stop or delete the application.

Tip

Mark sensitive environment variables as secrets. When the build server supports Docker build secrets, Coolify passes them using BuildKit's --secret mechanism instead of plain build arguments, keeping them out of image layers.

5.4 Environment variables

Coolify distinguishes several kinds of variables:

  • Runtime variables — available to the running container.
  • Build-time variables — available during the image build (written to a build-time env file).
  • Preview variables — used only for preview (pull-request) deployments.
  • Multiline variables — for values like certificates or JSON blobs.
  • Shared variables — defined once and reused across many resources (see Shared Variables).

You can edit variables one at a time or paste many at once with the bulk editor.

5.5 Domains, ports, and redirects

  • Set one or more FQDNs (e.g. https://app.example.com) on the application. Coolify configures the proxy and provisions TLS.
  • Ports exposed tells Coolify which container port serves traffic.
  • Port mappings publish container ports directly on the host (for non-HTTP services).
  • Redirect controls whether www and non-www both resolve, or one redirects to the other.
  • For finer control you can supply custom Nginx configuration per application.

5.6 Health checks and zero-downtime deploys

When a health check is configured, Coolify starts the new container, waits for it to report healthy, and only then switches traffic to it (a rolling update). If the new container never becomes healthy, the deploy fails and your old version keeps serving traffic.

New container is not healthy, rolling back to the old container.

Important

A correct health check is what makes deploys safe. Point it at a lightweight endpoint your app actually serves (e.g. /health or /), and give slow-starting apps a generous start period so they aren't marked unhealthy while still booting.

5.7 Triggering deployments

You can deploy an application in several ways:

  • Manually — click Deploy (or Redeploy) in the dashboard.
  • On Git push — connect a Git source so a push to the tracked branch auto-deploys (see Git integrations).
  • Via webhook — call the application's manual deploy webhook URL.
  • Via the API — POST /api/v1/deploy or POST /api/v1/applications/{uuid}/start (see Using the API).

5.8 Preview deployments

For GitHub-based applications, Coolify can create a preview deployment for each open pull request: a fully isolated copy of your app at its own generated domain, with its own preview environment variables. Previews update as the PR receives new commits and are torn down when the PR closes.

Note

Preview auto-triggering depends on receiving PR webhook events from your Git provider. If previews don't appear automatically, confirm the GitHub App webhook is configured and reaching your instance.

5.9 Logs, terminal, and rollback

  • Logs — stream live container logs from the application's Logs tab.
  • Terminal — open an interactive shell inside the running container (the in-browser terminal must be enabled for the server).
  • Rollback — redeploy any previously built image from the Rollback tab to revert instantly.

6. Managing Databases

Coolify runs managed, standalone databases as Docker containers with persistent storage, scheduled backups, and one-click lifecycle controls.

6.1 Supported database engines

Engine Notes
PostgreSQL Full-featured relational database.
MySQL Popular relational database.
MariaDB MySQL-compatible relational database.
MongoDB Document database.
Redis In-memory key/value store.
KeyDB Multithreaded Redis-compatible store.
Dragonfly Modern Redis/Memcached-compatible store.
ClickHouse Columnar analytics database.

6.2 Create a database

  1. In an environment, click + New → Database and pick an engine.
  2. Set the name, image/version, and credentials (Coolify can generate secure defaults).
  3. Choose the server/destination and click Start.

Coolify generates the connection details and exposes them on the database page. By default a database is reachable only on the internal Docker network; you can optionally make it publicly accessible on a mapped port.

6.3 Backups

Each database supports scheduled backups with a cron expression:

  • Store backups locally on the server and/or push them to S3-compatible storage.
  • Browse backup executions and download individual backups from the dashboard.
  • Restore from a previous backup or import an external dump.

Tip

Configure an S3 storage target (Storages) and enable "save to S3" on the backup schedule so your data survives even if the database server is lost. You can disable local copies entirely to save disk.

6.4 Lifecycle and configuration

From a database page you can Start, Stop, and Restart it; edit environment variables; manage persistent storage; attach the in-browser terminal; view logs and metrics; set resource limits; and configure backups. The Danger tab deletes the database and (optionally) its volumes.


7. Git Integrations and Auto-Deploy

Connecting a Git provider unlocks private repository access, automatic deployments on push, and (for GitHub) pull-request previews.

7.1 Supported providers

Provider Capabilities
GitHub Full GitHub App integration: private repos, push auto-deploy, and PR previews. Manual webhooks also supported.
GitLab Repository access and commit-triggered deploys via webhooks.
Bitbucket Repository access and webhook-triggered deploys.
Gitea / Forgejo Repository access and webhook-triggered deploys.

7.2 Connect a GitHub App

  1. Go to Sources and create a GitHub App connection.
  2. Follow the redirect to GitHub to install the app and grant it access to the repositories you want to deploy.
  3. Back in Coolify, the app's repositories and branches become selectable when creating private-repo applications.

Once connected, a push to a tracked branch triggers a deployment automatically, and opening a pull request can create a preview deployment.

7.3 Manual webhooks

If you'd rather not install an app, every application also exposes manual deploy webhook endpoints with per-provider secrets (GitHub, GitLab, Bitbucket, Gitea). Add the webhook URL to your repository's settings, and Coolify deploys when it receives a push event.

Note

GitLab commit-triggered deployments and GitHub PR previews both rely on the provider being able to reach your Coolify instance over the network. If auto-deploys aren't firing, verify the webhook is configured on the provider and that your instance is reachable.


8. One-Click Services

Beyond your own code, Coolify ships a catalog of 360+ ready-to-deploy services — popular open-source applications packaged as Docker Compose stacks with sensible defaults. Deploy them in a few clicks with domains and persistent storage handled for you.

8.1 Deploying a service

  1. In an environment, click + New → Service.
  2. Search the catalog and select an application.
  3. Set a domain and adjust any exposed environment variables.
  4. Click Deploy.

Coolify pulls the images, wires up the containers, configures the proxy and SSL, and starts the stack.

8.2 What's in the catalog

The catalog spans many categories. A small sample of the 360+ available services:

Category Examples
Content & wikis WordPress, Ghost, BookStack, WikiJS, Docmost, Outline
Developer tools Gitea, Forgejo, GitLab, Jenkins, SonarQube, code-server, Coder
Databases & data Supabase, NocoDB, Metabase, Appsmith, Directus, ClickHouse-backed tools
Automation & AI n8n, Activepieces, Flowise, LangFuse, Open WebUI, Ollama, LibreChat
Monitoring & analytics Uptime Kuma, Grafana, Plausible, Umami, PostHog, SigNoz, Glitchtip
Productivity & self-host staples Nextcloud, Vaultwarden, Immich, Paperless, Mealie, Homepage, Dashy
Communication Mattermost, Rocket.Chat, Matrix Synapse, Chatwoot

Tip

Many services offer database variants (e.g. WordPress with MariaDB vs with MySQL, Nextcloud with PostgreSQL). Pick the variant that matches your preference; Coolify provisions the bundled database for you.

8.3 Custom Docker Compose stacks

Not in the catalog? Choose Docker Compose and paste your own docker-compose.yaml. Coolify parses it, applies its domain/SSL conventions through labels, and manages the stack like any other service — including per-service logs, terminals, and (for database services) backups.


9. Scheduled Tasks

Coolify can run scheduled tasks — cron-style commands executed inside an application or service container.

  1. Open the resource's Scheduled Tasks tab.
  2. Add a task with a name, the command to run, the target container, and a cron expression (e.g. 0 2 * * * for 2 a.m. daily).
  3. Coolify runs the command on schedule and records each execution with its output.

Use scheduled tasks for cache warming, cleanup jobs, report generation, or any periodic maintenance your app needs. Review past runs and their logs from the same tab.


10. Shared Variables

Shared (reusable) environment variables let you define a value once and apply it across many resources. They are scoped at four levels:

Scope Applies to
Team Every resource owned by the team.
Project Every resource in the project.
Environment Every resource in a specific environment.
Server Every resource on a specific server.

Define shared variables under Shared Variables, then reference them from a resource's environment variables. This keeps common settings (API keys, region names, feature flags) consistent and editable in one place.


11. Notifications

Coolify can notify you about deployments, backups, server health, SSL expirations, and more across several channels:

Channel Configure under
Email Notifications → Email (uses your SMTP or Resend settings)
Discord Notifications → Discord (webhook URL)
Slack Notifications → Slack
Telegram Notifications → Telegram (bot token + chat)
Pushover Notifications → Pushover
Webhook Notifications → Webhook (POST to your own endpoint)

For each channel you choose which events trigger a notification (e.g. deployment success/failure, backup status, server unreachable). Email delivery requires configuring SMTP or Resend in Settings → Email.

Tip

At minimum, enable deployment failure and server unreachable notifications on a channel you actually watch. These are the alerts that need a human quickly.


12. Using the REST API

Everything you can do in the dashboard you can also do through Coolify's versioned REST API at /api/v1. This is ideal for CI/CD pipelines and infrastructure-as-code.

12.1 Authentication and tokens

The API uses bearer tokens (Laravel Sanctum). Create one under Security → API Tokens, then send it as a header:

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     https://<your-coolify>/api/v1/version

Tokens carry abilities that gate what they can do:

Ability Grants
read Read-only access (list/get).
write Create, update, and delete resources.
deploy Trigger and cancel deployments and start/stop resources.

Important

The API must be enabled for your instance. A token with write ability can toggle it via GET /api/v1/enable and GET /api/v1/disable. Some responses redact sensitive fields unless the request passes the instance's sensitive-data policy.

12.2 Health and version

# Unauthenticated health check
curl https://<your-coolify>/api/v1/health
OK
# Authenticated version check
curl -H "Authorization: Bearer <TOKEN>" https://<your-coolify>/api/v1/version

12.3 Common endpoints

Method Path Purpose
GET /api/v1/teams, /teams/current, /teams/current/members Team info
GET/POST/PATCH/DELETE /api/v1/projects, /projects/{uuid} Manage projects and environments
GET /api/v1/servers, /servers/{uuid}/resources, /servers/{uuid}/domains Inspect servers
POST /api/v1/servers, /servers/hetzner Add or provision a server
GET/POST /api/v1/applications, /applications/public, /applications/dockerfile, /applications/dockerimage List/create applications
POST /api/v1/applications/{uuid}/start | /restart | /stop Control an application
GET/POST /api/v1/applications/{uuid}/envs Manage env vars
GET/POST /api/v1/databases, /databases/postgresql (and per-engine) List/create databases
POST /api/v1/databases/{uuid}/backups Schedule a backup
GET/POST /api/v1/services List/create services
POST /api/v1/deploy Trigger a deployment by tag or UUID
GET /api/v1/deployments, /deployments/{uuid} Inspect deployments
POST /api/v1/deployments/{uuid}/cancel Cancel a running deployment
GET/POST /api/v1/security/keys Manage SSH private keys
GET /api/v1/resources List all resources

12.4 Example: deploy an application from CI

curl -X POST "https://<your-coolify>/api/v1/applications/<APP_UUID>/start" \
     -H "Authorization: Bearer <TOKEN_WITH_DEPLOY>"
{"message":"Deployment request queued.","deployment_uuid":"..."}

Poll the returned deployment UUID for status:

curl -H "Authorization: Bearer <TOKEN>" \
     "https://<your-coolify>/api/v1/deployments/<DEPLOYMENT_UUID>"

Tip

The full request/response schema for every endpoint is published as an OpenAPI specification by your instance. Point any OpenAPI tool at it to generate client code or browse the API interactively.

12.5 AI agents (MCP)

Coolify can also expose a Model Context Protocol (MCP) server at /mcp, letting AI agents manage your instance with a Sanctum token. It is disabled by default and toggled via POST /api/v1/mcp/enable and POST /api/v1/mcp/disable (requires a write token).


13. The In-Browser Terminal

Coolify includes a real-time, in-browser terminal (powered by the coolify-realtime service) so you can run commands without a separate SSH client:

  • Server terminal — a shell on a managed server.
  • Container terminal — a shell inside a running application, database, or service container.

The terminal must be enabled per server (Server → Security → Terminal Access), and access is governed by your team role.

Caution

The terminal grants real shell access to your servers and containers. Enable it only for servers where you trust everyone with terminal permission, and prefer the member role for users who shouldn't have it.


14. Teams, Users, and Roles

Coolify is multi-tenant through teams. Every server and resource belongs to a team, and you switch context by switching teams.

Role Can do
Owner Everything, including billing/subscription and deleting the team.
Admin Manage resources, servers, and members; cannot perform owner-only actions.
Member Use and view resources according to per-action permissions.

Invite teammates from Team → Members (an invitation link is generated and expires after a few days). Manage your own login, password, and two-factor authentication from Profile.

14.1 Sign-in options

  • Email + password (with optional two-factor authentication).
  • OAuth single sign-on via providers including Google, Microsoft/Azure, Authentik, Discord, Zitadel, Clerk, and Infomaniak — configured by an admin in Settings → OAuth.

15. Maintenance and Housekeeping

Task Where
Update Coolify Settings → Updates (or re-run the install script). Auto-update can be enabled.
Docker cleanup Server → Docker Cleanup — prune unused images/containers/volumes, on demand or scheduled.
Scheduled platform jobs Settings → Scheduled Jobs — view Coolify's own background jobs and diagnostics.
Backups Settings → Backup — back up Coolify's own metadata database.
Changelog The dashboard surfaces a changelog of new versions and features.

Tip

Enable scheduled Docker cleanup on busy servers. Build caches and old images accumulate quickly and can fill the disk, which causes deployments to fail with out-of-space errors.


16. Troubleshooting

Each entry lists the exact message you'll see, the likely cause, the fix, and how to prevent it.

Error: Server is not functional.

  • Cause: The target server failed validation or lost connectivity — bad SSH key, wrong user/port, Docker not running, or the proxy not installed.
  • Solution: Open the server page and click Validate & Install again. Verify SSH details and that Docker 24.0+ is running on the host.
  • Prevention: Use a stable SSH key, keep Docker updated, and watch server unreachable notifications.

Error: Unsupported build pack: {build_pack}

  • Cause: The application's build pack value is unset or invalid.
  • Solution: Open the application's General tab and choose a valid build pack (Nixpacks, Railpack, Dockerfile, Docker Compose, Static, or Docker Image).
  • Prevention: Always confirm the auto-detected build pack before the first deploy.

Error: Nixpacks failed to detect the application type.

  • Cause: Nixpacks couldn't recognize your stack (missing manifest like package.json, requirements.txt, etc.).
  • Solution: Ensure your project has the files Nixpacks expects, or switch to the Dockerfile build pack and supply your own build steps.
  • Prevention: Deploy from the repository root (set the correct base directory) so detection files are visible.

Error: Railpack deployments require the Docker buildx CLI plugin on the build server.

  • Cause: The Railpack build pack needs Docker buildx, which isn't installed on the build server.
  • Solution: Install/enable the docker buildx plugin on that server and redeploy, or switch build packs.
  • Prevention: Re-validate servers after major Docker changes so capabilities are re-detected.

Error: Docker config file (~/.docker/config.json) not found on the build server.

  • Cause: Pulling from or pushing to a private registry requires a Docker login on the build server.
  • Solution: Run docker login on the build server (or configure registry credentials) so ~/.docker/config.json exists.
  • Prevention: Configure registry authentication before deploying private images.

Error: Health check failed (...) / Rolling update failed (...)

  • Cause: The new container never became healthy, so Coolify kept the old version running.
  • Solution: Check the application logs, confirm the health-check path/port are correct, and increase the start period for slow-booting apps.
  • Prevention: Point health checks at a real, fast endpoint and test them before relying on auto-deploys.

Error: Private key not found. Please add a private key to the application and try again.

  • Cause: The application (or its server) has no SSH key to clone the repo or reach the host.
  • Solution: Add a private key under Security → Private Keys and attach it to the server/application.
  • Prevention: Create and assign keys during setup; keep at least one valid key per server.

Error: Your deploy key does not have access to the repository.

  • Cause: The deploy key isn't authorized on the Git provider for that repository.
  • Solution: Add the public half of the deploy key to the repository's deploy-keys settings, or use a GitHub App source instead.
  • Prevention: Verify repository access immediately after adding a private-repo application.

Error: Repository does not exist. Please check your repository URL and try again.

  • Cause: Wrong repository URL, or the repo is private and the source lacks access.
  • Solution: Double-check the URL and branch; for private repos connect a GitHub App or deploy key.
  • Prevention: Test with a public repo first to confirm connectivity.

Error: Docker Compose file not found at: ... (branch: ...)

  • Cause: Coolify can't find the Compose file at the configured path/branch, or the extension is wrong (.yml vs .yaml).
  • Solution: Correct the Docker Compose location and branch in the application's Build settings and confirm the file's extension.
  • Prevention: Keep the Compose path setting in sync with your repository layout.

Error: Deployment cancelled by user

  • Cause: Someone clicked Cancel (or called the cancel API) during the deployment.
  • Solution: Redeploy when ready. This is informational, not a failure of your app.
  • Prevention: N/A — this is expected behavior.

Issue: Page goes blank with a yellow loading bar after an update

  • Cause: Cached front-end assets can become stale after a Coolify upgrade.
  • Solution: Hard-refresh the browser (clear cache) after updating. If it persists, restart the coolify container.
  • Prevention: Hard-refresh once after every Coolify update.

Issue: Deploying a large repository sometimes fails

  • Cause: Large clones/builds can exceed timeouts or exhaust disk/memory on the build server.
  • Solution: Use a dedicated build server, raise the server's deployment timeout, and ensure adequate disk (run Docker cleanup).
  • Prevention: Keep build caches pruned and size build servers for your largest repo.

Issue: Build cache volume grows indefinitely

  • Cause: BuildKit/Railpack build caches accumulate over time.
  • Solution: Run Docker Cleanup on the server to prune build caches and unused images.
  • Prevention: Schedule regular Docker cleanup on build servers.

17. Frequently Asked Questions

Q: Is Coolify free? Yes. Coolify is open source under the Apache-2.0 license and free to self-host with no limits on servers, applications, or users. (A paid hosted/cloud option exists for those who don't want to run the control plane themselves, but self-hosting is fully featured.)

Q: Do I need to know Laravel or PHP to use it? No. Coolify is built with Laravel internally, but you operate it entirely through the dashboard and API. You deploy your own apps in whatever language you like.

Q: Can I deploy to the same server that runs Coolify? Yes. Onboarding creates a "localhost" destination so you can deploy to the Coolify host itself. For production, dedicating separate servers is recommended.

Q: How does automatic HTTPS work? Coolify runs a reverse proxy (Traefik by default) that requests and renews Let's Encrypt certificates automatically when you assign a domain to a resource. Caddy and Nginx are also supported, and you can use a custom CA for internal hosts.

Q: Which databases can Coolify manage? PostgreSQL, MySQL, MariaDB, MongoDB, Redis, KeyDB, Dragonfly, and ClickHouse — each with scheduled local and S3 backups.

Q: How many one-click services are there? Over 360 service templates ship in the catalog, and you can deploy any custom Docker Compose stack on top of that.

Q: How do auto-deploys work? Connect a Git source (GitHub App is the richest). A push to the tracked branch triggers a deploy; GitHub pull requests can spin up preview environments. You can also trigger deploys via webhook or the API.

Q: What are preview deployments? Ephemeral, isolated copies of your application created per pull request at their own domain, with their own preview environment variables — perfect for reviewing changes before merge.

Q: Can I run builds on a separate machine? Yes. Enable build-server mode for an application and Coolify builds the image on a designated build server, then deploys the result to your serving server(s).

Q: How do I back up Coolify itself? Use Settings → Backup to back up Coolify's own metadata (PostgreSQL) database, and keep a copy of /data/coolify (which holds your SSH keys, application data, and configuration).

Q: Is Docker Swarm supported? Swarm exists but is deprecated and slated for removal in Coolify v5. Use standard single- or multi-server deployments for new setups.

Q: How do I automate Coolify from CI/CD? Create a Sanctum API token with the abilities you need (read/write/deploy) and call the /api/v1 REST API. See Using the REST API.

Q: Can AI tools manage my instance? Yes — Coolify can expose an MCP server at /mcp (disabled by default; enable via the API) so AI agents can manage resources with an authorized token.