# Coolify User Guide

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:

```bash
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`):

```text
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.

```text
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.

### 3.2 Recommended install (one-line script)

```bash
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:

```yaml
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:

```bash
curl http://127.0.0.1:8000/api/health
```

```text
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](#46-provisioning-cloud-servers-hetzner).

### 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](#10-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.

```text
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](#7-git-integrations-and-auto-deploy)).
- **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](#12-using-the-rest-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:

```bash
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

```bash
# Unauthenticated health check
curl https://<your-coolify>/api/v1/health
```
```text
OK
```
```bash
# 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

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

Poll the returned deployment UUID for status:

```bash
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](#12-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.

---

_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. Unofficial; not affiliated with or reviewed by the project._