# Authorization (/docs/api-reference/authorization) API Authorization [#api-authorization] Coolify uses Bearer tokens to authenticate API requests. Tokens are scoped to a single team and carry specific permissions that control what data and actions are available. Who this is for? [#who-this-is-for] This guide is for people who: * Want to automate infrastructure management through the Coolify API. * Are building integrations that interact with Coolify programmatically. * Need to set up authentication for the [MCP Server](/integrations/mcp) or other API-based tools. *** How It Works? [#how-it-works] Every API request must include a Bearer token in the `Authorization` header. Coolify validates the token, identifies the user and team, then checks whether the token's permissions allow the requested action. All resources returned by the API are scoped to the **team** the token was created under. If you work across multiple teams, you need a separate token for each one. *** Example Data [#example-data] The following data is used as an example in this guide. Replace it with your actual instance URL and token. * **Coolify URL:** `https://coolify.shadowarcanist.com` * **API Base:** `https://coolify.shadowarcanist.com/api/v1` * **API Token:** `67|abcthisisa123dummytoken` *** 1\. Enable the API [#1-enable-the-api] You can enable or disable the API from the dashboard: 1. Go to **Settings** in the sidebar. 2. Click on **Advanced**. 3. Find the **API Settings** section and toggle **API Access** on. Optionally, configure **Allowed IPs** to restrict API access to specific IP addresses. Leave it empty or set to `0.0.0.0` to allow all IPs (not recommended for production usage) If you already have a token with `root` permissions, you can enable or disable the API programmatically: ```bash # Enable API curl -X POST https://coolify.shadowarcanist.com/api/v1/enable \ -H "Authorization: Bearer 67|abcthisisa123dummytoken" # Disable API curl -X POST https://coolify.shadowarcanist.com/api/v1/disable \ -H "Authorization: Bearer 67|abcthisisa123dummytoken" ``` These endpoints require a token with `root` permissions. *** 2\. Create an API Token [#2-create-an-api-token] 1. Go to **Security** in the sidebar. 2. Click on **API Tokens**. 3. Enter a name for your token. 4. Choose an expiration period — **7, 30, 60, 90, 1 year**, or **no expiration**. 5. Select the permissions you need (see [Permissions](#permissions) below). 6. Click **Create** button. The token is displayed **only once** after creation. Copy it immediately and store it somewhere safe — you won't be able to see it again. Your token will look like this: ```sh 67|abcthisisa123dummytoken ``` The number before the `|` is the token ID. Everything after is the secret — both parts are required for authentication. *** 3\. Make API Requests [#3-make-api-requests] Include your token in the `Authorization` header of every request: ```bash curl https://coolify.shadowarcanist.com/api/v1/teams \ -H "Authorization: Bearer 67|abcthisisa123dummytoken" ``` Base URL [#base-url] All API endpoints are available under: ```sh https://coolify.shadowarcanist.com/api/v1 ``` The only exceptions are `/api/health` and `/api/feedback`, which sit outside the `/v1` prefix. *** Permissions [#permissions] Each token carries one or more permissions that control what it can access. Select correct permissions when creating the token. | Permission | Access Level | Description | | ---------------- | -------------- | --------------------------------------------------------------------------------------------- | | `read` | Read-only | View resources — servers, projects, applications, databases, services | | `read:sensitive` | Read + secrets | Everything in `read`, plus access to passwords, private keys, environment variables, and logs | | `write` | Modify | Create, update, and delete resources | | `deploy` | Deploy | Trigger deployments and manage deploy webhooks | | `root` | Full access | Bypasses all permission checks — complete control over the API | The `root` permission can only be assigned by users with **Admin** or **Owner** roles. It grants unrestricted API access, including enabling/disabling the API itself. Only use `root` when absolutely necessary. How Permissions Are Checked [#how-permissions-are-checked] * Each API endpoint requires a specific permission — `read`, `write`, or `deploy`. * If your token doesn't have the required permission, the request returns **403 Forbidden** with a list of the missing permissions. * Tokens with `root` bypass all permission checks entirely. * The `read:sensitive` permission controls whether sensitive fields (passwords, secrets, private keys, compose files) are included or redacted in responses. Grant only the permissions your integration actually needs. A monitoring dashboard only needs `read`. A CI/CD pipeline might need `read` and `deploy`. Reserve `root` for administrative automation. *** Team Scoping [#team-scoping] Every API token is bound to the team that was active when the token was created. The token can **only** access resources belonging to that team. * Servers, projects, applications, databases, and services are all filtered by the token's team. * If you don't see a resource in API responses, it likely belongs to a different team. * To access resources across multiple teams, create a separate token while each team is active. *** Rate Limiting [#rate-limiting] API requests are rate-limited to **200 requests per minute** by default. This applies globally and can be configured via the `API_RATE_LIMIT` environment variable for Coolify. When you exceed the rate limit, the API returns **429 Too Many Requests**. *** IP Allowlisting [#ip-allowlisting] You can restrict API access to specific IP addresses, so only trusted networks can reach your instance's API. Configure Allowed IPs [#configure-allowed-ips] 1. Go to **Settings** in the sidebar. 2. Click on **Advanced**. 3. Find the **Allowed IPs for API Access** field. 4. Enter your allowed IPs as a comma-separated list. ```sh # Single IPs 192.168.1.100,203.0.113.50 # CIDR notation 10.0.0.0/8,172.16.0.0/16 # Mixed 192.168.1.100,10.0.0.0/8,203.0.113.0/24 ``` Both IPv4 and IPv6 addresses are supported, including CIDR ranges. Behavior [#behavior] | Configuration | Result | | ------------------------- | ----------------------------------- | | Empty (default) | All IPs allowed | | `0.0.0.0` | All IPs allowed (explicit wildcard) | | Comma-separated IPs/CIDRs | Only listed IPs can access the API | If you set allowed IPs incorrectly, you could lock yourself out of the API. Make sure your current IP is included before saving. You can always change this setting from the dashboard. Coolify automatically deduplicates entries — if a specific IP is already covered by a CIDR range in your list, the redundant entry is removed. *** Security Considerations [#security-considerations] * **Token storage** — Tokens are stored as SHA-256 hashes. Coolify cannot retrieve your token after creation — if you lose it, create a new one. * **Token expiration** — Set an expiration period for tokens used in automated systems. Coolify sends an email warning before a token expires. * **IP allowlisting** — Restrict API access to trusted IPs only. See [IP Allowlisting](#ip-allowlisting) above. * **Team isolation** — Tokens only access resources within their team. A leaked token cannot access other teams' resources. * **Revocation** — Delete a token from **Security > API Tokens** to immediately revoke access. *** Troubleshooting [#troubleshooting] * Check that **API access is enabled** on your instance (**Settings > API**). * If IP allowlisting is configured, make sure your IP is in the allowed list. * Verify your token has the required permission for the endpoint you're calling. * Verify your token is correct and includes both the ID and secret (e.g., `67|abcth...`). * Check that the token hasn't expired — create a new one if needed. * Make sure the `Authorization` header format is exactly `Bearer `. * Resources are scoped to the token's team. If you don't see a resource, it may belong to a different team. * Switch to the correct team in the dashboard and create a new token for that team. * Your token needs the `read:sensitive` or `root` permission to see passwords, private keys, and other secrets. * Tokens with only `read` permission receive redacted values for sensitive fields. * The default limit is 200 requests per minute. Space out your requests or ask your instance administrator to adjust the `API_RATE_LIMIT` setting. # Docker Compose Build Packs (/docs/applications/build-packs/docker-compose)
Docker Compose lets you deploy multiple Docker containers and configure them easily. With the Docker Compose build pack, you can use your own Docker Compose file (i.e. `docker-compose.y[a]ml`) as the single source of truth, giving you full control over how your application is built and deployed on Coolify. How to use Docker Compose? [#how-to-use-docker-compose] 1\. Create a New Resource in Coolify [#1-create-a-new-resource-in-coolify] On the Coolify dashboard, open your project and click the **Create New Resource** button. 2\. Choose Your Deployment Option [#2-choose-your-deployment-option] **A.** If your Git repository is public, choose the **Public Repository** option. **B.** If your repository is private, you can select **Github App** or **Deploy Key**. (These methods require extra configuration. You can check the guides on setting up a [Github App](/applications/ci-cd/github/setup-app) or [Deploy Key](/applications/ci-cd/github/deploy-key) if needed.) 3\. Select Your Git Repository [#3-select-your-git-repository] If you are using a public repository, paste the URL of your GitHub repository when prompted. The steps are very similar for all other options. 4\. Choose the Build Pack [#4-choose-the-build-pack] Coolify defaults to using Nixpacks. Click the Nixpacks option and select **Docker Compose** as your build pack from the dropdown menu. 5\. Configure the Build Pack [#5-configure-the-build-pack] * **Branch:** Coolify will automatically detect the branch in your repository. * **Base Directory:** Enter the directory that Coolify should use as the root. Use `/` if your files are at the root or specify a subfolder (like `/backend` for a monorepo). * **Docker Compose Location:** Enter the path to your Docker Compose file, this path is combined with the Base Directory. Make sure the file extension matches exactly, if it doesn’t then Coolify won’t be able to load it. Click on **Continue** button once you have set all the above settings to correct details. Making services available to the outside world [#making-services-available-to-the-outside-world] Read more about [Exposing Services to the Internet](/knowledge-base/docker/compose#exposing-services-to-the-internet) in the Knowledge Base. Advanced Configuration [#advanced-configuration] Using Environment and Shared Variables [#using-environment-and-shared-variables] Within Coolify you can configure these easily following the details found in the [Knowledge Base for Docker Compose](/knowledge-base/docker/compose#defining-environment-and-shared-variables). Storage [#storage] You can set up storage in your compose file, with some extra options for Coolify. Create an Empty Directory [#create-an-empty-directory] Define directories with host binding and inform Coolify to create them: ```yaml services: filebrowser: image: filebrowser/filebrowser:latest volumes: - type: bind source: ./srv target: /srv is_directory: true # Instructs Coolify to create the directory. ``` Create a File with Content [#create-a-file-with-content] Specify a file with predefined content and even include a dynamic value from an environment variable: ```yaml services: filebrowser: image: filebrowser/filebrowser:latest environment: - POSTGRES_PASSWORD=password volumes: - type: bind source: ./srv/99-roles.sql target: /docker-entrypoint-initdb.d/init-scripts/99-roles.sql content: | -- NOTE: Change these passwords for production! \set pgpass `echo "$POSTGRES_PASSWORD"` ALTER USER authenticator WITH PASSWORD :'pgpass'; ALTER USER pgbouncer WITH PASSWORD :'pgpass'; ``` Exclude from Healthchecks [#exclude-from-healthchecks] If a service should not be part of the overall healthchecks (for example, a one-time migration service), set the `exclude_from_hc` option to `true`: ```yaml services: some-service: exclude_from_hc: true ... ``` Networking [#networking] When you deploy a Docker Compose stack, Coolify automatically creates an isolated bridge network (named after your resource UUID, e.g. `ewc08w0`) for all services in your stack. All services can communicate with each other using their service names as hostnames (e.g. `http://backend:8080`). Coolify also connects its reverse proxy (Traefik) to this network so it can route external traffic to your services. Do Not Define Custom Networks [#do-not-define-custom-networks] If your `docker-compose.yml` defines custom networks, **remove them**. Defining custom networks causes intermittent outages where your app becomes unreachable over HTTPS. For example, do **not** do this: ```yaml services: frontend: networks: - my-network backend: networks: - my-network networks: my-network: driver: bridge ``` When you define a custom network, your containers end up on **two networks** simultaneously — the Coolify-managed one and your custom one. Traefik is only on the Coolify-managed network, but non-deterministically picks which network IP to route to. If it picks the custom network IP, it cannot reach your container and requests will **hang indefinitely** or return **504 Gateway Timeout**. This behavior is intermittent — it may work after one deploy and break after the next, depending on which IP Traefik selects. See [#4483](https://github.com/coollabsio/coolify/issues/4483), [#6215](https://github.com/coollabsio/coolify/issues/6215), [#6153](https://github.com/coollabsio/coolify/issues/6153). **Instead**, simply remove the `networks:` sections entirely: ```yaml services: frontend: ... backend: ... ``` Coolify's auto-created network already provides inter-service communication. Connect to Predefined Networks [#connect-to-predefined-networks] By default, each compose stack is deployed to a separate network named after your resource UUID. This setup allows each service in the stack to communicate with one another. If you want to connect services across different stacks (for example, linking an application to a separate database), enable the **Connect to Predefined Network** option on your Service Stack page. Note that you must use the full name (like `postgres-`) when referencing a service in another stack. Raw Docker Compose Deployment [#raw-docker-compose-deployment] For advanced users, Coolify offers a "Raw Compose Deployment" mode. This option lets you deploy your Docker Compose file directly without many of Coolify's additional configurations. This mode is intended for advanced users familiar with Docker Compose. Labels [#labels] Coolify automatically adds these labels to your application (if not already set): ```yaml labels: - coolify.managed=true - coolify.applicationId=5 - coolify.type=application ``` To enable Coolify's Proxy (Traefik), also include these labels: ```yaml labels: - traefik.enable=true - "traefik.http.routers..rule=Host(`shadowarcanist.com`) && PathPrefix(`/`)" - traefik.http.routers..entryPoints=http ``` Build Arguments [#build-arguments] When building images with Docker Compose, Coolify can inject build arguments into your build process. You can configure these settings in the **Advanced** menu of your application. Inject Build Args to Dockerfile [#inject-build-args-to-dockerfile] Controls whether Coolify automatically injects build arguments during the build. Disable this in the Advanced menu if you want full control over build arguments in your Dockerfile. * **Enabled (default):** Coolify automatically injects build arguments * **Disabled:** You manage `ARG` statements yourself in the Dockerfile Include Source Commit in Build [#include-source-commit-in-build] Controls whether the `SOURCE_COMMIT` variable (Git commit hash) is included in builds. Disabled by default to preserve Docker's build cache between commits. You can enable this in the Advanced menu if your build process requires the commit hash. * **Disabled (default):** `SOURCE_COMMIT` is not included, improving cache utilization * **Enabled:** `SOURCE_COMMIT` is included as a build argument If build cache is not being preserved between deployments, ensure "Include Source Commit in Build" is disabled. The `SOURCE_COMMIT` value changes with every commit and will invalidate the cache. Known Issues and Solutions [#known-issues-and-solutions] If you see a "No Available Server" error when visiting your website, it is likely due to the health check for your container. Run `docker ps` on your server terminal to check if your container is unhealthy or still starting. To resolve this, fix the issue causing the container to be unhealthy or remove the health checks. # Dockerfile Build Pack (/docs/applications/build-packs/dockerfile)
Dockerfile includes step-by-step instructions to build a Docker image that Coolify uses to deploy your application or website. The Dockerfile build pack allows you to use your own Dockerfile to deploy your application, you have complete control over how your application is built and deployed on Coolify. How to use Dockerfile? [#how-to-use-dockerfile] 1\. Create a New Resource in Coolify [#1-create-a-new-resource-in-coolify] On the Coolify dashboard, open your project and click the **Create New Resource** button. 2\. Choose Your Deployment Option [#2-choose-your-deployment-option] **A.** If your Git repository is public, choose the **Public Repository** option. **B.** If your repository is private, you can select **Github App** or **Deploy Key**. (These methods require extra configuration. You can check the guides on setting up a [Github App](/applications/ci-cd/github/setup-app) or [Deploy Key](/applications/ci-cd/github/deploy-key) if needed.) 3\. Select Your Git Repository [#3-select-your-git-repository] If you are using a public repository, paste the URL of your GitHub repository when prompted. The steps are very similar for all other options. 4\. Choose the Build Pack [#4-choose-the-build-pack] Coolify defaults to using Nixpacks. Click the Nixpacks option and select **Dockerfile** as your build pack from the dropdown menu. 5\. Configure the Build Pack [#5-configure-the-build-pack] * **Branch:** Coolify will automatically detect the branch in your repository. * **Base Directory:** Enter the directory that Coolify should use as the root. Use `/` if your files are at the root or specify a subfolder (like `/backend` for a monorepo). Click on **Continue** button once you have set all the above settings to correct details. 6\. Configure Network Settings [#6-configure-network-settings] After clicking **Continue**, update settings like your domain and environment variables (if needed). The important option is the port where your application runs. Coolify sets the default port to 3000, so if your application listens on a different port, update the port number on the network section. Advanced Configuration [#advanced-configuration] Environment Variables [#environment-variables] You can manage your environment variables from the Coolify UI. Click on the **Environment Variables** tab to add or update them. Pre/Post Deployment Commands [#prepost-deployment-commands] * **Pre-deployment:** Optionally, specify a script or command to execute in the existing container before deployment begins. This command is run with `sh -c`, so you do not need to add it manually. * **Post-deployment:** Optionally, specify a script or command to execute in the newly built container after deployment completes. This command is also executed with `sh -c`. Build Arguments [#build-arguments] Coolify automatically injects build arguments into your Dockerfile during the build process. These include environment variables you've configured and predefined system values like `SOURCE_COMMIT`. You can configure these settings in the **Advanced** menu of your application. Inject Build Args to Dockerfile [#inject-build-args-to-dockerfile] By default, Coolify injects Docker build arguments (`ARG` statements) into your Dockerfile. If you prefer to manage build arguments manually in your Dockerfile, you can disable this behavior in the Advanced menu. * **Enabled (default):** Coolify automatically injects build arguments * **Disabled:** You manage `ARG` statements yourself in the Dockerfile Include Source Commit in Build [#include-source-commit-in-build] The `SOURCE_COMMIT` variable contains the Git commit hash of your source code. By default, this is excluded from the build to preserve Docker's build cache. You can enable this in the Advanced menu if needed. * **Disabled (default):** `SOURCE_COMMIT` is not included, improving cache utilization * **Enabled:** `SOURCE_COMMIT` is included as a build argument Enabling "Include Source Commit in Build" will cause Docker's build cache to be invalidated on every commit, since the commit hash changes each time. Only enable this if your build process requires the commit hash. Node.js Multi-Core Scaling [#nodejs-multi-core-scaling] A plain Node.js process only uses one CPU core. To make a Node.js (or Bun) app use every core on the host from a single Dockerfile build, see the [Node.js Multi-Core Scaling](/knowledge-base/nodejs-multi-core-scaling) guide. Known Issues and Solutions [#known-issues-and-solutions] If you see a "No Available Server" error when visiting your website, it is likely due to the health check for your container. Run `docker ps` on your server terminal to check if your container is unhealthy or still starting. To resolve this, fix the issue causing the container to be unhealthy or remove the health checks. If your app works when you check it with a `curl localhost` inside the container but you receive a 404 or "No Available Server" error when accessing your domain, verify the port settings. Make sure that the port in the network settings matches the port where your application is listening. Also, check the startup log to ensure the application is not only listening on localhost. If needed, change it to listen on all interfaces (for example, `0.0.0.0`). # Build Packs (/docs/applications/build-packs)
Coolify deploys every application as a Docker container. This means your application runs in its own isolated container. To run a container, you need a Docker image built from your source code. Build packs helps to create this Docker image and manage the build and deployment process. Why Use Build Packs? [#why-use-build-packs] * **Simplifies the Build Process:** Some Build packs automatically create the Docker image needed for deployment, so you don’t have to spend time on learning how to write Dockerfiles on your own. * **Flexibility for Different Projects:** Since every application is different, you can choose a build pack that suits your specific needs, whether you prefer an automated solution or a custom configuration. How Build Packs Work [#how-build-packs-work] Each build pack offers a different approach to building your Docker image: * **Automated Dockerfile Creation:** Build packs like Nixpacks & Static Build Pack automatically generate a Dockerfile based on your codebase and builds the docker image. * This allows you to deploy your application quickly without having to write the Dockerfile yourself. * **Custom Dockerfile or Docker Compose:** Build packs like Dockerfile & Docker Compose let you use a Dockerfile or Docker Compose file that you have already have on your codebase. * This gives you full control over how your Docker image is built and how multiple services work together. Choose the Right Build Pack [#choose-the-right-build-pack] Coolify have four build packs to meet different requirements: * **Nixpacks:** Good for quick and automated Docker image creation with minimal configuration. * **Static Build Pack:** Perfect for static sites and simple applications that don’t need server-side processing. * **Dockerfile:** Use your own Dockerfile, if you want full control over the docker image build process. * **Docker Compose:** Perfect to Deploy complex, multi-service applications using your custom Docker Compose file. How to use a Build Pack [#how-to-use-a-build-pack] Each build pack has its own step-by-step guide to help you use them in Coolify. Click the links below to learn more about each build pack. * [Static Build Pack](/applications/build-packs/static) * [Nixpack](/applications/build-packs/nixpacks) * [Dockerfile](/applications/build-packs/dockerfile) * [Docker Compose](/applications/build-packs/docker-compose) # Nixpacks Build Pack (/docs/applications/build-packs/nixpacks)
Nixpacks is a open source build pack created by [Railway](https://railway.com?utm_source=coolify.io) and the source is available on [Github](https://github.com/railwayapp/nixpacks?utm_source=coolify.io). Coolify uses Nixpacks as one of the build pack. Nixpacks checks your git repository (also called as "**source directory**" in nixpacks) and generates a Dockerfile, then it will build a docker image based on the Dockerfile it generated. Nixpacks can deploy both fully static websites and non-static applications. Once your repository is set up, you can use Coolify to deploy your project with ease. How to use Nixpacks? [#how-to-use-nixpacks] On Coolify you can only use Nixpacks on git-based deployments. 1\. Create a New Resource in Coolify [#1-create-a-new-resource-in-coolify] On Coolify dashboard open your project and click the **Create New Resource** button. 2\. Choose Your Deployment Option [#2-choose-your-deployment-option] **A.** If your Git repository is public, choose the **Public Repository** option. **B.** If your repository is private, you can select **Github App** or **Deploy Key**. (These methods require extra configuration. You can check the guides on setting up a [Github App](/applications/ci-cd/github/setup-app) or [Deploy Key](/applications/ci-cd/github/deploy-key) if needed.) 3\. Select Your Git Repository [#3-select-your-git-repository] If you are using a public repository, paste the URL of your GitHub repository when prompted. The steps are very similar for all other options. 4\. Choose the Build Pack [#4-choose-the-build-pack] Coolify will default to using Nixpacks. If it doesn’t, click to select Nixpacks as your build pack. 5\. Configure Build Pack [#5-configure-build-pack] We have different options like Base Directory, Publish Directory, and Ports that slightly change based on the application you deploy (static websites/applications). So, below we have two sections for the deployments possible with Nixpacks. * [How to deploy Fully Static Websites](#how-to-deploy-fully-static-website) * [How to deploy Non-Static Website/Applications](#how-to-deploy-non-static-website-applications) How to deploy Fully Static Website? [#how-to-deploy-fully-static-website] First, follow the previous section in this documentation: [How to use Nixpacks](#how-to-use-nixpacks). After that, proceed with the steps below. 1. **Branch:** Coolify will automatically detect the branch from your Repository. 2. **Base Directory:** Enter the directory Nixpacks should use as the root (for example, `/` if your files are at the root, or a subfolder if applicable). * If you have a monorepo then you can enter the path of the directory you want to use as base directory (`/backend` for example) 3. **Is it a static Site?:** Click on this option to enable static mode. 4. **Port:** Once you enabled `Is it a static Site` the port will be automatically set to `80` and cannot be changed. (This is intentional) 5. **Publish Directory:** Once you enabled `Is it a static Site` this publish directory option will visible on the UI. You have to enter the output directory where your static files are generated (commonly `/dist`). 6. Click on **Continue** button once you have set all the above settings to correct details. 7. Choose a web server for your static website * As of Coolify **v4.0.0-beta.404**, the only web server option available is [Nginx](https://nginx.org/en/?utm_source=coolify.io). So **Nginx** will be selected by default. 8. Click the **Deploy** button. The deployment process is usually quick (often less than a minute, depending on your server). 9. Customize Your Web Server Configuration `Optional` * Coolify provides a default web server configuration that works for most cases. * If you want to change it then click the **Generate** button to load the default settings and make any changes you need. You have to click on the **Restart** button for the new configuration to take effect. How this works? [#how-this-works] Nixpacks will build the website using your codebase and create a Docker image with a web server to serve them. This means your final Docker image has a web server ready to serve your HTML, CSS, and JavaScript files. How to deploy Non-Static Website/Applications? [#how-to-deploy-non-static-websiteapplications] First, follow the previous section in this documentation: [How to use Nixpacks](#how-to-use-nixpacks). After that, proceed with the steps below. 1. **Branch:** Coolify will automatically detect the branch from your Repository. 2. **Base Directory:** Enter the directory Nixpacks should use as the root (for example, `/` if your files are at the root, or a subfolder if applicable). * If you have a monorepo then you can enter the path of the directory you want to use as base directory (`/backend` for example) 3. **Port:** Enter the port where your application listens for incoming requests. 4. **Is it a static Site?:** Leave this unchecked since you’re deploying a non-static application. 5. Click on **Continue** button once you have configured all the above options. 6. After clicking the **Continue** button, you can adjust settings like your domain and environment variables, then click the **Deploy** button to launch your application. How this works? [#how-this-works-1] Nixpacks analyzes your codebase, builds a Docker image, and then starts a container using that image. Advanced Configuration [#advanced-configuration] Environment Variables [#environment-variables] You can customize Nixpacks' behavior using environment variables. There are many variables available for different application frameworks, and you can find detailed information in their documentation: [Nixpacks Environment Variables](https://nixpacks.com/docs/configuration/environment?utm_source=coolify.io). To add or modify environment variables in Coolify, simply click on the **Environment Variables** tab, where you can manage them easily. *** Commands [#commands] If needed, you can override the default install, build, and start commands. Simply scroll down to the build section on Coolify and input your custom commands. You may need to include a `nixpacks.toml` file in your repository for these changes to take effect. *** Configuration file [#configuration-file] Nixpacks supports specifying build configurations in a nixpacks.toml or nixpacks.json file. If one of these files is present in the root of your repository, it will be automatically used. For more details, refer to the [Nixpacks documentation](https://nixpacks.com/docs/configuration/file?utm_source=coolify.io). *** Node.js Multi-Core Scaling [#nodejs-multi-core-scaling] A plain Node.js process only uses one CPU core. To make a Node.js (or Bun) app use every core on the host from a single Nixpacks build, see the [Node.js Multi-Core Scaling](/knowledge-base/nodejs-multi-core-scaling) guide. Known Issues [#known-issues] Outdated Packages/Dependencies [#outdated-packagesdependencies] Sometimes, Nixpacks may use older package versions than you need. This is especially common with Node.js, where you might need a specific minor or patch version. For Node.js version pinning, see the dedicated [Node.js Versioning](/applications/build-packs/nixpacks/node-versioning) guide. For other packages, you can update the `nixpkgs` archive version in your `nixpacks.toml` file. Learn more in the Nixpacks docs on [nixpkgs archive](https://nixpacks.com/docs/configuration/file#nixpkgs-archive?utm_source=coolify.io). # Node.js Versioning (/docs/applications/build-packs/nixpacks/node-versioning) Node.js Versioning in Nixpacks [#nodejs-versioning-in-nixpacks] Nixpacks only supports **major version** specification for Node.js. This page explains the limitation and provides a workaround for pinning specific minor or patch versions. Understanding the Limitation [#understanding-the-limitation] According to the [Nixpacks Node provider documentation](https://nixpacks.com/docs/providers/node?utm_source=coolify.io): > "Only a major version can be specified. For example, `18.x` or `20`." When you specify a Node.js version via: * `NIXPACKS_NODE_VERSION` environment variable * `engines.node` in `package.json` * `.nvmrc` or `.node-version` files You can only control the **major version** (e.g., `20`, `22`). The specific minor and patch version (e.g., `22.13.1` vs `22.14.0`) is determined by the nixpkgs archive that Nixpacks uses internally. The Problem [#the-problem] You set `"node": ">=22"` in your `package.json` or `NIXPACKS_NODE_VERSION=22`, but your application needs Node 22.14.0 specifically. Nixpacks may instead provide 22.12.0 or another patch version from its default nixpkgs archive—causing runtime issues if your code depends on features from a newer patch. Workaround [#workaround] To pin a specific minor/patch version, you can override the nixpkgs archive in your `nixpacks.toml` file. Create this file in your repository root: ```toml [phases.setup] nixpkgsArchive = '51ad838b03a05b1de6f9f2a0fffecee64a9788ee' ``` The `nixpkgsArchive` value is a commit SHA from the [NixOS/nixpkgs repository](https://github.com/NixOS/nixpkgs?utm_source=coolify.io). Each commit contains specific package versions, so by pinning a commit, you control the exact versions available. Finding the Right Archive Commit [#finding-the-right-archive-commit] To find a nixpkgs commit containing your required Node.js version: 1. Browse the [NixOS/nixpkgs repository](https://github.com/NixOS/nixpkgs?utm_source=coolify.io) 2. Search for files like `v20.nix`, `v22.nix`, or `v24.nix` (the Node.js version definition files) 3. Check the commit history for when your desired version was added 4. Copy the full commit SHA **Some verified commits for Node.js:** * `51ad838b03a05b1de6f9f2a0fffecee64a9788ee` → Node 22.13.1 * `bf744fe90419885eefced41b3e5ae442d732712d` → Node 22.x versions * `ffeebf0acf3ae8b29f8c7049cd911b9636efd7e7` → Node 22.14.0 (unstable branch) Learn more in the Nixpacks docs on [nixpkgs archive](https://nixpacks.com/docs/configuration/file#nixpkgs-archive?utm_source=coolify.io). Node.js Version Reference (SHA256 Hashes) [#nodejs-version-reference-sha256-hashes] The following tables list Node.js versions and their SHA256 hashes from the nixpkgs history. These can help you verify you're getting the expected version when working with nixpkgs archives. These hashes are provided for reference only. They have not been verified for accuracy nor stability. Test thoroughly before using in production. | Version | SHA256 | | ------- | :----------------------------------------------------------------- | | 20.0.0 | `sha256-dFDnV5Vo99HLOYGFz85HLaKDeyqjbFliCyLOS5d7XLU=` | | 20.1.0 | `sha256-YA+eEYYJlYFLkSKxrFMY9q1WQnR4Te7ZjYqSBmSUNrU=` | | 20.2.0 | `sha256-IlI98jFsNVaXFP8fabBTwuKGztRgiYQX3uRpRe/N+Yk=` | | 20.3.0 | `sha256-G6jUlCPtOnVykGa7PqJkk+6ct9ZWjvlIWX/J70VPdDU=` | | 20.3.1 | `sha256-EqgtswZpeVm0OJs1Gl+XhImGsTE/mQGw4LPYz08/mZE=` | | 20.4.0 | `sha256-Cb0Lc8UmtjwCnV3f2IXRCWLnrYfJdblFg8H4zpDuU0g=` | | 20.5.0 | `sha256-yzJ1aVje8cBOBpp5txtSymHtFZDBfyz6HuOvZB9y4Fg=` | | 20.5.1 | `sha256-Q5xxqi84woYWV7+lOOmRkaVxJYBmy/1FSFhgScgTQZA=` | | 20.6.0 | `sha256-nvtcunqPSxjTiw19N6mzDe1zOQyE44DPTeianTCn1vo=` | | 20.6.1 | `sha256-Ouxeco2qOIAMNDsSkiHTSIBkolKaObtUZ7xVviJsais=` | | 20.7.0 | `sha256-P8/c0FxGFRdIBZZZZnTfhbNc/OWX3QrjP1QW/E3xK+o=` | | 20.8.0 | `sha256-QSvoR65t9hAQup2jzD5r5bZ6oALjVOkZ9Z7INgNxcEw=` | | 20.8.1 | `sha256-95nGb2pjhruKwsdaN490DEVel/H+lkOT3TnJ+fbvvHA=` | | 20.9.0 | `sha256-oj2WgQq/BFVCazSdR85TEPMwlbe8BXG5zFEPSBw6RRk=` | | 20.10.0 | `sha256-MuslbuvYys1VdOZjHlS0K+fsjr4lrUeoymhUA7rRVTU=` | | 20.11.0 | `sha256-MYB+vu6wScU/F2XkqVrtaUdqS2lt0QDLU5q2aNeVC0A=` | | 20.11.1 | `sha256-d4E+2/P38W0tNdM1NEPe5OYdXuhNnjE4x1OKPAylIJ4=` | | 20.12.0 | `sha256-duU0bOv9WBUo9pn3ZPTRpuh8uBi2lnCPI13ctiWg940=` | | 20.12.1 | `sha256-aEDUkLpNHVFlXg++EgmVahXbQFUQ1+oWa62YqMnTek4=` | | 20.12.2 | `sha256-18vMX7+zHpAB8/AVC77aWavl3XE3qqYnOVjNWc41ztc=` | | 20.14.0 | `sha256-CGVQKPDYQ26IFj+RhgRNY10/Nqhe5Sjza9BbbF5Gwbs=` | | 20.15.0 | `sha256-D0p6BRw12V65BejLKqQ8XUArExIDkI/mM+s8+gUO+Qc=` | | 20.15.1 | `sha256-/dU6VynZNmkaKhFRBG+0iXchy4sPyir5V4I6m0D+DDQ=` | | 20.16.0 | `cd6c8fc3ff2606aadbc7155db6f7e77247d2d0065ac18e2f7f049095584b8b46` | | 20.17.0 | `9abf03ac23362c60387ebb633a516303637145cb3c177be3348b16880fd8b28c` | | 20.18.0 | `7d9433e91fd88d82ba8de86e711ec41907638e227993d22e95126b02f6cd714a` | | 20.18.1 | `91df43f8ab6c3f7be81522d73313dbdd5634bbca228ef0e6d9369fe0ab8cccd0` | | 20.18.2 | `69bf81b70f3a95ae0763459f02860c282d7e3a47567c8afaf126cc778176a882` | | 20.18.3 | `0674f16f3bc284c11724cd3f7c2a43f7c2c13d2eb7a872dd0db198f3d588c5f2` | | 20.19.0 | `5ac2516fc905b6a0bc1a33e7302937eac664a820b887cc86bd48c035fba392d7` | | 20.19.1 | `5587b23e907d0c7af2ea8a8deb33ec50010453b46dbb3df5987c5678eee5ed51` | | 20.19.2 | `4a7ff611d5180f4e420204fa6f22f9f9deb2ac5e98619dd9a4de87edf5b03b6e` | | 20.19.3 | `99be7b9d268d48b93be568a23240398ceacb0782dc7055b9972305c000b0e292` | | 20.19.4 | `b87fd7106013d3906706913ffc63a4403715fbb272c4f83ff4338527353eec0f` | | 20.19.5 | `230c899f4e2489c4b8d2232edd6cc02f384fb2397c2a246a22e415837ee5da51` | | 20.19.6 | `2026f9ff52c286d7c7d99932b21be313d1736aea524c5aff1748d41ab0bd9a20` | | Version | SHA256 | | ------- | :----------------------------------------------------------------- | | 22.0.0 | `sha256-IuKPv/MfaQc7gCTLQnReUQX4QEHzR1smC5fVoUEDnRo=` | | 22.1.0 | `sha256-nX1fQNnb1iYMmbXklLX5vHVejw/6xw4SGtzl+0QvI8s=` | | 22.2.0 | `sha256-iJkIqIKNFISRDX5lm2qlet6NUo/w45Dpp372WadihHQ=` | | 22.3.0 | `0k0h4s9s2y0ms3g6xhynsqsrkl9hz001dmj6j0gpc5x5vk8mpf5z` | | 22.4.0 | `sha256-KStDAITy8ykT3H2k6y+8iWklJ3Kp0b/ormxLSpjKOtM=` | | 22.4.1 | `sha256-ZfyFf1qoJWqvyQCzRMARXJrq4loCVB/Vzg29Tf0cX7k=` | | 22.5.1 | `924f381a32cf26b6bedbe95feedde348450f4fd321283d3bf3f7965aa45ce831` | | 22.6.0 | `37259d618d5565ca55acc2585045c7e1c5b9965a3d4eb44c0a237fdae84b9d44` | | 22.7.0 | `1e0b6f2f2ca4fb0b4644a11363169daf4b7c42f00e5a53d2c65a9fdc463e7d88` | | 22.8.0 | `f130e82176d1ee0702d99afc1995d0061bf8ed357c38834a32a08c9ef74f1ac7` | | 22.9.0 | `a55aeb368dee93432f610127cf94ce682aac07b93dcbbaadd856df122c9239df` | | 22.10.0 | `3180710d3130ad9df01466abf010e408d41b374be54301d1480d10eca73558e0` | | 22.11.0 | `bbf0297761d53aefda9d7855c57c7d2c272b83a7b5bad4fea9cb29006d8e1d35` | | 22.12.0 | `fe1bc4be004dc12721ea2cb671b08a21de01c6976960ef8a1248798589679e16` | | 22.13.1 | `cfce282119390f7e0c2220410924428e90dadcb2df1744c0c4a0e7baae387cc2` | | 22.14.0 | `c609946bf793b55c7954c26582760808d54c16185d79cb2fb88065e52de21914` | | 22.15.0 | `e7c4226d1d92f33ad854d6da4f7e519e77690b8e73f93496881f8c539174d9df` | | 22.15.1 | `c19f0177d21c621746625e5f37590bd0d79a72043b77b53784cba5f145e7263e` | | 22.16.0 | `720894f323e5c1ac24968eb2676660c90730d715cb7f090be71a668662a17c37` | | 22.17.0 | `7a3ef2aedb905ea7926e5209157266e2376a5db619d9ac0cba3c967f6f5db4f9` | | 22.17.1 | `327415fd76fcebb98133bf56e2d90e3ac048b038fac2676f03b6db91074575b9` | | 22.18.0 | `120e0f74419097a9fafae1fd80b9de7791a587e6f1c48c22b193239ccd0f7084` | | 22.19.0 | `0272acfce50ce9ad060288321b1092719a7f19966f81419835410c59c09daa46` | | 22.20.0 | `ff7a6a6e8a1312af5875e40058351c4f890d28ab64c32f12b2cc199afa22002d` | | 22.21.1 | `487d73fd4db00dc2420d659a8221b181a7937fbc5bc73f31c30b1680ad6ded6a` | | Version | SHA256 | | ----------- | :----------------------------------------------------------------- | | 24.0.0-rc.2 | `729fca42bb7266031dd020f3935423ea8d4b4e2d119b34b608f1d079e5c1621a` | | 24.0.0-rc.3 | `9bbca08fba05f075a20f734ea80b195a4a39218476b60b32db79e1d393fda20b` | | 24.0.0 | `914f3f1b03f84a0994d7357f190ff13c038800c693b6c06da2290eb588c82761` | | 24.0.1 | `70271026971808409a7ed6444360d5fe3ef4146c1ca53f2ca290c60d214be84e` | | 24.0.2 | `1597075afc06e5c6145d0bfbd77e2072c2ec0ab71ac4950cf008b2641374cd71` | | 24.1.0 | `c8171b2aeccb28c8c5347f273a25adae172fb2a65bc8c975bc22ec58949d0eaf` | | 24.2.0 | `40143d43efbdeeb9537995f532126c494d63a31da332acb5022f76f00afc62ab` | | 24.3.0 | `eb688ef8a63fda9ebc0b5f907609a46e26db6d9aceefc0832009a98371e992ed` | | 24.4.0 | `42fa8079da25a926013cd89b9d3467d09110e4fbb0c439342ebe4dd6ecc26bbb` | | 24.4.1 | `adb79ca0987486ed66136213da19ff17ef6724dcb340c320e010c9442101652f` | | 24.5.0 | `f1ba96204724bd1c6de7758e08b3718ba0b45d87fb3bebd7e30097874ccc8130` | | 24.6.0 | `8ad5c387b5d55d8f3b783b0f1b21bae03a3b3b10ac89a25d266cffa7b795e842` | | 24.7.0 | `cf74a77753b629ffebd2e38fb153a21001b2b7a3c365c0ec7332b120b98c7251` | | 24.8.0 | `1c03b362ebf4740d4758b9a3d3087e3de989f54823650ec80b47090ef414b2e0` | | 24.9.0 | `f17bc4cb01f59098c34a288c1bb109a778867c14eeb0ebbd608d0617b1193bbf` | | 24.10.0 | `f17e36cb2cc8c34a9215ba57b55ce791b102e293432ed47ad63cbaf15f78678f` | | 24.11.0 | `cf9c906d46446471f955b1f2c6ace8a461501d82d27e1ae8595dcb3b0e2c312a` | | 24.11.1 | `ea4da35f1c9ca376ec6837e1e30cee30d491847fe152a3f0378dc1156d954bbd` | | 24.12.0 | `6d3e891a016b90f6c6a19ea5cbc9c90c57eef9198670ba93f04fa82af02574ae` | | Version | SHA256 | | ------- | :----------------------------------------------------------------- | | 25.2.1 | `aa7c4ac1076dc299a8949b8d834263659b2408ec0e5bba484673a8ce0766c8b9` | # Railpack Build Pack (/docs/applications/build-packs/railpack) Railpack [#railpack] Railpack is an open source build pack created by [Railway](https://railway.com?utm_source=coolify.io) as the successor to [Nixpacks](/applications/build-packs/nixpacks). The source is available on [GitHub](https://github.com/railwayapp/railpack?utm_source=coolify.io). Coolify uses Railpack as one of the build packs. Railpack checks your git repository and automatically detects your programming language, installs dependencies, and configures build and start commands — all with zero configuration. It then builds an optimized Docker image using BuildKit. Railpack can deploy both fully static websites and non-static applications. Once your repository is set up, you can use Coolify to deploy your project with ease. *** How to use Railpack? [#how-to-use-railpack] On Coolify you can only use Railpack on git-based deployments. The setup steps are the same as Nixpacks — follow the [Nixpacks guide](/applications/build-packs/nixpacks#how-to-use-nixpacks) but select **Railpack** instead of **Nixpacks** in the build pack selector (Step 4). Railpack is currently marked as **Beta** in Coolify. It is fully functional but may receive changes as it matures. *** Deploying Static Websites [#deploying-static-websites] The steps for deploying a fully static website with Railpack are the same as Nixpacks. Follow the [Nixpacks static site guide](/applications/build-packs/nixpacks#how-to-deploy-fully-static-website) — the only difference is that Railpack is selected as the build pack. *** Deploying Non-Static Applications [#deploying-non-static-applications] The steps for deploying a non-static application with Railpack are the same as Nixpacks. Follow the [Nixpacks non-static guide](/applications/build-packs/nixpacks#how-to-deploy-non-static-website-applications) — the only difference is that Railpack is selected as the build pack. *** Advanced Configuration [#advanced-configuration] Environment Variables [#environment-variables] You can customize Railpack's behavior using environment variables prefixed with `RAILPACK_`. Below are the available variables: | Variable | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `RAILPACK_BUILD_CMD` | Override the build command detected by Railpack | | `RAILPACK_INSTALL_CMD` | Override the install command detected by Railpack | | `RAILPACK_START_CMD` | Override the start command for the container | | `RAILPACK_PACKAGES` | Install additional [Mise](https://mise.jdx.dev?utm_source=coolify.io) packages (format: `pkg[@version]`, space-separated) | | `RAILPACK_BUILD_APT_PACKAGES` | Install additional apt packages during the build phase (space-separated) | | `RAILPACK_DEPLOY_APT_PACKAGES` | Install additional apt packages in the final deployed image (space-separated) | | `RAILPACK_DISABLE_CACHES` | Disable specific BuildKit cache keys, or `*` to disable all caches | | `RAILPACK_VERBOSE` | Enable verbose logging during the build | For more details, see the [Railpack Environment Variables](https://railpack.com/config/environment-variables/?utm_source=coolify.io) documentation. To add or modify environment variables in Coolify, simply click on the **Environment Variables** tab, where you can manage them easily. Configuration file [#configuration-file] Railpack supports specifying build configurations in a `railpack.json` file. If this file is present in the root of your repository, it will be automatically used. For example: ```json { "$schema": "https://schema.railpack.com", "packages": { "node": "22" }, "steps": { "install": { "commands": ["npm install"] }, "build": { "commands": ["npm run build"] } }, "deploy": { "startCommand": "node dist/index.js" } } ``` Adding `$schema` to your `railpack.json` enables autocomplete and validation in your editor. For more details, refer to the [Railpack Configuration File](https://railpack.com/config/file/?utm_source=coolify.io) documentation. *** Railpack vs Nixpacks [#railpack-vs-nixpacks] Railpack is the successor to [Nixpacks](/applications/build-packs/nixpacks), built by the same team at Railway. Key differences include: | | Railpack | Nixpacks | | --------------------- | -------------------------------------------------- | ---------------------- | | **Config file** | `railpack.json` (JSON) | `nixpacks.toml` (TOML) | | **Build system** | Docker BuildKit with frontend | Native Docker build | | **Package manager** | [Mise](https://mise.jdx.dev?utm_source=coolify.io) | Nix | | **Env var prefix** | `RAILPACK_*` | `NIXPACKS_*` | | **Maintenance** | Actively developed | Maintenance mode | | **Status in Coolify** | Beta | Stable | Both build packs support automatic language detection, static site deployment, custom install/build/start commands, and environment variable configuration. # Static Build Packs (/docs/applications/build-packs/static)
Static Build Packs take the files from your project and create a Docker image with a web server to serve them. This means your final Docker image has a web server ready to display your HTML, CSS, and JavaScript files. Static Build Packs only work if your project is already built (for example, with a static site generator like [Astro](https://astro.build/?utm_source=coolify.io) or [Webstudio](https://webstudio.is/?utm_source=coolify.io)). Once you have the built files, you can upload them to a Git repository and use Coolify to deploy your site. How to Use Static Build Pack [#how-to-use-static-build-pack] 1\. Prepare Your Static Files [#1-prepare-your-static-files] First, build your site with your favorite static site generator. This process creates a folder with all the files your site needs (HTML, CSS, JavaScript, etc.). Next, upload these static files to a Git repository. You can use [GitHub](https://github.com/?utm_source=coolify.io), [GitLab](https://about.gitlab.com/?utm_source=coolify.io), or any other Git service. For this guide, we will use [GitHub](https://github.com/?utm_source=coolify.io) as an example. 2\. Create a New Resource in Coolify [#2-create-a-new-resource-in-coolify] On Coolify dashboard open your project and click the **Create New Resource** button. 3\. Choose Your Deployment Option [#3-choose-your-deployment-option] **A.** If your Git repository is public, choose the **Public Repository** option. **B.** If your repository is private, you can select **Github App** or **Deploy Key**. (These methods require extra configuration. You can check the guides on setting up a [Github App](/applications/ci-cd/github/setup-app) or [Deploy Key](/applications/ci-cd/github/deploy-key) if needed.) 4\. Select Your Git Repository [#4-select-your-git-repository] If you are using a public repository, paste the URL of your GitHub repository when prompted. The steps are very similar for all options. 5\. Choose the Build Pack [#5-choose-the-build-pack] Coolify will default to using Nixpacks. Click on the Nixpack option, and then select **Static** from the dropdown menu. This tells Coolify to build your image with a static web server. 6\. Set the Base Directory [#6-set-the-base-directory] Enter the path where your static files are located: * If your files are in the root of your repository, just type `/`. * If they are in a subfolder, type the path to that folder (for example, `/out`). After setting the base directory, click the **Continue** button. 7\. Choose a Web Server [#7-choose-a-web-server] As of Coolify **v4.0.0-beta.402**, the only web server option available is [Nginx](https://nginx.org/en/?utm_source=coolify.io). So **Nginx** will be selected by default. 8\. Enter Your Domain [#8-enter-your-domain] Type the domain name where you want your site to be available. If you have multiple domains, separate them with commas. 9\. Deploy Your Site [#9-deploy-your-site] Click the **Deploy** button. The deployment process is usually quick (often less than a minute, depending on your server). Once the deployment is finished, visit your domain in a browser to see your live site. 10\. Customize Your Web Server Configuration `Optional` [#10-customize-your-web-server-configuration-optional] Coolify provides a default web server configuration that works for most cases. If you want to change it then click the **Generate** button to load the default settings and make any changes you need. You have to click on the **Restart** button for the new configuration to take effect. # Integration (/docs/applications/ci-cd/bitbucket/integration) Bitbucket Integration [#bitbucket-integration] This guide will show you how to use Bitbucket based repositories with Coolify. Public Repositories [#public-repositories] You can use public repositories without any additional setup. 1. Select the `Public repository` option in the Coolify when you create a new resource. 2. Add your repository URL to the input field, for example: `https://bitbucket.com/coolify-test2/coolify-examples` You can only use the https URL. 1. That's it! Coolify will automatically pull the latest version of your repository and deploy it. Private Repositories [#private-repositories] Private repositories require a few more steps to setup. 1. Add a private key (aka `Deploy Keys`) to Coolify and to your Bitbucket repository in the `Repository Settings` / `Access Keys` menu. * You can generate a new key pair with the following command: ```bash ssh-keygen -t rsa -b 4096 -C "deploy_key" ``` * Or you can also use Coolify to generate a new key for you in the `Keys & Tokens` menu. 2. Create a new resource and select the `Private Repository (with deploy key)` 3. Add your repository URL to the input field, for example: `git@bitbucket.org:coolify-test2/coolify-examples.git` You need to use the SSH URL, so the one that starts with `git@`. 4. That's it! Coolify will automatically pull the latest version of your repository and deploy it. Automatic commit deployments with webhooks (Optional) [#automatic-commit-deployments-with-webhooks-optional] You can add a custom webhook URL to your Bitbucket repository to trigger a new deployment when you push to your repository. This can be set on either public or private repositories. In your resource, there is a `Webhooks` menu. In the `Manual Git Webhooks` section, you can find the URL what you need to set in your Bitbucket repository. 1. Set a secret key in the `Bitbucket Webhook Secret` input field. 2. Go to your repository in Bitbucket and open the `Repository Settings` / `Webhooks` menu as `Repository hooks`. 3. Add the URL from Coolify to the `URL` input field and the secret token. 4. Select the `Push` option. 5. That's it! Now when you push to your repository, Bitbucket will send a webhook request to Coolify and it will trigger a new deployment. Merge request deployments with webhooks (Optional) [#merge-request-deployments-with-webhooks-optional] You can add a custom webhook URL to your Bitbucket repository to trigger a new deployment when you create a new merge request. This can be set on either public or private repositories. The process is the same as the previous one. In the `Repository Settings` / `Webhooks` menu, you need to select the following events in the `Pull Request` option: * `Created` * `Updated` * `Merged` * `Declined` # Integration (/docs/applications/ci-cd/gitea/integration) Gitea Integration [#gitea-integration] This guide will show you how to use Gitea based repositories with Coolify. Public Repositories [#public-repositories] You can use public repositories without any additional setup. 1. Select the `Public repository` option in the Coolify when you create a new resource. 2. Add your repository URL to the input field, for example: `https://gitea.com/heyandras/coolify-examples` You can only use the https URL. 1. That's it! Coolify will automatically pull the latest version of your repository and deploy it. Private Repositories [#private-repositories] Private repositories require a few more steps to setup. 1. Add a private key (aka `Deploy Keys`) to Coolify and to your Gitea repository in the `Repository Settings` / `Access Keys` menu. * You can generate a new key pair with the following command: ```bash ssh-keygen -t rsa -b 4096 -C "deploy_key" ``` * Or you can also use Coolify to generate a new key for you in the `Keys & Tokens` menu. 2. Create a new resource and select the `Private Repository (with deploy key)` 3. Add your repository URL to the input field, for example: `git@gitea.com:heyandras/coolify-examples.git` You need to use the SSH URL, so the one that starts with `git@`. 4. That's it! Coolify will automatically pull the latest version of your repository and deploy it. Automatic commit deployments with webhooks (Optional) [#automatic-commit-deployments-with-webhooks-optional] You can add a custom webhook URL to your Gitea repository to trigger a new deployment when you push to your repository. This can be set on either public or private repositories. In your resource, there is a `Webhooks` menu. In the `Manual Git Webhooks` section, you can find the URL what you need to set in your Gitea repository. 1. Set a secret key in the `Gitea Webhook Secret` input field. 2. Go to your repository in Gitea and open the `Repository Settings` / `Webhooks` menu as `Repository hooks`. 3. Add the URL from Coolify to the `URL` input field and the secret token. 4. Select the `Push` option. 5. That's it! Now when you push to your repository, Gitea will send a webhook request to Coolify and it will trigger a new deployment. Merge request deployments with webhooks (Optional) [#merge-request-deployments-with-webhooks-optional] You can add a custom webhook URL to your Gitea repository to trigger a new deployment when you create a new merge request. This can be set on either public or private repositories. The process is the same as the previous one. In the `Repository Settings` / `Webhooks` menu, you need to select the following events in the `Pull Request` option: * `Created` * `Updated` * `Merged` * `Declined` # GitHub Actions (/docs/applications/ci-cd/github/actions) GitHub Actions [#github-actions] GitHub Actions allow you to build your application as a Docker image and deploy it to Coolify automatically. GitHub Actions provide greater flexibility for deploying your app, as you can trigger the workflow on events like commits to specific branches or releases on GitHub. You can also integrate checks and tests into your CI/CD pipeline, ensuring that new versions are deployed to Coolify only after all validations pass. Process Overview [#process-overview] Set up GitHub Actions to build and publish a Docker image of your app to a container registry (e.g., GHCR or Docker Hub), then make an API call to Coolify to redeploy your app using the latest image pushed to the registry. For reference, check out this [example repository](https://github.com/andrasbacsai/github-actions-with-coolify) and its [workflow file](https://github.com/andrasbacsai/github-actions-with-coolify/blob/main/.github/workflows/build.yaml). The following data is used as an example in this guide. Please replace it with your actual data when following the steps: * **Docker Image:** `shadowarcanist/tasklytics:latest` * **Registry:** `ghcr.io` * **Branch:** `main` 1\. Choose the Right Deployment Type [#1-choose-the-right-deployment-type] With GitHub Actions, build your application as a Docker image on GitHub runners and push it to a container registry. Select a deployment type that supports prebuilt Docker images. For Git-based applications, use Docker Compose as your build pack. In your compose file, pull the prebuilt image instead of building it: ```yaml services: web: # OLD: # build: # context: . # dockerfile: Dockerfile # NEW: image: ghcr.io/shadowarcanist/tasklytics:latest ports: - "8080:8080" ``` For Docker-based applications, use the image name like `ghcr.io/shadowarcanist/tasklytics:latest` so Docker pulls the prebuilt image. 2\. Enable Coolify API [#2-enable-coolify-api] 1. Go to the "Settings" page in Coolify. 2. Click on the "Configuration" tab. 3. Click on "Advanced". 4. Check the "API Access" option. 3\. Create Coolify API Token [#3-create-coolify-api-token] 1. Go to the "Keys & Tokens" page in Coolify. 2. Click on the "API Tokens" tab. 3. Check the "Deploy" option under Token permissions. 4. Give your API token a name. 5. Click "Create" button. 6. Copy and save the generated API token somewhere safe (you'll need it later). 4\. Get Coolify Webhook URL [#4-get-coolify-webhook-url] 1. Open your application's configuration page. 2. Go to the "Webhook" page. 3. Copy and save the "Deploy webhook" URL somewhere safe (you'll need it later). 5\. Set Up Repository Secrets [#5-set-up-repository-secrets] 1. Go to your GitHub repository settings. 2. Click "Actions" in the sidebar (under "Secrets and variables"). 3. Click "New repository secret". 4. Enter `COOLIFY_WEBHOOK` as the name. 5. Enter the Coolify deploy webhook URL as the secret (from [step 4](#_4-get-coolify-webhook-url)). 6. Click "Add secret" button. 7. Click "New repository secret". 8. Enter `COOLIFY_TOKEN` as the name. 9. Enter the Coolify API token as the secret (from step 3). 10. Click "Add secret" button. 6\. Set Up GitHub Workflow [#6-set-up-github-workflow] 1. Create a new workflow file in the `.github/workflows` directory of your repository (name it with a `.yml` or `.yaml` extension). 2. Use the following workflow content as a starting point: ```yaml name: Build and Deploy on: push: branches: ["main"] # Trigger on pushes to main branch env: REGISTRY: ghcr.io IMAGE_NAME: "andrasbacsai/github-actions-with-coolify" jobs: build-and-deploy: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkout@v3 - name: Login to registry uses: docker/login-action@v2 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: Build and push image uses: docker/build-push-action@v4 with: context: . file: Dockerfile platforms: linux/amd64 push: true tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest - name: Deploy to Coolify run: | curl --request GET '${{ secrets.COOLIFY_WEBHOOK }}' --header 'Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}' ``` This workflow builds the Docker image, pushes it to `ghcr.io` with the tag `latest`, and triggers a redeployment in Coolify via API. The above workflow is just an example to show how the process works. Adjust it to fit your own CI/CD needs. Make sure the **Deploy to Coolify** step comes after all checks and tests so it only runs when everything before it passes. 7\. Authenticate with Container Registry [#7-authenticate-with-container-registry] If pushing to a private registry, authenticate it on your server so it can pull the image. Run one of these commands on your server's terminal (based on the registry): * **Docker Hub**: `docker login` * **GitHub Container Registry (GHCR)**: `echo $GH_TOKEN | docker login ghcr.io -u $USERNAME --password-stdin` For other registries, refer to their documentation. That's it! # GitHub Auto Deploy (/docs/applications/ci-cd/github/auto-deploy) GitHub Auto Deploy [#github-auto-deploy] Coolify can automatically deploy new versions of your application whenever you push changes to your GitHub repository. There are three methods to set up automatic deployments on Coolify: * [GitHub App](#github-app) * [GitHub Actions](#github-actions) * [Webhooks](#webhooks) GitHub App [#github-app] We have a dedicated guide for setting up a GitHub App, which you can follow here: [/github/setup-app](/applications/ci-cd/github/setup-app). Coolify automatically enables "Auto Deploy" after you set up your GitHub App. If it doesn't, enable it on your application by following these steps: 1. Open your application configuration page. 2. Go to the "Advanced" page. 3. Enable "Auto Deploy" under the general section. GitHub Actions [#github-actions] We have a dedicated guide for setting up GitHub Actions, which you can follow here: [/github/actions](/applications/ci-cd/github/actions). Webhooks [#webhooks] 1\. Enable Auto Deploy [#1-enable-auto-deploy] 1. Open your application configuration page. 2. Go to the "Advanced" page. 3. Enable "Auto Deploy" under the general section. 2\. Set Up GitHub Webhook Secret [#2-set-up-github-webhook-secret] 1. Enter a GitHub webhook secret (this must be a random string; you can use tools like [Random String Generator](https://getrandomgenerator.com/string)). 2. Save the webhook URL somewhere safe, we'll need it later. A webhook secret acts like a password. Coolify only accepts the webhook if the secret matches. 3\. Set Up Webhook on GitHub [#3-set-up-webhook-on-github] 1. Go to your repository settings page. 2. Click on "Webhooks" from the sidebar. 3. Click the "Add webhook" button. 4. Enter the previously copied webhook URL from Coolify in the "Payload URL" field. 5. Enter the webhook secret from Coolify in the "Secret" field. 6. Enable "Enable SSL verification". 7. Select "Just the `push` event". 8. Enable "Active". 9. Click the "Add webhook" button. After clicking "Add webhook", you'll see a page like the one shown below: That's it! Coolify will automatically redeploy your application whenever you push changes to your repository. # GitHub Deploy Key (/docs/applications/ci-cd/github/deploy-key) GitHub Deploy Key [#github-deploy-key] Deploy keys allow you to grant read-only access to a single private GitHub repository without using a personal access token or SSH key tied to your account. When using deploy keys, Coolify can clone and deploy from private repositories securely, ensuring that only the specified repository is accessible. Why Use Deploy Keys with Coolify? [#why-use-deploy-keys-with-coolify] 1. **Secure Access**: Grant read-only access to a single repository without sharing to many repositories. 2. **Repository-Specific**: Deploy keys are scoped to one repository. 3. **No Account Exposure**: Prevents potential security risks if the key is compromised. 4. **Cannot Install Github App**: Deploy keys can be used when you cannot install a GitHub App to your organization. When Not to Use Deploy Keys [#when-not-to-use-deploy-keys] 1. **Multiple Repositories**: If you need access to multiple private repositories, consider using a GitHub App. *** The following data is used as an example in this guide. Please replace it with your actual data when following the steps: * **Repository Owner:** `ShadowArcanist` * **Repository Name:** `coolify-dev` * **Deploy Key Name:** `Deploy Key Tutorial` * **SSH URL:** `git@github.com:ShadowArcanist/coolify-dev.git` 1\. Create a Private Key on Coolify [#1-create-a-private-key-on-coolify] 1. In your Coolify dashboard, click on **Keys & Tokens** from the sidebar. 2. Click on **Private keys** tab. 3. Click the **+ Add** button to create a new private key. 4. Click **Generate new RSA SSH Key** or **Generate new ED25519 SSH Key** to generate a key pair. 5. Copy the public key. 6. Click **Continue** to save the keys. You can also generate a key externally using the `ssh-keygen` command and paste the private key into Coolify: ```bash ssh-keygen -t rsa -b 4096 -C "coolify-deploy-key" ``` Then, copy the contents of the generated `.pub` file for the next step. 2\. Add Deploy Key on GitHub [#2-add-deploy-key-on-github] 1. Go to your GitHub repository settings. 2. Navigate to **Deploy keys** in the left sidebar. 3. Click **Add deploy key** button. You can also access the deploy keys page directly at `https://github.com/YOUR_USERNAME/YOUR_REPO_NAME/settings/keys` 4. Enter a title for your deploy key (e.g., `Coolify Deploy Key`). 5. Paste the public key you copied from Coolify. 6. Make sure **Allow write access** is unchecked (deploy keys should be read-only). 7. Click **Add key** to save. 3\. Copy Repository SSH URL [#3-copy-repository-ssh-url] 1. Go to your GitHub repository. 2. Click the **Code** button. 3. Select the **Local** tab. 4. Click the **SSH** tab. 5. Copy the SSH URL (e.g., `git@github.com:ShadowArcanist/coolify-dev.git`). 4\. Create a New Resource on Coolify [#4-create-a-new-resource-on-coolify] 1. Select your project from the Coolify dashboard. 2. Click the **+ New** button to create a new resource. 5\. Select Private Repository (with Deploy Key) as Resource Type [#5-select-private-repository-with-deploy-key-as-resource-type] Select **Private Repository (with Deploy Key)** from the available resource types. 6\. Choose Your Server [#6-choose-your-server] Coolify automatically selects the `localhost` server if you don't have any remote servers connected. In such cases, skip to the next step. Choose the server where you want to deploy the application. 7\. Choose Your Deploy Key [#7-choose-your-deploy-key] Select the private key you created in Coolify from the list of available private keys. 8\. Configure the Application and Deploy [#8-configure-the-application-and-deploy] 1. Paste the SSH URL you copied from GitHub (e.g., `git@github.com:ShadowArcanist/coolify-dev.git`). 2. After entering the repository link, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on [applications](/applications) for more details.) Once configured, deploy your application. That's it! # Overview (/docs/applications/ci-cd/github/overview) GitHub Integration [#github-integration] Coolify simplifies deploying applications from your GitHub repositories or Docker images hosted on GitHub Container Registry. GitHub integration with Coolify supports deploying from both private and public repositories, automatic deployments on new commits, and pull request deployments. Ways to Use GitHub with Coolify [#ways-to-use-github-with-coolify] You can integrate GitHub with Coolify in several ways, depending on your needs. Below are the available options, each linked to a detailed guide for easy setup: | Method | Description | | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Public Repository](/applications/ci-cd/github/public-repository) | Deploy applications directly using the URL of a public repository. | | [Private Repository using GitHub App](/applications/ci-cd/github/setup-app) | Install the GitHub App on your personal account or organization to deploy both private and public repositories. | | [Private Repository using Deploy Key](/applications/ci-cd/github/deploy-key) | Deploy applications from private repositories using a deploy key. | | [Automatic Deployments](/applications/ci-cd/github/auto-deploy) | Automatically deploy new versions of your application when commits are pushed to a specific branch in your GitHub repository. | | [Build and Deploy Using GitHub Actions](/applications/ci-cd/github/actions) | Build your application on GitHub using GitHub Actions as part of your CI/CD pipeline, push it to any Docker registry (such as GHCR or Docker Hub), and automatically deploy on Coolify. | | [Preview Deployments](/applications/ci-cd/github/preview-deploy) | Automatically deploy new versions of your application based on pull requests. | # GitHub Preview Deploy (/docs/applications/ci-cd/github/preview-deploy) GitHub Preview Deploy [#github-preview-deploy] Preview deployments allow Coolify to automatically deploy new versions of your application whenever someone opens a pull request (PR) on your GitHub repository. These preview deployments are automatically deleted once the associated pull request is merged or closed, ensuring a clean environment. Features [#features] * **[Scoped Deployments](#scoped-deployments)**: Control who can trigger PR preview deployments. * **[Scoped Secrets](#scoped-secrets)**: Keep production and preview environment variables separate. * **[Automated Comments](#automated-comments)**: Post deployment status updates directly on pull requests. Preview Deployments Options [#preview-deployments-options] * **Preview URL Template:** Each preview deployment gets its own unique URL based on this template. * Use `{{random}}` to generate a random subdomain each time a PR is deployed. * Use `{{pr_id}}` to use the pull request ID as the subdomain. You need to set up a **wildcard** `A` record for the subdomain you want to use for preview deployments, pointing to your server's IP address. For example, to use `https://123.preview.shadowarcanist.com`, create an A record for `*.preview.shadowarcanist.com` pointing to your server's IP address. * **Load Pull Requests:** Allows you to manually fetch all open pull requests on your repository. This is useful if you already had open PRs before setting up preview deployments. Coolify does not automatically deploy preview deployments for pull requests that were opened before preview deployments were enabled. You need to manually deploy these by clicking the 'Deploy' button on the pull request list in the Preview Deployments page. Scoped Deployments [#scoped-deployments] If anyone can trigger a new preview deployment by creating a pull request, they could run arbitrary code directly on your environment, potentially gaining access to your environment or secrets. Coolify allows you to configure who can trigger new preview deployments to prevent this: * **Preview Deployments**: Enables the Preview Deployments feature, and only repository members, collaborators, and contributors can trigger PR deployments. * **Allow Public PR Deployments**: Anyone can trigger PR deployments. Scoped Secrets [#scoped-secrets] Coolify separates environment variables for production and preview deployments, keeping your secrets safe. * **Production Environment Variables:** These variables are used only in your main deployment. They remain fully isolated and are never exposed to preview deployments triggered from pull requests. * **Preview Deployment Environment Variables:** A separate set of variables used only for PR-based preview deployments. These variables can safely contain non-sensitive or limited-scope values, ensuring contributors' pull requests cannot access production secrets. Automated Comments [#automated-comments] Coolify posts comments on pull requests with the deployment status and automatically updates them if the status changes. Automated comments only work if you are using the GitHub App for preview deployments. Setup Methods [#setup-methods] There are two methods to set up preview deployments on Coolify: * [Using GitHub App](#setup-using-github-app) * [Using Webhooks](#setup-using-webhooks) Setup Using GitHub App [#setup-using-github-app] We have a dedicated guide for setting up the GitHub App, so please follow it first: [/applications/ci-cd/github/setup-app](/applications/ci-cd/github/setup-app). As part of the setup, ensure Preview Deployments is configured correctly. The steps differ depending on whether you use Automated or Manual setup, as shown below. Before you click "Register now", enable the "Preview Deployments" option. That's it! While setting up permissions for the GitHub App, do the following: 1. Under the "**Permissions**" section, click on "**Repository permissions**". 2. Set access to `Read and write` for `Pull Requests`. 3. Scroll down to the "**Subscribe to events**" section. 4. Enable the `Pull requests` option. That's it! *** If you have already set up the GitHub App without enabling the "Preview Deployments" feature, follow these steps: 1. In your Coolify dashboard, click on **Sources** from the sidebar, then select your GitHub App. 2. Click the **Update** button in the "Permissions" section (this will redirect you to GitHub). 3. Under the "**Permissions**" section, click on "**Repository permissions**". 4. Set access to `Read and write` for `Pull Requests`. 5. Scroll down to the "**Subscribe to events**" section. 6. Enable the `Pull requests` option. *** Setup Using Webhooks [#setup-using-webhooks] 1. Enter a GitHub webhook secret (this must be a random string; you can use tools like [Random String Generator](https://getrandomgenerator.com/string)). 2. Save the webhook URL somewhere safe—we'll need it later. A webhook secret acts like a password. Coolify only accepts the webhook if the secret matches. 3. Go to your repository settings page. 4. Click on **Webhooks** from the sidebar. 5. Click the **Add webhook** button. 6. Enter the previously copied webhook URL from Coolify in the "Payload URL" field. 7. Enter the webhook secret from Coolify in the "Secret" field. 8. Enable "Enable SSL verification". 9. Select "Let me select individual events". 10. Select "Pull Requests". 11. Enable "Active". 12. Click the **Add webhook** button. After clicking "Add webhook", you'll see a page like the one shown below: That's it! Coolify will automatically deploy preview deployments when a new pull request is created. # Deploy Public Repository (/docs/applications/ci-cd/github/public-repository) Deploy Public Repository [#deploy-public-repository] You can deploy applications from any public GitHub repository by simply providing the repository URL. 1\. Create a New Resource on Coolify [#1-create-a-new-resource-on-coolify] 1. Select your project from the Coolify dashboard. 2. Click the **+ New** button to create a new resource. 2\. Select Public Repository as Resource Type [#2-select-public-repository-as-resource-type] Choose **Public Repository** from the available resource types. 3\. Choose Your Server [#3-choose-your-server] Coolify automatically selects the `localhost` server if you don't have any remote servers connected. In such cases, skip to the next step. Select the server where you want to deploy the application. 4\. Enter Your Repository Link [#4-enter-your-repository-link] Paste the URL of your public GitHub repository. The branch will be **automatically selected** based on the provided URL. * [https://github.com/coollabsio/coolify-examples](https://github.com/coollabsio/coolify-examples) → **main** branch will be selected. * [https://github.com/coollabsio/coolify-examples/tree/nodejs-fastify](https://github.com/coollabsio/coolify-examples/tree/nodejs-fastify) → **nodejs-fastify** branch will be selected 5\. Configure the Application and Deploy [#5-configure-the-application-and-deploy] After entering the repository link, click **Check Repository**. Then, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on [builds](/applications/build-packs) for more details.) Once configured, deploy your application. That's it! # Setup GitHub App (/docs/applications/ci-cd/github/setup-app) GitHub App [#github-app] Github app allows you to grant access to a single or multiple private repositories from your either personal github account or your organization on github. Why use github app with Coolify? [#why-use-github-app-with-coolify] Scoped Access: The GitHub app lets you grant Coolify access to a specific repository, a selected group of repositories, or even all of your repositories. This gives you flexibility and better control over what Coolify can access. When Not to Use github app with Coolify? [#when-not-to-use-github-app-with-coolify] Lack of Permission: If you don't have the necessary permissions to install the GitHub app, or if you prefer not to install it, then it’s best not to use it with Coolify. Installation Methods [#installation-methods] There are two ways to install Github App on Coolify: * [Automated Installation](/applications/ci-cd/github/setup-app#automated-installation) (Recommended) * [Manual Installation](/applications/ci-cd/github/setup-app#manual-installation) We highly recommend the Automated Installation method as it automates the process and reduces the chance of errors. The following data is used as an example in this guide. Please replace it with your actual data when following the steps: * **GitHub App Name on Coolify:** `Github App Tutorial` * **GitHub App Name on Github:** `coolify-github-app-tutorial` * **Webhook Endpoint:** `https://coolboxy.shadowarcanist.internal` Automated Installation [#automated-installation] 1\. Create a Github App on Coolify [#1-create-a-github-app-on-coolify] 1. In your Coolify dashboard, click on Sources from the sidebar. 2. Click the + Add button to create a new github app. 3. Enter a Name for your App 4. Enter your github organization name (if you are adding the github app to your github account then leave this field empty) and click continue 1) If you are using Selfhost or Enterprise version of Github then you can enter your github details on the Selhost/Enterprise github section. 2) The "System wide" option allows all teams you have on your coolify instance to use this specific github app, if you only want the current team to use the github app then leave this option unchecked. Coolify cloud users won't see the option "System wide" because this option will enable your github app to all Cloud users so this option is disabled on Coolify Cloud 2\. Set Webhook Endpoint [#2-set-webhook-endpoint] 1. Select the endpoint for github to send Webhook when a event (commit, pr) happens on github. If this endpoint is not reachable then automatic deployments won't work so if you decide to close port 8000 on your server you have to set the webhook endpoint as your Coolify dashboard domain 2. Preview deployments are enabled by default and you can disable them if you dont want them 3. Click on Register now button (this will take you to github) 3\. Create Github App on Github [#3-create-github-app-on-github] 1. Give your github app a name (this will be shown on your github app list and you can always change it later) 2. Click on Create app button (this will take you back to your coolify dashboard) 4\. Allow Github app access to repositories [#4-allow-github-app-access-to-repositories] 1. Click on "Install repositories on Github" button 2. Select the repositories that you want this app to have access to (you can give access to all repositories or specific repositories) 3. Click on "Install" button (this will take you back to your Coolify dashboard) 5\. Create a New Resource on Coolify [#5-create-a-new-resource-on-coolify] 1. Select your project from the Coolify dashboard. 2. Click the **+ New** button to create a new resource. 6\. Select Private Repository (with Github App) as Resource Type [#6-select-private-repository-with-github-app-as-resource-type] Select **Private Repository (with Github App)** from the available resource types. 6\. Choose Your Server [#6-choose-your-server] Coolify automatically selects the `localhost` server if you don't have any remote servers connected. In such cases, skip to the next step. Choose the server where you want to deploy the application. 7\. Choose Your Github App [#7-choose-your-github-app] Select the Github App you created in Coolify from the list of available Apps. 8\. Configure the Application and Deploy [#8-configure-the-application-and-deploy] 1. Choose Repository and click on "Load Repository" button. 2. After selecting the repository, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on [builds](/applications/build-packs) for more details.) Once configured, deploy your application. That's it! *** **The Automated installation guide ends here. If you’ve followed the steps above, you can start using Github Apps now. The guide below is for those who want to manually install and set up Github App.** Manual Installation [#manual-installation] 1\. Create a Github App on Coolify [#1-create-a-github-app-on-coolify-1] 1. In your Coolify dashboard, click on Sources from the sidebar. 2. Click the + Add button to create a new github app. 3. Enter a Name for your App 4. Enter your github organization name (if you are adding the github app to your github account then leave this field empty) and click continue 1) If you are using Selfhost or Enterprise version of Github then you can enter your github details on the Selhost/Enterprise github section. 2) The "System wide" option allows all teams you have on your coolify instance to use this specific github app, if you only want the current team to use the github app then leave this option unchecked. Coolify cloud users won't see the option "System wide" because this option will enable your github app to all Cloud users so this option is disabled on Coolify Cloud 5. Click on Continue button 6. Save the Source ID of github app somewhere safe (source id is the UUID you see on your url bar after `/github/`) We will need the following data to setup the github app: * App ID * Installation ID * Client ID * Client Secret * Webhook Secret * SSH Key We will get these data in the next few steps. 2\. Create a App on Github [#2-create-a-app-on-github] Creating apps on github slightly varies for personal accounts and organizations so choose the correct one from the below section 1. Go to your github account settings 2. On the sidebar scroll down till you see "developer settings" and click on it 3. Click the "New github app" button 1. Go to your github Organization settings 2. On the sidebar scroll down till you see "**developer settings**" and click on it 3. Click on "Github Apps" 4. Click the "New github app" button 3\. Setup the Github App on Github [#3-setup-the-github-app-on-github] 1. Give your app a name 2. Enter homepage url for your app (this can be anything) 3. Scroll down till you see the "**Post Installation**" section 4. Enter Setup URL: `https://coolboxy.shadowarcanist.internal/webhooks/source/github/install?source=a8000cg0g0ogcc0ggkk8ow4k` 5. Enable the option `Redirect on Update` 6. Enter Webhook URL: `https://coolboxy.shadowarcanist.internal/webhooks/source/github/events` You have to replace `https://coolboxy.shadowarcanist.internal` with your Coolify dashboard url and replace `a8000cg0g0ogcc0ggkk8ow4k` with the Source ID [Step 1](#_1-create-a-github-app-on-coolify-1) 7. Enter Webhook Secret (this has to be a random string, you can use tools like [Random String Generator](https://getrandomgenerator.com/string)) 8. Enable the option `Enable SSL verification` 9. Scroll down till you see the "**Permissions**" section 10. Set Access to `Read-only` for `Contents` 11. Set Access to `Read and write` for `Pull Requests` (Only needed if you plan to use Preview deployments feature) 12. Set Access to `Read-only` for `Email addresses` On the screenshot above for permissions section we have hidden lot of Permission and only shown the Permission needed to setup Github app for Coolify. 13. Scroll down till you see the "**Subscribe to events**" section 14. Enable the option `Push` 15. Enable the option `Pull requests` (Only needed if you plan to use Preview deployments feature) 16. Select the option `Only on this account` (Prevents others from installing our Github app to their github accounts) 17. Click the button "**Create Github App**" 18. Save the `App ID` and `Client ID` somewhere safe (we have to enter this on Coolify later) 19. Click the `Generate a new client secret` button 20. Save the `client secret` somewhere safe (we have to enter this on Coolify later) 21. Scroll down till you see the "**Private keys**" section 22. Click the `Generate a private key` button (this will automatically download the private key as a `.pem` file) 23. Click "Install App" from the sidebar 24. Click the "**Install**" button 25. Select the repositories you want the app to have access to. 26. Click the "**Install**" button 27. Click the Settings icon (this will take you to your account or organization applications page) 28. Save the `Installation ID` somewhere safe (Installation ID is the number you see on your url bar after `/installations/`) 4\. Add Private keys on Coolify [#4-add-private-keys-on-coolify] 1. In your Coolify dashboard, click on **Keys & Tokens** from the sidebar. 2. Click on **Private keys** tab. 3. Click the **+ Add** button to add a new private key. 4. Give your Private key a name 5. Paste the content of the `.pem` file which github automatically downloaded to your machine when you setup the Github App on Github 6. Click on "**Continue**" button 7. In your Coolify dashboard, click on **Sources** from the sidebar and select your Github app from the list 8. Enter the details (App ID, Installation ID etc..) you saved on previous steps 9. On "Private key" select the key you just added to Coolify 10. Click on "**Sync Name**" button, if you see a success message then you have done everything correctly and you can start using the Github app! 5\. Create a New Resource on Coolify [#5-create-a-new-resource-on-coolify-1] 1. Select your project from the Coolify dashboard. 2. Click the **+ New** button to create a new resource. 6\. Select Private Repository (with Github App) as Resource Type [#6-select-private-repository-with-github-app-as-resource-type-1] Select **Private Repository (with Github App)** from the available resource types. 6\. Choose Your Server [#6-choose-your-server-1] Coolify automatically selects the `localhost` server if you don't have any remote servers connected. In such cases, skip to the next step. Choose the server where you want to deploy the application. 7\. Choose Your Github App [#7-choose-your-github-app-1] Select the Github App you created in Coolify from the list of available Apps. 8\. Configure the Application and Deploy [#8-configure-the-application-and-deploy-1] 1. Choose Repository and click on "Load Repository" button. 2. After selecting the repository, configure the buildpack, ports, and other settings. (Refer to our dedicated guide on [builds](/applications/build-packs) for more details.) Once configured, deploy your application. That's it! # Switch GitHub Apps (/docs/applications/ci-cd/github/switch-apps) Switch GitHub Apps [#switch-github-apps] Switching GitHub Apps allows you to change the GitHub App associated with your deployed applications, for example, when moving repositories to a new organization or account. Why Switch GitHub Apps? [#why-switch-github-apps] 1. **Organization Changes**: You've moved repositories to a new GitHub organization that requires a different GitHub App. 2. **Access Management**: You want to use a GitHub App with different permissions or repository access. This feature is introduced in **Coolify v4.0.0-beta.408**. To follow this guide, you **must** be using Coolify v4.0.0-beta.408 or a higher version. 1\. Move Repositories (Optional) [#1-move-repositories-optional] If your goal is to move a repository to a different account or organization, go ahead and transfer it on GitHub. If you just want to use a different GitHub App without changing repositories, you can skip this step. 2\. Add New GitHub App to Coolify [#2-add-new-github-app-to-coolify] We have a dedicated guide for setting up a GitHub App, which you can follow here: [/applications/ci-cd/github/setup-app](/applications/ci-cd/github/setup-app). Follow that guide and come back here. 3\. Set Up Repository Access [#3-set-up-repository-access] After adding the new GitHub App, verify that it has access to the correct repositories by following these steps: 1. In your Coolify dashboard, click on **Sources** from the sidebar, then select your new GitHub App. 2. Click the **Update Repositories** button (this will redirect you to GitHub). 3. Under the Repository access section, check if you can see the repositories that you want to use. 4\. Switch Git Source on Coolify [#4-switch-git-source-on-coolify] 1. Open your application configuration page. 2. Go to the "Git Source" page. 3. Select your new GitHub App. 5\. Update Repository Name (If Applicable) [#5-update-repository-name-if-applicable] If you have moved your repository to a new organization or account, update the repository name accordingly (e.g., from `shadowarcanist/switch-apps-guide` to `airoflare/switch-apps-guide`). You can skip this step if you didn't move your repository. 6\. Redeploy the Application [#6-redeploy-the-application] To apply the new GitHub App to your application, redeploy it by clicking the **Redeploy** button. That's it! # Integration (/docs/applications/ci-cd/gitlab/integration) GitLab Integration [#gitlab-integration] Public Repositories [#public-repositories] You can use public repositories without any additional setup. 1. Select the `Public repository` option in the Coolify when you create a new resource. 2. Add your repository URL to the input field, for example: `https://gitlab.com/andrasbacsai/coolify-examples` You can only use the https URL. 3. That's it! Coolify will automatically pull the latest version of your repository and deploy it. Private Repositories [#private-repositories] Private repositories require a few more steps to setup. 1. Add a private key (aka `Deploy Keys`) to Coolify and to your GitLab repository in the `Settings` / `Repository` / `Deploy Keys` menu. * You can generate a new key pair with the following command: ```bash ssh-keygen -t rsa -b 4096 -C "deploy_key" ``` * Or you can also use Coolify to generate a new key for you in the `Keys & Tokens` menu. 2. Create a new resource and select the `Private Repository (with deploy key)` 3. Add your repository URL to the input field, for example: `git@gitlab.com:andrasbacsai/coolify-examples.git` You need to use the SSH URL, so the one that starts with `git@`. 4. That's it! Coolify will automatically pull the latest version of your repository and deploy it. Public Container Registry [#public-container-registry] You can use public container registry without any additional setup. 1. Select the `Docker Image` option in the Coolify when you create a new resource. 2. Add your public container registry URL and also the tag to the input field, for example: `registry.gitlab.com/username/repository:latest`. 3. Press the `Deploy` button. 4. That's it! Coolify will automatically pull the latest version of your container registry and deploy it. Private Container Registry [#private-container-registry] Private container registry require a few more steps to setup. 1. Add a `Deploy Token` in your GitLab repository in the `Settings` / `Repository` / `Deploy Token` with scope `read_registry`. This step will generate credentials `username` and `token` 2. login docker with that credentials in your coolify server ``` echo "token-xxx" | docker login registry.privategitlab.com -u gitlab+deploy-token-xxx --password-stdin ``` 3. Select the `Docker Image` option in the Coolify when you create a new resource. 4. Add your private container registry URL and also the tag to the input field, for example: `registry.privategitlab.com/username/repository:latest`. 5. Press the `Deploy` button. 6. That's it! Coolify will automatically pull the latest version of your container registry and deploy it. Automatic commit deployments with webhooks (Optional) [#automatic-commit-deployments-with-webhooks-optional] You can add a custom webhook URL to your GitLab repository to trigger a new deployment when you push to your repository. This can be set on either public or private repositories. In your resource, there is a `Webhooks` menu. In the `Manual Git Webhooks` section, you can find the URL what you need to set in your GitLab repository. 1. Set a secret key in the `GitLab Webhook Secret` input field. 2. Go to your repository in GitLab and open the `Settings` / `Webhooks` menu. 3. Add the URL from Coolify to the `URL` input field and the secret token. 4. Select the `Push events` option. 5. That's it! Now when you push to your repository, GitLab will send a webhook request to Coolify and it will trigger a new deployment. Merge request deployments with webhooks (Optional) [#merge-request-deployments-with-webhooks-optional] You can add a custom webhook URL to your GitLab repository to trigger a new deployment when you create a new merge request. This can be set on either public or private repositories. The process is the same as the previous one, but you need to select the `Merge request events` option in the `Settings` / `Webhooks` menu. # CI/CD with Git Providers (/docs/applications/ci-cd) CI/CD with Git Providers [#cicd-with-git-providers] Applications in Coolify are designed to be deployed directly from **Git repositories**, enabling continuous integration and continuous deployment (CI/CD) workflows. This means your applications automatically update when you push code changes to your repository. How Git Integration Works [#how-git-integration-works] When you deploy an application in Coolify, you connect it to a Git repository from **any Git provider**. Coolify works with all Git platforms, including: * **[GitHub](/applications/ci-cd/github/overview)** - Full GitHub App integration or deploy keys * **[GitLab](/applications/ci-cd/gitlab/integration)** - GitLab integration with webhooks * **[Bitbucket](/applications/ci-cd/bitbucket/integration)** - Bitbucket integration with webhooks * **[Gitea](/applications/ci-cd/gitea/integration)** - Self-hosted Git platform * **Any other Git provider** - Works with any Git-compatible platform with publicly accessible repositories or using deploy keys Once connected, Coolify: 1. **Pulls your source code** from the repository 2. **Builds a Docker image** using your chosen [build pack](/applications/build-packs) 3. **Deploys the container** to your server 4. **Watches for changes** and automatically redeploys when you push new commits (if auto-deploy is enabled) Key Benefits of Git-Based Deployments [#key-benefits-of-git-based-deployments] Automatic Deployments [#automatic-deployments] Push code to your repository and Coolify automatically builds and deploys your application. No manual intervention needed. Preview Deployments [#preview-deployments] Test pull requests in isolated environments before merging to production. Each PR gets its own unique URL. Version Control Integration [#version-control-integration] * Track deployment history alongside your code commits * Roll back to previous versions easily * See exactly what code is running in production CI/CD Workflows [#cicd-workflows] * Integrate with GitHub Actions, GitLab CI, and other CI tools * Run tests before deployment * Automate complex deployment pipelines If you want to deploy your own application **without connecting to a Git provider**, you can deploy it as a [Service](/services/introduction) instead. Services allow you to: * Upload a Docker Compose file directly to Coolify * Deploy from Docker images without source code * Manage the application manually without Git integration This is useful for scenarios where you build your Docker images elsewhere or prefer manual control over deployments. Repository Access Methods [#repository-access-methods] Coolify supports multiple ways to access your Git repositories: Public Repositories [#public-repositories] Simply provide the HTTPS URL of your public repository. No authentication needed. Works with any Git provider. Private Repositories [#private-repositories] Choose from authentication methods based on your Git provider: 1. **Git Provider App Integration (Recommended for supported providers)** * Available for GitHub * Full integration with automatic webhooks * Pull request deployments * Commit status updates * No SSH key management 2. **Deploy Keys (Works with any Git provider)** * SSH-based authentication * Universal support - works with any Git platform * More manual webhook setup required * Better for air-gapped or restricted environments * Ideal for custom or self-hosted Git servers Supported Git Providers [#supported-git-providers] While we provide detailed integration guides for popular platforms, **Coolify works with any Git provider** that supports standard Git protocols: * **Public Repositories**: Any Git provider (no authentication required) * **With App Integration**: GitHub * **With Deploy Keys**: Any Git provider (GitHub, GitLab, Bitbucket, Gitea, Gogs, Forgejo, self-hosted solutions, and more) Next Steps [#next-steps] Ready to connect your Git provider? Choose your platform for detailed setup guides: * **[GitHub Integration](/applications/ci-cd/github/overview)** - Connect GitHub repositories * **[GitLab Integration](/applications/ci-cd/gitlab/integration)** - Connect GitLab repositories * **[Bitbucket Integration](/applications/ci-cd/bitbucket/integration)** - Connect Bitbucket repositories * **[Gitea Integration](/applications/ci-cd/gitea/integration)** - Connect self-hosted Gitea * **[Other Git Providers](/applications/ci-cd/other-providers)** - Connect Gogs, Forgejo, or any custom Git server Or learn about [Build Packs](/applications/build-packs) to understand how Coolify transforms your code into running containers. # Other Git Providers (/docs/applications/ci-cd/other-providers) Other Git Providers [#other-git-providers] This guide will show you how to use other Git provider with Coolify, such as Gogs, Forgejo, and any other Git-compatible platform. Public Repositories [#public-repositories] You can use public repositories from any Git provider without any additional setup. 1. Select the `Public repository` option in Coolify when you create a new resource. 2. Add your repository URL to the input field, for example: `https://git.example.com/username/repository` You can only use the HTTPS URL. 3. That's it! Coolify will automatically pull the latest version of your repository and deploy it. Private Repositories [#private-repositories] Private repositories require deploy keys for authentication. With Deploy Keys [#with-deploy-keys] 1. Add a private key (aka `Deploy Keys`) to Coolify and to your Git repository in the repository settings (usually under `Settings` / `Deploy Keys` or `SSH Keys`). * You can generate a new key pair with the following command: ```bash ssh-keygen -t ed25519 -C "coolify_deploy_key" ``` * Or you can also use Coolify to generate a new key for you in the `Keys & Tokens` menu. 2. Create a new resource and select the `Private Repository (with deploy key)` 3. Add your repository URL to the input field, for example: `git@git.example.com:username/repository.git` You need to use the SSH URL, so the one that starts with `git@`. 4. That's it! Coolify will automatically pull the latest version of your repository and deploy it. Automatic commit deployments (Optional) [#automatic-commit-deployments-optional] For Git providers without direct integration, automatic deployments require triggering the deployment via the Deploy Webhook endpoint. This requires your Git provider to support workflow automation or webhook actions (similar to GitHub Actions). If your provider doesn't support this, you'll need to trigger deployments manually through the Coolify dashboard. Prerequisites [#prerequisites] 1. Create a [Coolify API Token](/api-reference/authorization) in your Coolify dashboard 2. Get the Deploy Webhook URL from your resource (Your resource → `Webhooks` menu → `Deploy Webhook`) Setup with Workflow/CI System [#setup-with-workflowci-system] If your Git provider supports workflow automation (like GitHub Actions, GitLab CI, Forgejo Actions, etc.), you can trigger deployments automatically: 1. Add your Coolify API token to your repository secrets (e.g., `COOLIFY_TOKEN`) 2. Add the Deploy Webhook URL to your repository secrets (e.g., `COOLIFY_WEBHOOK`) 3. Create a workflow file that triggers on push events: ```yaml # Example workflow (syntax varies by provider) on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - name: Trigger Coolify Deployment run: | curl --request GET "${{ secrets.COOLIFY_WEBHOOK }}" \ --header "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}" ``` 4. That's it! Now when you push to your repository, the workflow will trigger and send a request to Coolify to start a new deployment. Some Git providers allow webhooks to send custom headers. If supported, you can configure a webhook to send a GET request with the `Authorization: Bearer YOUR_TOKEN` header directly to the Deploy Webhook URL, without needing a workflow file. Supported Git Providers [#supported-git-providers] This method works with any Git provider that supports standard Git protocols, including: * Gogs * Forgejo * Self-hosted GitLab CE/EE instances * Custom Git servers (gitolite, etc.) * Any Git-over-SSH compatible platform Comparison with App Integration [#comparison-with-app-integration] | Feature | Other Providers | GitHub, GitLab, Bitbucket, Gitea | | --------------------- | -------------------------- | -------------------------------- | | Repository access | ✅ Yes | ✅ Yes | | Manual deployments | ✅ Yes | ✅ Yes | | Auto-deploy | ⚠️ Requires workflow setup | ✅ Automatic | | Pull request previews | ❌ No | ✅ Yes | # Django (/docs/applications/django) Django [#django] Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design. Requirements [#requirements] 1. Set the base directory where your `requirements.txt` and `manage.py` files are located. > In the example repository, it is `/coolify`. 2. Add `gunicorn` to the `requirements.txt` file, [official docs](https://gunicorn.org/install/). 3. Add `localhost` and your `domain` to `ALLOWED_HOSTS` in `settings.py` file, [ official docs](https://docs.djangoproject.com/en/4.2/ref/settings/#allowed-hosts). > `Localhost` is required for health checks to work properly. # Applications (/docs/applications) Applications [#applications] Application could be any type of web application. It could be a static site, a NodeJS application, a PHP application, etc. For complex applications, you can use Docker Compose based deployments or the one-click services. How Deployments Work [#how-deployments-work] Coolify deploys all applications as Docker containers. This means your app runs inside an isolated container on your server. **Key Concepts:** * **Docker Image:** A packaged version of your application with all dependencies included * **Container:** A running instance of your Docker image * **Build Process:** Transforms your source code into a Docker image ready for deployment You have two options for deploying applications: 1. **Build on Coolify:** Use [build packs](/applications/build-packs) to automatically create Docker images from your source code 2. **Use Pre-built Images:** Deploy existing images from registries like [Docker Hub](https://hub.docker.com/?utm_source=coolify.io) or [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry?utm_source=coolify.io) Building Docker images can be resource-intensive. You can use a dedicated [build server](/knowledge-base/server/build-server) to handle builds separately from your production server. Examples [#examples] The list is not complete. You can host almost any application that you want, not just the ones listed here. * [Vite](/applications/vite) * [Django](/applications/django) * [Jekyll](/applications/jekyll) * [Vue.js](/applications/vuejs) * [Next.js](/applications/nextjs) * [Nuxt](/applications/nuxt) * [Laravel](/applications/laravel) * [Symfony](/applications/symfony) * [Ruby on Rails](/applications/rails) * [SvelteKit](/applications/svelte-kit) General Configuration [#general-configuration] Commands [#commands] You can overwrite the default commands by setting a custom value on the UI. * Build * Install * Start If you leave it empty, Nixpacks will detect which commands to run. For example, in Nodejs, it will check the lock files and run `npm ci` or `yarn install` or `pnpm install` accordingly. Base Directory [#base-directory] It is useful for monorepos. You can set the base directory for all the commands that will be executed by Coolify. Public Directory [#public-directory] If you are building a static site, it is important to set the public directory, so the builder will know which directory to serve. Port Exposes [#port-exposes] Port exposes are required for Docker Engine to know which ports to expose. The first port will be the default port for health checks. Examples: If you have a NodeJS application that listens on port 3000, you can set it like this: `3000`. If you have a PHP-FPM application that listens on port 9000, you can set it like this: `9000`. If you have a Nginx server that listens on port 80, you can set it like this: `80`. Port Mappings [#port-mappings] You will lose some functionality if you map a port to the host system, like `Rolling Updates`. If you would like to map a port to the host system (server), you can do it here like this: `8080:80`. This will map the port 8080 on the host system to the port 80 inside the container. If you would like to get performance boost and you do not need any domain (websocket server with VERY high traffic), you can map its port to the host, so the request will not go through the proxy. Advanced [#advanced] Static Site (Is it a static site?) [#static-site-is-it-a-static-site] > This feature is only available for Nixpacks buildpacks. If you need to serve a static site (SPA, HTML, etc), you can set this to `true`. It will be served by Nginx. `Disabled by default`. Force HTTPS [#force-https] If you would like to force HTTPS, so no HTTP connections allowed, you can set this to `true`. `Enabled by default`. Auto Deploy [#auto-deploy] > This feature is only available for GitHub App based repositories. If you would like to deploy automatically when a new commit is pushed to the repository, you can set this to `true`. `Enabled by default`. Preview Deployments [#preview-deployments] Preview deployments are a great way to test your application before merging it into the main branch. Imagine it like a staging environment. URL Template [#url-template] You can setup your preview URL with a custom template. Default is `{{pr_id}}.{{domain}}`. This means that if you open a Pull Request with the ID `123`, and you resource domain is `example.com` the preview URL will be `123.example.com`. If you have several domains for your resource, the first will be used as the `{{ domain }}` part. Automated Preview Deployments [#automated-preview-deployments] > This feature is only available for GitHub App based repositories. If you would like to deploy a preview version of your application (based on a Pull Requests), you can set this to `true`. `Disabled by default`. If set to `true`, all PR's that are opened against the resource's configured branch, will be deployed to a unique URL. Manually Triggered Preview Deployments [#manually-triggered-preview-deployments] You can manually deploy a Pull Request to a unique URL by clicking on the `Deploy` button on the Pull Request page. Git Submodules [#git-submodules] If you are using git submodules, you can set this to `true`. `Enabled by default`. Git LFS [#git-lfs] If you are using git lfs, you can set this to `true`. `Enabled by default`. Environment Variables [#environment-variables] [Read here](/knowledge-base/environment-variables) Persistent Storage [#persistent-storage] [Read here](/knowledge-base/persistent-storage) Health Checks [#health-checks] By default, all containers are checked for liveness. Traefik Proxy won't work if the container has health check defined, but it is `unhealthy`. If you do not know how to set up health checks, turn it off. Rollbacks [#rollbacks] You can rollback to a previous version of your resource. At the moment, only local images are supported, so you can only rollback to a locally available docker image. Resource Limits [#resource-limits] By default, the container won't have any resource limits. You can set the limits here. For more details, read the [Docker documentation](https://docs.docker.com/reference/compose-file/services). Deployment Types [#deployment-types] There are several types of application deployments available. * Public Git Repository * Private Git Repository ([GitHub App](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps)) * Private Git Repository ([Deploy Key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys)) * Based on a Dockerfile * Based on a Docker Compose * Based on a Docker Image Build Packs [#build-packs] Build packs help transform your source code into Docker images. Coolify supports several build pack options to match different deployment needs: * **[Nixpacks](/applications/build-packs/nixpacks)** - Automatic detection and building (recommended for most applications) * **[Static](/applications/build-packs/static)** - For static sites and SPAs * **[Dockerfile](/applications/build-packs/dockerfile)** - Use your own custom Dockerfile * **[Docker Compose](/applications/build-packs/docker-compose)** - For multi-service applications * **Docker Image** - Deploy pre-built images from registries For detailed guides on each build pack, see the [Build Packs section](/applications/build-packs). Coolify uses [Nixpacks](https://nixpacks.com) by default, which automatically detects your application type and builds it accordingly. For most applications, you won't need to configure anything. # Jekyll (/docs/applications/jekyll) Jekyll [#jekyll] Jekyll is a simple, blog-aware, static site generator for personal, project, or organization sites. Deploy with Nixpacks [#deploy-with-nixpacks] Nixpacks needs a few prerequisites in your source code to deploy your Jekyll application. More info [here](https://nixpacks.com/docs/providers/ruby). Deploy with Dockerfile [#deploy-with-dockerfile] If you want simplicity, you can use a Dockerfile to deploy your Jekyll application. Prerequisites [#prerequisites] 1. Set `Ports Exposes` field to `80`. 2. Create a `Dockerfile` in the root of your project with the following content: ```dockerfile FROM ruby:3.1.1 AS builder RUN apt-get update -qq && apt-get install -y build-essential nodejs WORKDIR /srv/jekyll COPY Gemfile Gemfile.lock ./ RUN bundle install COPY . . RUN chown 1000:1000 -R /srv/jekyll RUN bundle exec jekyll build -d /srv/jekyll/_site FROM nginx:alpine COPY --from=builder /srv/jekyll/_site /usr/share/nginx/html EXPOSE 80 CMD ["nginx", "-g", "daemon off;"] ``` 3. Make sure you have a `Gemfile` and `Gemfile.lock` in the root of your project. 4. Set the buildpack to `Dockerfile`. # Laravel (/docs/applications/laravel) Laravel [#laravel] Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Example repository [here](https://github.com/coollabsio/coolify-examples/tree/main/laravel). Deploy with Nixpacks [#deploy-with-nixpacks] Requirements [#requirements] * Set `Build Pack` to `nixpacks` * Set the required [environment variables](#environment-variables) * Add `nixpacks.toml` with the following [configuration](#all-in-one-container) * Set `Ports Exposes` to `80` Environment Variables [#environment-variables] If your application needs a database or Redis, you can simply create them beforehand in the Coolify dashboard. You will receive the connection strings which you can use in your application and set them as environment variables: ```bash DB_CONNECTION=mysql DB_HOST= DB_PORT=3306 DB_DATABASE=laravel DB_USERNAME=root DB_PASSWORD= REDIS_HOST= REDIS_PASSWORD=null REDIS_PORT=6379 ``` All-in-one container [#all-in-one-container] If you would like to start queue worker, scheduler, etc within one container (recommended), then you can place a `nixpacks.toml` inside your repository with the following value. ```toml [phases.setup] nixPkgs = ["...", "python311Packages.supervisor"] [phases.build] cmds = [ "mkdir -p /etc/supervisor/conf.d/", "cp /assets/worker-*.conf /etc/supervisor/conf.d/", "cp /assets/supervisord.conf /etc/supervisord.conf", "chmod +x /assets/start.sh", "..." ] [start] cmd = '/assets/start.sh' [staticAssets] "start.sh" = ''' #!/bin/bash # Ensure storage and bootstrap cache are writable by www-data chown -R www-data:www-data /app/storage /app/bootstrap/cache chmod -R 775 /app/storage /app/bootstrap/cache # Transform the nginx configuration node /assets/scripts/prestart.mjs /assets/nginx.template.conf /etc/nginx.conf # Start supervisor supervisord -c /etc/supervisord.conf -n ''' "supervisord.conf" = ''' [unix_http_server] file=/assets/supervisor.sock [supervisord] logfile=/var/log/supervisord.log logfile_maxbytes=50MB logfile_backups=10 loglevel=info pidfile=/assets/supervisord.pid nodaemon=false silent=false minfds=1024 minprocs=200 [rpcinterface:supervisor] supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface [supervisorctl] serverurl=unix:///assets/supervisor.sock [include] files = /etc/supervisor/conf.d/*.conf ''' "worker-nginx.conf" = ''' [program:worker-nginx] process_name=%(program_name)s_%(process_num)02d command=nginx -c /etc/nginx.conf autostart=true autorestart=true stdout_logfile=/var/log/worker-nginx.log stderr_logfile=/var/log/worker-nginx.log ''' "worker-phpfpm.conf" = ''' [program:worker-phpfpm] process_name=%(program_name)s_%(process_num)02d command=php-fpm -y /assets/php-fpm.conf -F autostart=true autorestart=true stdout_logfile=/var/log/worker-phpfpm.log stderr_logfile=/var/log/worker-phpfpm.log ''' "worker-laravel.conf" = ''' [program:worker-laravel] process_name=%(program_name)s_%(process_num)02d command=bash -c 'exec php /app/artisan queue:work --sleep=3 --tries=3 --max-time=3600' user=www-data autostart=true autorestart=true stopasgroup=true killasgroup=true numprocs=12 # To reduce memory/CPU usage, change to 2. startsecs=0 stopwaitsecs=3600 stdout_logfile=/var/log/worker-laravel.log stderr_logfile=/var/log/worker-laravel.log ''' "php-fpm.conf" = ''' [www] listen = 127.0.0.1:9000 user = www-data group = www-data listen.owner = www-data listen.group = www-data pm = dynamic pm.max_children = 50 pm.min_spare_servers = 4 pm.max_spare_servers = 32 pm.start_servers = 18 clear_env = no php_admin_value[post_max_size] = 35M php_admin_value[upload_max_filesize] = 30M ''' "nginx.template.conf" = ''' user www-data www-data; worker_processes 5; daemon off; worker_rlimit_nofile 8192; events { worker_connections 4096; # Default: 1024 } http { include $!{nginx}/conf/mime.types; index index.html index.htm index.php; default_type application/octet-stream; log_format main '$remote_addr - $remote_user [$time_local] $status ' '"$request" $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for"'; access_log /var/log/nginx-access.log; error_log /var/log/nginx-error.log; sendfile on; tcp_nopush on; server_names_hash_bucket_size 128; # this seems to be required for some vhosts server { listen ${PORT}; listen [::]:${PORT}; server_name localhost; $if(NIXPACKS_PHP_ROOT_DIR) ( root ${NIXPACKS_PHP_ROOT_DIR}; ) else ( root /app; ) add_header X-Content-Type-Options "nosniff"; client_max_body_size 35M; index index.php; charset utf-8; $if(NIXPACKS_PHP_FALLBACK_PATH) ( location / { try_files $uri $uri/ ${NIXPACKS_PHP_FALLBACK_PATH}?$query_string; } ) else ( location / { try_files $uri $uri/ /index.php?$query_string; } ) location = /favicon.ico { access_log off; log_not_found off; } location = /robots.txt { access_log off; log_not_found off; } $if(IS_LARAVEL) ( error_page 404 /index.php; ) else () location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; include $!{nginx}/conf/fastcgi_params; include $!{nginx}/conf/fastcgi.conf; } location ~ /\.(?!well-known).* { deny all; } } } ''' ``` With Inertia.js [#with-inertiajs] When using Laravel with [Inertia.js](https://inertiajs.com/), you may need to specify some additional configuration in your `nixpacks.toml` file. Increasing the NGINX buffer size for Inertia requests [#increasing-the-nginx-buffer-size-for-inertia-requests] Because of a [known issue](https://github.com/inertiajs/inertia-laravel/issues/529) with Inertia.js and default NGINX configuration, you may need to increase the buffer size for NGINX to handle Inertia requests. ```sh # ... http { # ... server { # ... location ~ \.php$ { fastcgi_buffer_size 8k; # [!code ++][!code focus] fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; include $!{nginx}/conf/fastcgi_params; include $!{nginx}/conf/fastcgi.conf; # ... } } } ``` Inertia SSR [#inertia-ssr] If you are using Inertia.js with [server-side rendering](https://inertiajs.com/server-side-rendering), you should add another worker in your `nixpacks.toml` file to automatically start your SSR server. ```toml "worker-inertia-ssr.conf" = ''' [program:inertia-ssr] process_name=%(program_name)s_%(process_num)02d command=bash -c 'exec php /app/artisan inertia:start-ssr' autostart=true autorestart=true stderr_logfile=/var/log/worker-inertia-ssr.log stdout_logfile=/var/log/worker-inertia-ssr.log ''' ``` By default, Nixpacks runs the command `npm run build` to build your application during the deployment. Ensure that your `build` script in `package.json` contains the necessary build commands for server-side rendering. If you use one of the official starter kits including Inertia.js, change your scripts like this: ```yaml "scripts": { "build": "vite build", # [!code --] "build": "vite build && vite build --ssr", # [!code ++] "build:ssr": "vite build && vite build --ssr", } ``` Alternatively, if you don't want to adapt your default `build` script in `package.json`, you can add the correct build command for server-side rendering directly in your `nixpacks.toml` configuration file. ```yaml [phases.build] cmds = [ "npm run build:ssr", # [!code ++] "mkdir -p /etc/supervisor/conf.d/", "cp /assets/worker-*.conf /etc/supervisor/conf.d/", "cp /assets/supervisord.conf /etc/supervisord.conf", "chmod +x /assets/start.sh", "..." ] ``` Persistent php.ini customizations [#persistent-phpini-customizations] If you want to customize settings from your php.ini file, you can easily do so by using the `php_admin_value` directive and appending them to your `php-fpm.conf` file like this: ```toml "php-fpm.conf" = ''' [www] listen = 127.0.0.1:9000 user = www-data group = www-data listen.owner = www-data listen.group = www-data pm = dynamic pm.max_children = 50 pm.min_spare_servers = 4 pm.max_spare_servers = 32 pm.start_servers = 18 clear_env = no php_admin_value[memory_limit] = 512M php_admin_value[max_execution_time] = 60 php_admin_value[max_input_time] = 60 php_admin_value[post_max_size] = 256M ''' ``` Deploy with Dockerfile and Nginx Unit [#deploy-with-dockerfile-and-nginx-unit] Prerequisites [#prerequisites] 1. Create a new resource from a private or public repository. 2. Set the `Ports Exposes` field to `8000`, for example. 3. Set default environment variables using `Developer view` in `Environment Variables`: ```bash APP_DEBUG=false APP_ENV=staging APP_KEY= #YourAppKey APP_MAINTENANCE_DRIVER=file APP_NAME=Laravel CACHE_STORE=file DB_CONNECTION= #YourDbConnection DB_DATABASE= #YourDb DB_HOST= #YourDbHost DB_PASSWORD= #YourDbPassword DB_PORT= #YourDbPort DB_USERNAME= #YourDbUsername FILESYSTEM_DISK=public MAIL_MAILER=log SESSION_DRIVER=file ``` 4. Create a `Dockerfile` in the root of your project with the following content: ```dockerfile FROM unit:1.34.1-php8.3 RUN apt update && apt install -y \ curl unzip git libicu-dev libzip-dev libpng-dev libjpeg-dev libfreetype6-dev libssl-dev \ && docker-php-ext-configure gd --with-freetype --with-jpeg \ && docker-php-ext-install -j$(nproc) pcntl opcache pdo pdo_mysql intl zip gd exif ftp bcmath \ && pecl install redis \ && docker-php-ext-enable redis RUN echo "opcache.enable=1" > /usr/local/etc/php/conf.d/custom.ini \ && echo "opcache.jit=tracing" >> /usr/local/etc/php/conf.d/custom.ini \ && echo "opcache.jit_buffer_size=256M" >> /usr/local/etc/php/conf.d/custom.ini \ && echo "memory_limit=512M" > /usr/local/etc/php/conf.d/custom.ini \ && echo "upload_max_filesize=64M" >> /usr/local/etc/php/conf.d/custom.ini \ && echo "post_max_size=64M" >> /usr/local/etc/php/conf.d/custom.ini COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer WORKDIR /var/www/html RUN mkdir -p /var/www/html/storage /var/www/html/bootstrap/cache RUN chown -R unit:unit /var/www/html/storage bootstrap/cache && chmod -R 775 /var/www/html/storage COPY . . RUN chown -R unit:unit storage bootstrap/cache && chmod -R 775 storage bootstrap/cache RUN composer install --prefer-dist --optimize-autoloader --no-interaction COPY unit.json /docker-entrypoint.d/unit.json EXPOSE 8000 CMD ["unitd", "--no-daemon"] ``` 3. Create a `unit.json` file (lowercase) at the root of your project with the following content. ```json { "listeners": { "*:8000": { "pass": "routes", "forwarded": { "protocol": "X-Forwarded-Proto", "source": [""] } } }, "routes": [ { "match": { "uri": "!/index.php" }, "action": { "share": "/var/www/html/public$uri", "fallback": { "pass": "applications/laravel" } } } ], "applications": { "laravel": { "type": "php", "root": "/var/www/html/public/", "script": "index.php" } } } ``` When using docker-compose for deployment, then there might be an issue with `Mixed content error` when some of the assets are requested via `http://` instead of `https://`. To avoid that, find your load balancer/proxy subnet or IP address and add it to the unit.config to explicitly tell unit to forward the correct headers to Laravel. Laravel also has to be configured trust proxies. More on that [here](https://laravel.com/docs/12.x/requests#configuring-trusted-proxies). ```json "listeners": { "*:8000": { "pass": "routes", "forwarded": { "protocol": "X-Forwarded-Proto", "source": [""] } } }, ``` 4. Set Post-deployment to: ```bash php artisan optimize:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear && php artisan optimize ``` # NextJS (/docs/applications/nextjs) NextJS [#nextjs] NextJS is a React framework that enables functionality such as server-side rendering and generating static websites. [Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/nextjs) Deploy with Nixpacks [#deploy-with-nixpacks] Server build (NodeJS) [#server-build-nodejs] * Set `Build Pack` to `nixpacks`. Static build (SPA) [#static-build-spa] * Set `Build Pack` to `nixpacks`. * Enable `Is it a static site?`. * Set `Output Directory` to `out`. Deploy with Dockerfile [#deploy-with-dockerfile] If you are having problems with Nixpacks or want more control over the building stage, you can use a Dockerfile to deploy your NextJS application. Prerequisites [#prerequisites] 1. Set `Ports Exposes` field to `3000`. 2. Create a `Dockerfile` in the root of your project and copy the content from the official [NextJS Repository](https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile). 3. Set the Build Pack to `Dockerfile`. # Nuxt (/docs/applications/nuxt) Nuxt [#nuxt] Nuxt is an open source framework that makes web development intuitive and powerful. Create performant and production-grade full-stack web apps and websites with confidence. [Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/nuxt) Server build (Nuxt, using `nuxt build`) [#server-build-nuxt-using-nuxt-build] * Set `Build Pack` to `nixpacks`. * Set Start Command to `node .output/server/index.mjs` Alternatively, you can set the `start` script inside package.json to `node .output/server/index.mjs`. Then Nixpacks will automatically use it as the start command. Static build (Nuxt, using `nuxt generate`) [#static-build-nuxt-using-nuxt-generate] * Set `Build Pack` to `nixpacks`. * Enable `Is it a static site?`. * Set `Output Directory` to `dist`. Nitro server build (Nitro, using `nitro build`) [#nitro-server-build-nitro-using-nitro-build] * Set `Build Pack` to `nixpacks`. * Set Start Command to `node .output/server/index.mjs` Alternatively, you can set the `start` script inside package.json to `node .output/server/index.mjs`. Then Nixpacks will automatically use it as the start command. # Phoenix (/docs/applications/phoenix) Phoenix [#phoenix] Phoenix is a productive web framework that does not compromise speed and maintainability written in Elixir/Erlang. Requirements [#requirements] * Set `Build Pack` to `nixpacks` * Set `MIX_ENV` to `prod` * It should be a `Build time` environment variable * Set `SECRET_KEY_BASE` to a random string ([https://hexdocs.pm/phoenix/deployment.html#handling-of-your-application-secrets](https://hexdocs.pm/phoenix/deployment.html#handling-of-your-application-secrets)) * It should be a `Build time` environment variable * Set `DATABASE_URL` to your database connection string * It should be a `Build time` environment variable * Set `Ports Exposes` to `4000` (default) # Ruby on Rails (/docs/applications/rails) Ruby on Rails [#ruby-on-rails] Ruby on Rails is a web-application framework that includes everything needed to create database-backend web applications according to the Model-View-Controller (MVC) pattern. Requirements [#requirements] If you would like to migrate the database during the deployment with `NIXPACKS` build pack, you need to set the following `Start Command`: ```bash bundle exec rake db:migrate && bundle exec bin/rails server -b 0.0.0.0 -p ${PORT:-3000} -e $RAILS_ENV ``` # SvelteKit (/docs/applications/svelte-kit) SvelteKit [#sveltekit] Svelte Kit is a framework for building web applications of all sizes, with a beautiful development experience and flexible filesystem-based routing. Static build (`adapter-static`) [#static-build-adapter-static] You need to use `@sveltejs/adapter-static` ([docs](https://kit.svelte.dev/docs/adapter-static)) adapter to build a static site. 1. Set your site to static `on` (under `Build Pack` section). 2. Set your `Publish Directory` to `/build` Node server (`adapter-node`) [#node-server-adapter-node] You need to use `@sveltejs/adapter-node` ([docs](https://kit.svelte.dev/docs/adapter-node)) adapter to build a node server based SvelteKit app. 1. Set `Static` to `off` (under the `Build Pack` section). 2. Set your `Install Command` to `npm install`. 3. Set your `Build Command` to `npm run build`. 4. Set your `Start Command` to `node build`. 5. Click `Save`. 6. In your Environment Variables tab, check the current Node version supported by Nix. In the example screenshot below, it's `version 22`. 7. Add `engines` to your `package.json` with the Node version from your environment variables. For example ```json "engines": { "node": ">=22" } ``` 8. Git Commit 9. Click Deploy from your Coolify Dashboard 10. Add an Environment Variable ORIGIN with your app's actual domain. For example: 11. Optional, but recommended: Go to the Healthcheck tab and click `Enable Healthcheck` # Symfony (/docs/applications/symfony) Symfony [#symfony] Symfony is the leading PHP framework to create websites and web applications. Built on top of the Symfony Components. Requirements [#requirements] * Set `Build Pack` to `nixpacks` * Set `APP_ENV` * Set `APP_SECRET` * Set `NIXPACKS_PHP_FALLBACK_PATH` to `/index.php` * Set `NIXPACKS_PHP_ROOT_DIR` to `/app/public` * Set `Ports Exposes` to `80` Database migrations [#database-migrations] If you use Doctrine, you can add the following `Post-deployment script` : `php bin/console doctrine:migrations:migrate --all-or-nothing --no-interaction` Other components [#other-components] If your application needs a database or Redis, you can simply create them beforehand in the Coolify dashboard. You will receive the connection strings which you can use in your application and set them as environment variables: ```bash DATABASE_URL=postgresql://app:!ChangeMe!@127.0.0.1:5432/app?serverVersion=16&charset=utf8 REDIS_HOST= REDIS_PASSWORD=null REDIS_PORT=6379 ``` Trusted proxy [#trusted-proxy] You might need to configure the [trusted proxy](https://symfony.com/doc/current/deployment/proxies.html) : * Set the environment variable `TRUSTED_PROXIES` with the IP of your server * Add the following Symfony configuration : ```yaml # config/packages/framework.yaml framework: trusted_proxies: "%env(TRUSTED_PROXIES)%" trusted_headers: ['x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-forwarded-port', 'x-forwarded-prefix'] ``` Persistent php.ini customizations [#persistent-phpini-customizations] If you want to customize settings from your php.ini file, you can easily do so by using the `php_admin_value` directive and appending them to your `php-fpm.conf` file like this: ```toml "php-fpm.conf" = ''' [www] listen = 127.0.0.1:9000 user = www-data group = www-data listen.owner = www-data listen.group = www-data pm = dynamic pm.max_children = 50 pm.min_spare_servers = 4 pm.max_spare_servers = 32 pm.start_servers = 18 clear_env = no php_admin_value[memory_limit] = 512M php_admin_value[max_execution_time] = 60 php_admin_value[max_input_time] = 60 php_admin_value[post_max_size] = 256M ''' ``` # Vite (/docs/applications/vite) Vite [#vite] Vite is a build tool that aims to provide a faster and leaner development experience for modern web projects. [Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/vite) Vanilla TypeScript build (Static) [#vanilla-typescript-build-static] * Set `Build Pack` to `nixpacks`. * Enable `Is it a static site?`. * Set `Publish Directory` to `dist`. Vanilla JavaScript build (Static) [#vanilla-javascript-build-static] * Set `Build Pack` to `nixpacks`. * Enable `Is it a static site?`. * Set `Publish Directory` to `dist`. # Vue (/docs/applications/vuejs) Vue [#vue] Vue.js is an approachable, performant and versatile framework for building web user interfaces. [Example repository.](https://github.com/coollabsio/coolify-examples/tree/main/vue) Server build (NodeJS|Express) [#server-build-nodejsexpress] * Set `Build Pack` to `nixpacks`. * Set 'Start Command' to `node server.js`. Static build (SPA) [#static-build-spa] * Set `Build Pack` to `nixpacks`. * Enable `Is it a static site?`. * Set `Output Directory` to `dist`. Static build with Router (SPA) [#static-build-with-router-spa] * Set `Build Pack` to `nixpacks`. * Enable `Is it a static site?`. * Set `Output Directory` to `dist`. # Backups (/docs/databases/backups) Backups [#backups] Scheduled database backups could be configured for PostgreSQL and for Coolify itself. This schedules are based on cron expressions, so you can configure them to run as often as you want. You can also use simple cron expressions like: ```js const VALID_CRON_STRINGS = [ 'every_minute' => '* * * * *', 'hourly' => '0 * * * *', 'daily' => '0 0 * * *', 'weekly' => '0 0 * * 0', 'monthly' => '0 0 1 * *', 'yearly' => '0 0 1 1 *', ]; ``` PostgreSQL [#postgresql] Coolify creates a full backup of your PostgreSQL databases. You can specify which database to backup, with a comma separated list. Coolify's own database is also backed up using this method. Backup command [#backup-command] ```bash pg_dump --format=custom --no-acl --no-owner --username ``` Restore command [#restore-command] The backup has custom format, so you can restore it using the following command (or with any equivalent tool): ```bash pg_restore --verbose --clean -h localhost -U postgres -d postgres pg-dump-postgres-1697207547.dmp ``` MySQL [#mysql] ```bash mysqldump -u root -p ``` MariaDB [#mariadb] ```bash mariadb-dump -u root -p ``` MongoDB [#mongodb] ```bash mongodump --authenticationDatabase=admin --uri= --gzip --archive= ``` Or if you exclude some collections: ```bash mongodump --authenticationDatabase=admin --uri= --gzip --archive= --excludeCollection= --excludeCollection= ``` S3 Backups [#s3-backups] You can also define your own [S3 compatible](/knowledge-base/s3/introduction) storage to store your backups. # ClickHouse (/docs/databases/clickhouse) Clickhouse [#clickhouse] What is ClickHouse [#what-is-clickhouse] ClickHouse is an open-source column-oriented database management system designed for online analytical processing (OLAP). It's known for its exceptional query performance on large datasets, making it ideal for real-time analytics and data warehousing applications. ClickHouse uses a column-oriented storage format and employs various optimizations like vectorized query execution to achieve high performance. It supports SQL with extensions and can handle both batch and stream data ingestion, making it versatile for various analytical workloads. To connect [#to-connect] Map the port `8123:8123` for the HTTP interface. In DBeaver, connect to `http://__ip_address__:8123` and use the `default` username plus the password in the UI. If you also want the native TCP protocol (used by [clickhouse-client](https://clickhouse.com/docs/interfaces/cli) CLI), publish `9000:9000` as well. Backup and Restore Guide [#backup-and-restore-guide] Currently, Coolify does not support modifying ClickHouse configurations, which means certain native backup options (e.g., backing up to a local Disk or using `ALTER TABLE ... FREEZE PARTITION ...`) are not possible. Instead, the recommended approach is to use S3 for backups. How to Backup ClickHouse [#how-to-backup-clickhouse] To backup a table or an entire database, use the following SQL command: * **Backup a Table:** ```sql BACKUP TABLE TO S3('/', '', '') ``` * **Backup a Database:** Replace `TABLE` with `DATABASE` to backup the whole database: ```sql BACKUP DATABASE TO S3('/', '', '') ``` How to Restore ClickHouse [#how-to-restore-clickhouse] To restore a table or database from an S3 backup, use the corresponding RESTORE command: * **Restore a Table:** ```sql RESTORE TABLE FROM S3('/', '', '') ``` * **Restore a Database:** Replace `TABLE` with `DATABASE` to restore the whole database: ```sql RESTORE DATABASE FROM S3('/', '', '') ``` What Doesn't Work [#what-doesnt-work] * **Disk Backups:** ```sql BACKUP TABLE test.table TO Disk('backups', '1.zip') ``` Does not work due to Coolify not allowing modifications to ClickHouse configurations. * **Native Partition Freezes:** ```sql ALTER TABLE ... FREEZE PARTITION ... ``` May not work because of limitations in the Docker/Coolify file structure. * **clickhouse-backup Tool:** External tools like [clickhouse-backup](https://github.com/Altinity/clickhouse-backup?utm_source=coolify.io) might not function properly within the Docker/Coolify setup due to similar configuration restrictions. Performance Notes [#performance-notes] A community member shared that backing up a 145GB database took around 12 minutes, while restoring it took roughly 17 minutes. Links [#links] * [The official website](https://clickhouse.com/?utm_source=coolify.io) * [GitHub](https://github.com/ClickHouse/ClickHouse?utm_source=coolify.io) # DragonFly (/docs/databases/dragonfly) DragonFly [#dragonfly] What is DragonFly [#what-is-dragonfly] DragonFly is a modern in-memory datastore, designed as a Redis alternative with better scalability and resource efficiency. It offers a Redis-compatible API while providing improved performance on multi-core systems. DragonFly is built to handle high-throughput scenarios and large datasets more efficiently than traditional in-memory datastores. With its multi-threaded architecture and advanced data structures, DragonFly aims to provide enhanced scalability and performance for applications that require Redis-like functionality on modern hardware. Data Persistence [#data-persistence] By default, Dragonfly DB does not save data to disk. To enable persistence, set up snapshots manually. For example, configure the service with: ```yaml services: dragonfly: command: 'dragonfly --requirepass XXXXXXXX --dir /data --dbfilename dragonfly-snapshot-{timestamp} --snapshot_cron "*/5 * * * *"' ``` You can also trigger manual saves using the SDK's `SAVE` command. Links [#links] * [The official website](https://dragonflydb.io/?utm_source=coolify.io) * [GitHub](https://github.com/dragonflydb/dragonfly?utm_source=coolify.io) # Introduction (/docs/databases) Databases you can host with Coolify [#databases-you-can-host-with-coolify] Coolify supports a variety of databases to suit different application needs. Even if you don't see your favorite database here, you can still host it with Coolify, using Docker. Coolify offers one-click setup for the following databases: * [PostgreSQL](/databases/postgresql) * [Redis](/databases/redis) * [DragonFly](/databases/dragonfly) * [KeyDB](/databases/keydb) * [Clickhouse](/databases/clickhouse) * [MongoDB](/databases/mongodb) * [MySQL](/databases/mysql) * [MariaDB](/databases/mariadb) Each database has its own strengths and use cases. Click on a database to learn more about it. Deploy a database [#deploy-a-database] When selecting a New Resource, you can select a database from the list. You can configure a database with a simple click. Coolify supports the following databases: * PostgreSQL * MySQL * MariaDB * MongoDB * Redis * DragonFly * KeyDB * Clickhouse Ports Mapping vs Public Port [#ports-mapping-vs-public-port] Ports Mapping [#ports-mapping] Ports mapping is using the Docker [port mapping](https:/.docker.com/network/#published-ports) feature. It is used to map the container port to the host port. For example, if you set the port mapping to `8080:80`, the container port `80` will be mapped to the host port `8080`. Public Port [#public-port] Public port is used to expose the container port to the internet, by starting an Nginx TCP proxy. Which one should I use? [#which-one-should-i-use] * Port mappings makes the connection/port permanent (you need to restart your database to change it). * The public port makes the connection/port dynamic (you can change it without restarting the database, Coolify will restart the Nginx TCP proxy for you). Proxy Timeout [#proxy-timeout] When using a public port, Coolify starts an Nginx TCP proxy to expose your database. By default, the proxy timeout is set to **3600 seconds** (1 hour). You can configure this in the database settings under **Proxy Timeout (seconds)**. This controls how long idle connections are kept open before Nginx closes them. * The minimum value is **1 second**. * Set a higher value if you have long-running queries or connections that stay idle for extended periods. Access database during builds [#access-database-during-builds] If you are using `Nixpacks` build pack, you have two ways to access your database during builds: 1. Database & your application are `in the same network`: You can reach it using the `internal URL` provided by Coolify. 2. Database & your application `are not in the same network`: You need to set your database to be `Accessible over the internet` and use the `public URL` provided by Coolify. # KeyDB (/docs/databases/keydb) KeyDB [#keydb] What is KeyDB [#what-is-keydb] KeyDB is a high-performance fork of Redis, focusing on multithreading, memory efficiency, and high availability. It maintains API compatibility with Redis while offering improved performance, especially on multi-core systems. KeyDB introduces features like active replication, FLASH storage support, and subkey expires to enhance the capabilities of the traditional Redis model. Designed to be a drop-in replacement for Redis, KeyDB aims to provide better resource utilization and scalability for applications requiring high-throughput in-memory data storage and processing. Links [#links] * [The official website](https://keydb.dev/) * [GitHub](https://github.com/EQ-Alpha/KeyDB) # MariaDB (/docs/databases/mariadb) MariaDB [#mariadb] What is MariaDB [#what-is-mariadb] MariaDB is an open-source fork of MySQL, designed to remain free and open-source. It aims to be a drop-in replacement for MySQL with enhanced features and performance. MariaDB maintains high compatibility with MySQL while offering additional storage engines, performance improvements, and features. Started by core members of MySQL, MariaDB provides a robust and scalable database solution suitable for a wide range of applications. Links [#links] * [The official website](https://mariadb.org/) * [GitHub](https://github.com/MariaDB/server) # MongoDB (/docs/databases/mongodb) MongoDB [#mongodb] What is MongoDB [#what-is-mongodb] MongoDB is a popular, open-source document-oriented NoSQL database designed for scalability and flexibility. It stores data in flexible, JSON-like documents, meaning fields can vary from document to document and data structure can be changed over time. MongoDB is known for its horizontal scalability, powerful query language, and ability to handle large volumes of unstructured or semi-structured data. It's widely used in modern web applications, content management systems, and other scenarios where flexible data models and scalability are crucial. Links [#links] * [The official website](https://www.mongodb.com/) * [GitHub](https://github.com/mongodb/mongo) # MySQL (/docs/databases/mysql) MySQL [#mysql] What is MySQL [#what-is-mysql] MySQL is a widely-used, open-source relational database management system (RDBMS) known for its reliability, ease of use, and performance. It's an essential component of the popular LAMP (Linux, Apache, MySQL, PHP/Python/Perl) stack used for web development. MySQL provides a robust, ACID-compliant database solution suitable for a wide range of applications, from small websites to large-scale enterprise systems. It offers features like replication, partitioning, and full-text indexing, making it versatile for various use cases. Links [#links] * [The official website](https://www.mysql.com/) * [GitHub](https://github.com/mysql/mysql-server) # PostgreSQL (/docs/databases/postgresql) PostgreSQL [#postgresql] What is PostgreSQL [#what-is-postgresql] PostgreSQL is an advanced, open-source object-relational database system known for its reliability, feature robustness, and performance. It has more than 30 years of development and is widely used in the industry. PostgreSQL, often simply "Postgres", uses and extends the SQL language combined with many features that safely store and scale the most complicated data workloads. Links [#links] * [The official website](https://www.postgresql.org/) * [GitHub](https://github.com/postgres/postgres) Import Backups [#import-backups] Coolify can import a database dump into a running PostgreSQL instance using the **Import Backups** section of the Configuration for the instance. The database dump can either be a file uploaded to the server, or dragged and dropped into the Configuration screen directly. The import command can be customized, but by default it expects a database dump created using the `pg_dump` command with the `-Fc` flag passed in (custom format). For example, the following command connects to a PostgreSQL database running in a local Docker container named `pg-db` as the database user `postgres` and writes a dump of the `postgres` database to the file `example-database.sql.gz`: ```bash docker exec pg-db pg_dump -U postgres -d postgres -Fc >example-database.sql.gz ``` Note on upgrading PostgreSQL [#note-on-upgrading-postgresql] The **custom** dump format is sensitive to version differences between the dump and restore commands. Use the plain (default) or **tar** dump formats to migrate from an older version of PostgreSQL to a newer version. When using plain format dumps, use `psql` as the custom import command instead of `pg_restore`. See the PostgreSQL documentation for `pg_dump` and `pg_restore` for more information. # Redis (/docs/databases/redis) Redis [#redis] What is Redis [#what-is-redis] Redis is an in-memory data store used by millions of developers as a cache, vector database, document database, streaming engine, and message broker. Redis has built-in replication and different levels of on-disk persistence. It supports complex data types (for example, strings, hashes, lists, sets, sorted sets, and JSON), with atomic operations defined on those data types. Links [#links] * [The official website](https://redis.io/) * [GitHub](https://github.com/redis/redis) # Database SSL (/docs/databases/ssl) Database SSL `^v4.0.0-beta.399` [#database-ssl--v400-beta399] Database SSL in Coolify encrypts the communication between your applications and databases, ensuring that data remains secure. With automatic certificate binding and generation, this feature simplifies secure setup. It was first introduced in Coolify version **v4.0.0-beta.399**. Introduction [#introduction] Database SSL adds an extra layer of security by encrypting data exchanged with your database. This guide covers: * Enabling SSL mode for your database connections. * Selecting the appropriate SSL mode based on your security needs. * Managing the CA certificate that verifies database connections. 1\. How to Enable Database SSL [#1-how-to-enable-database-ssl] To secure your database connection with SSL: 1. **Access Database Settings**\ In your Coolify dashboard, access the general settings of the database you want to secure. 2. **Enable SSL Mode**\ Check the **Enable SSL** option to activate SSL for the database connection. 3. **Select the SSL Mode**\ Choose the SSL mode from the dropdown menu. For example, select **verify-full** for maximum security. To make use of SSL after enabling it, you need to use the new connection URL for your app, which includes the SSL configuration. If you are not using the new URL, the database connection will not use SSL (in most cases). Coolify automatically binds the generated certificates and keys to the required locations, so manual changes are only needed if you wish to use custom certificates. 2\. SSL Modes Explained [#2-ssl-modes-explained] Coolify supports several SSL modes, each providing a different level of security: PostgreSQL [#postgresql] * **allow (insecure)**\ This mode permits both encrypted and unencrypted connections. It does not enforce SSL, so if SSL fails, the connection will fall back to an unencrypted state. This option is considered insecure because it allows unencrypted traffic. * **prefer (secure)**\ With this mode, Coolify will attempt to use SSL first. If an SSL connection is available, it will be used, otherwise, it will fall back to an unencrypted connection. While this option prefers encryption, it doesn’t guarantee that every connection will be secured. * **require (secure)**\ This mode mandates that the connection must be encrypted. However, it does not perform any checks on the server certificate. This means the connection is encrypted, but the identity of the server is not verified. * **verify-ca (secure)**\ This option goes a step further by encrypting the connection and verifying that the server's certificate is signed by a trusted Certificate Authority (CA). It does not check if the hostname matches the certificate. This mode offers a balance between security and ease of setup. * **verify-full (secure)**\ This is the most secure mode. It not only encrypts the connection and verifies the certificate authority but also confirms that the server’s hostname matches the certificate. This provides full assurance that you are connecting to the correct server, similar to the security level provided by Cloudflare Origin Certificate setups. Other Databases [#other-databases] * **MySQL & MongoDB:**\ Only the following modes are available: **prefer, require, verify ca, verify full**. * **MariaDB, Redis, KeyDB, DragonFly DB:**\ No SSL modes are visible in the UI. * **Clickhouse DB:**\ SSL is not supported, there is no checkbox to enable SSL nor dropdown options. Modes lower than **require** are not 100% secure as they only encrypt the connection without full verification of the server’s identity. For modes higher than **require** (i.e., **verify-ca** and **verify-full**), you must mount the Coolify CA certificate into the container that connects to the database for additional security. Note that in most cases (for example, PostgreSQL), merely enabling SSL does nothing unless you use the new connection URL that enforces SSL. However, for some databases, like the redis-based ones, enabling SSL in the UI does enforce the mode. For maximum security, **verify-full** is recommended (when available). 3\. CA SSL Certificate Management [#3-ca-ssl-certificate-management] Coolify manages the CA certificate automatically, ensuring that secure database connections are validated. In the dashboard, under **Servers > YOUR\_SERVER\_NAME > Proxy > Advanced**, you can see the following options: * **CA SSL Certificate**: Displays the current CA certificate used. * **Save Certificate**: Allows you to save a local copy of the certificate. * **Regenerate Certificate**: Lets you generate a new CA certificate if needed. Recommended Configuration [#recommended-configuration] For secure connections, mount the Coolify CA certificate into all containers that need to connect to your databases. The recommended bind mount is: ```bash /data/coolify/ssl/coolify-ca.crt:/etc/ssl/certs/coolify-ca.crt:ro ``` 4\. Using a Custom CA Certificate [#4-using-a-custom-ca-certificate] If you wish to use your own CA certificate instead of the one generated by Coolify: 1. **Prepare Your CA Certificate**\ Make sure your certificate is in PEM format. 2. **Upload Your Certificate**\ Upload your custom CA certificate in the following location: ```bash /data/coolify/ssl/coolify-ca.crt ``` 3. **Mount the Certificate**\ Make sure that the container that requires database access mounts the certificate at: ```bash /data/coolify/ssl/coolify-ca.crt:/etc/ssl/certs/coolify-ca.crt:ro ``` # Coolify Cloud (/docs/get-started/cloud)
[Coolify Cloud](https://coolify.io/pricing/) is our managed, paid service (maintained by [Andras](https://x.com/heyandras), Coolify’s Founder) that runs the Coolify on our infrastructure, so you don’t need to allocate CPU, RAM, or disk for Coolify itself. You still bring your own servers (VPS, Raspberry Pi, EC2, etc.) and connect them via SSH, then deploy apps, databases, and services exactly as you would with a self-hosted instance. Coolify Cloud uses the same open-source codebase, so there are no locked-behind-paywall features. Benefits of Coolify Cloud [#benefits-of-coolify-cloud] | Features | Explanation | | :--------------------------- | :------------------------------------------------------------------------------------------------------------------ | | **Zero Maintenance Coolify** | No need to upgrade, or monitor Coolify, our team does it for you. | | **Daily Backups** | The Coolify Cloud database is backed up every 24 hours. | | **Preconfigured Email** | Receive build, deployment, and server status notifications via email without any setup on your end. | | **Automatic Scaling** | As you connect more servers, our infrastructure scales CPU, RAM, and disk usage for Coolify. | | **Staged Updates** | New updates are first rolled out to self-hosted users. Once stability is confirmed, they’re rolled out to Cloud. | | **Founder-Tested Releases** | Andras personally tests every update before it’s deployed to the Cloud, ensuring maximum stability and reliability. | Getting Started with Coolify Cloud [#getting-started-with-coolify-cloud] 1. **Create Your Account:** * Visit the [Coolify Cloud Registration](https://app.coolify.io/register) page and sign up. 2. **Choose Your Plan:** * Base fee: **$5/month** (includes up to two connected servers). * **$3/month** per additional server. 3. **Complete Payment** * Use any major credit/debit card to finish the subscription process. 4. **Connect Your Servers** 1) **Add Private Key:** Login to your Coolify account (or create one if you’re new) and Add a new private key 2) **Add a Server:** Navigate to the **Servers** tab and add a new server by entering your Hetzner server’s IPv4 address. 3) **Validate Server:** Click **Validate Server & Install Docker Engine**. Coolify will automatically install all necessary components on your server. 4) **Check Status:** Once finished, you should see a green **Proxy Running** status indicating everything is set up. 5. **Deploy Your Applications** How Coolify Cloud Pricing works? [#how-coolify-cloud-pricing-works] We charge a base fee of **$5/month**, which covers up to **two servers**. Each additional server you connect is an **add-on of $3/month**. Charging per server allows us to scale our infrastructure responsibly, since each connected server increases resource usage (CPU, RAM, storage) on our end. If you only need one server, you still pay the $5 base fee (with capacity for a second server if you add it later). If you plan to connect more than two, simply multiply $3 by the extra servers. Why Coolify Cloud Exists [#why-coolify-cloud-exists] You might wonder why Coolify Cloud is a paid service when there are no exclusive, locked-down features. The idea came to Andras (Coolify's Founder) as a way to offer a “**paid option without paywall**” — a model where the open-source project stays completely free, but those who prefer a managed experience can contribute financially. * **Experiment Turned Success:** * Initially launched as an experiment, Coolify Cloud quickly attracted over 2,100 active users. - **Sustainable Funding:** * While the revenue from Cloud is modest, it provides a steady income stream that helps keep Coolify free and under active development for everyone. - **Community-First Approach** * By not restricting any features, we maintain transparency and trust. * Cloud subscribers simply pay for convenience and reliability, not to unlock core functionality. Frequently Asked Questions [#frequently-asked-questions] No. Coolify Cloud and self-hosted Coolify share the same feature set. Cloud’s value lies in automatic backups, email notifications, scaling, and update testing handled for you. No, Coolify Cloud only backs up the Coolify database (e.g., dashboard settings). You are responsible for backing up any databases or storage volumes on your servers. No. To transfer configurations, you'll need to back up the database from your self-hosted instance and restore it to a new Coolify instance. However, since you don’t have access to the database in Coolify Cloud, it’s not possible to migrate data or settings directly to the cloud version. Every 24 hours Yes, Coolify Cloud uses the same open-source codebase as the self-hosted version. There are no paywall features, and the Cloud service is simply a managed experience for convenience. If you cancel your subscription, you will stop being billed, and your access to Coolify Cloud will be suspended at the end of your current billing cycle. However, your servers will remain unaffected, and all of your applications will continue running as normal. Since your server will still be hosting your applications with a reverse proxy handling incoming requests, there will be no interruptions. If a payment fails or an invoice is missed, your subscription and access to Coolify Cloud will be temporarily paused until the payment is successfully processed. You will receive an email notification about the failed payment. Once the payment is made, your Coolify Cloud access will be restored, and all your settings will remain intact—there’s no data loss. Your servers will also stay up and running, and your applications will continue to function normally, as everything is still hosted on your own server with a reverse proxy. Yes, Coolify Cloud uses specific IP addresses. You can find the list of IPs [here](https://coolify.io/docs/knowledge-base/faq#coolify-cloud-public-ips). The main requirement is that Coolify Cloud needs to access your server's SSH port. Yes, when using Coolify Cloud, you must provide your own servers (e.g., VPS, Raspberry Pi, EC2, etc.). Coolify Cloud manages Coolify on our infrastructure, but we don’t provide the servers themselves. This approach allows you to choose the hardware that best fits your needs. While you bring your own servers, the subscription fee for Coolify Cloud covers the managed service aspect. This includes infrastructure management, maintenance, support, updates, and scaling, so you don’t have to worry about technical aspects like monitoring, patching, or backups for Coolify. We take care of the heavy lifting to ensure everything runs smoothly. You won’t be able to add extra servers to Coolify cloud unless your subscription is upgraded. Currently, Coolify Cloud doesn’t offer a free trial. However, the subscription is affordable—just **$5 per month** for up to two connected servers. If you want to explore all the features, you can run Coolify on a small Linux server or a VM on your PC by following the [self-hosted installation guide](https://coolify.io/docs/get-started/installation). Since both cloud and self-hosted versions use the same codebase, you’ll be able to test all the features without any limitations. The current **$5/month** subscription rate is already quite affordable, so discounts are not available at the moment. **Not really.** You're paying for the managed Coolify instance, but stopping the use of Coolify Cloud won't affect your applications. You can connect your own server, so you retain full control. Everything runs as a Docker container, and Coolify will install a reverse proxy on your server to ensure everything works smoothly without needing Coolify Cloud. In a true vendor lock-in, your apps would stop if you stop paying, but that’s not the case with Coolify Cloud. No. The Coolify Cloud dashboard is only available at [https://app.coolify.io](https://app.coolify.io). If you’d like to access the dashboard on your own domain, you’ll need to self-host Coolify. # Concepts (/docs/get-started/concepts)
Many people start their self-hosting journey after discovering Coolify. If you’re one of them, here’s a list of a few concepts that could make your experience smoother. Servers [#servers] A server is a computer designed to run applications or services, providing the necessary computing power for your projects. It can be either physical such as a machine you have at home, like a Raspberry Pi, or one rented from a hosting provider like Hetzner. Resources [#resources] In Coolify, a resource refers to an application or service you set up on your server—like a website, database, or API. Each resource comes with its own configuration, like domains, backups, health checks, and so on. Coolify offers a handy list of pre-set resources, called one-click services, that you can deploy instantly. But if you prefer, you can also deploy your own application easily. Environments [#environments] In Coolify, a environment is a tailored setup on your server that determines how your resources operate. For instance, you could have a development environment for testing and debugging your code, alongside a production environment where your finished application goes live. With Coolify, you can set up multiple environments on a single server, letting you switch between them effortlessly. Projects [#projects] A project in Coolify is a group of environments and resources you’ve deployed on your server. It serves as the highest-level structure in Coolify, organizing your deployment setup. You can manage multiple projects on the same server, each with its own unique set of environments and resources. For example, you might create one project for all your hobby-related resources and another for work-related ones. Containers [#containers] In Coolify, everything you deploy runs as a Docker container, making it easy to manage and isolate your application. You can use pre-built Docker images from public registries like Docker Hub or GitHub Container Registry to deploy without building them yourself. To deploy, you need a Docker image, either one you’ve built or one from someone else. If you’re coding your own app, Coolify can auto-build the image from a Dockerfile or Docker Compose file, though this resource-heavy process requires a capable server. Alternatively, you can build the image elsewhere, push it to a registry, and let Coolify deploy it as a container. Reverse Proxy [#reverse-proxy] A reverse proxy is a server or app that sits between your application and users, forwarding requests to the right place. Coolify includes two proxy options, Caddy and Traefik, which handle requests to your website by directing them to the container running your app. This setup lets you run multiple applications on one server without tweaking configs or ports. Plus, Coolify supports unlimited domains, so you could deploy 20 different apps, each with its own unique domain. The reverse proxy also automatically manages SSL/TLS certificates for your applications. When you enter a domain with `https://`, the proxy requests and installs certificates from [Let's Encrypt](https://letsencrypt.org?utm_source=coolify.io) automatically, with no manual configuration needed. Certificates are renewed automatically before they expire, keeping your applications secure without any intervention. Security [#security] Coolify doesn’t manage your server’s security or updates, that’s your responsibility to keep everything secure and up to date. It’s built to simplify deployment management for you. While the Coolify core team plans to introduce more security features eventually, for now, securing your server is entirely up to you. Teams [#teams] Coolify supports multiple users and teams, allowing each team to have its own projects and environments. You can assign roles like admin to users, simplifying project management and collaboration on a single server. Currently, the teams feature isn’t fully polished for production use, but the Coolify core team plans to enhance it down the line. # Contributing to Core (/docs/get-started/contribute/coolify) Contributing to Coolify [#contributing-to-coolify] > "First, thanks for considering contributing to my project. It really means a lot!" - [@andrasbacsai](https://github.com/andrasbacsai) You can ask for guidance anytime on our [Discord Community Server](https://coollabs.io/discord) in the `#contribute` channel. To understand the tech stack, please refer to the [Tech Stack](https://github.com/coollabsio/coolify/blob/main/TECH_STACK.md) document. Table of Contents [#table-of-contents] 1. [Setup Development Environment](#_1-setup-development-environment) 2. [Verify Installation](#_2-verify-installation-optional) 3. [Fork and Setup Local Repository](#_3-fork-and-setup-local-repository) 4. [Set up Environment Variables](#_4-set-up-environment-variables) 5. [Start Coolify](#_5-start-coolify) 6. [Start Development](#_6-start-development) 7. [Create a Pull Request](#_7-create-a-pull-request) 8. [Development Notes](#development-notes) 9. [Resetting Development Environment](#resetting-development-environment) 10. [Additional Contribution Guidelines](#additional-contribution-guidelines) 1\. Setup Development Environment [#1-setup-development-environment] Follow the steps below for your operating system: 1. Install `docker-ce`, Docker Desktop (or similar): * Docker CE (recommended): * Install Windows Subsystem for Linux v2 (WSL2) by following this guide: [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install?ref=coolify) * After installing WSL2, install Docker CE for your Linux distribution by following this guide: [Install Docker Engine](https://docs.docker.com/engine/install/?ref=coolify) * Make sure to choose the appropriate Linux distribution (e.g., Ubuntu) when following the Docker installation guide * Install Docker Desktop (easier): * Download and install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/?ref=coolify) * Ensure WSL2 backend is enabled in Docker Desktop settings 2. Install Spin: * Follow the instructions to install Spin on Windows from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-windows#download-and-install-spin-into-wsl2?ref=coolify) 1. Install Orbstack, Docker Desktop (or similar): * Orbstack (recommended, as it is a faster and lighter alternative to Docker Desktop): * Download and install [Orbstack](https://docs.orbstack.dev/quick-start#installation?ref=coolify) * Docker Desktop: * Download and install [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/?ref=coolify) 2. Install Spin: * Follow the instructions to install Spin on MacOS from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-macos/#download-and-install-spin?ref=coolify) 1. Install Docker Engine, Docker Desktop (or similar): * Docker Engine (recommended, as there is no VM overhead): * Follow the official [Docker Engine installation guide](https://docs.docker.com/engine/install/?ref=coolify) for your Linux distribution * Docker Desktop: * If you want a GUI, you can use [Docker Desktop for Linux](https://docs.docker.com/desktop/install/linux-install/?ref=coolify) 2. Install Spin: * Follow the instructions to install Spin on Linux from the [Spin documentation](https://serversideup.net/open-source/spin/docs/installation/install-linux#configure-docker-permissions?ref=coolify) 2\. Verify Installation (Optional) [#2-verify-installation-optional] After installing Docker (or Orbstack) and Spin, verify the installation: 1. Open a terminal or command prompt 2. Run the following commands: ```bash docker --version spin --version ``` You should see version information for both Docker and Spin. 3\. Fork and Setup Local Repository [#3-fork-and-setup-local-repository] 1. Fork the [Coolify](https://github.com/coollabsio/coolify) repository to your GitHub account. 2. Install a code editor on your machine (choose one): | Editor | Platform | Download Link | | ------------------------------------- | ------------------- | -------------------------------------------------------------- | | Visual Studio Code (recommended free) | Windows/macOS/Linux | [Download](https://code.visualstudio.com/download?ref=coolify) | | Cursor (recommended but paid) | Windows/macOS/Linux | [Download](https://www.cursor.com/?ref=coolify) | | Zed (very fast) | Windows/macOS/Linux | [Download](https://zed.dev/download?ref=coolify) | 3. Clone the Coolify Repository from your fork to your local machine * Use `git clone` in the command line, or * Use GitHub Desktop (recommended): * Download and install from [https://desktop.github.com/](https://desktop.github.com/?ref=coolify) * Open GitHub Desktop and login with your GitHub account * Click on `File` -> `Clone Repository` select `github.com` as the repository location, then select your forked Coolify repository, choose the local path and then click `Clone` 4. Open the cloned Coolify Repository in your chosen code editor. 4\. Set up Environment Variables [#4-set-up-environment-variables] 1. In the Code Editor, locate the `.env.development.example` file in the root directory of your local Coolify repository. 2. Duplicate the `.env.development.example` file and rename the copy to `.env`. 3. Open the new `.env` file and review its contents. Adjust any environment variables as needed for your development setup. 4. If you encounter errors during database migrations, update the database connection settings in your `.env` file. Use the IP address or hostname of your PostgreSQL database container. You can find this information by running `docker ps` after executing `spin up`. 5. Save the changes to your `.env` file. 5\. Start Coolify [#5-start-coolify] 1. Open a terminal in the local Coolify directory. 2. Run the following command in the terminal (leave that terminal open): ```bash spin up ``` You may see some errors, but don't worry this is expected. 3. If you encounter permission errors, especially on macOS, use: ```bash sudo spin up ``` If you change environment variables afterwards or anything seems broken, press Ctrl + C to stop the process and run `spin up` again. 6\. Start Development [#6-start-development] 1. Access your Coolify instance: * URL: `http://localhost:8000` * Login: `test@example.com` * Password: `password` 2. Additional development tools: | Tool | URL | Note | | --------------------------- | --------------------------------- | ------------------------------------------- | | Laravel Horizon (scheduler) | `http://localhost:8000/horizon` | Only accessible when logged in as root user | | Mailpit (email catcher) | `http://localhost:8025` | | | Telescope (debugging tool) | `http://localhost:8000/telescope` | Disabled by default | To enable Telescope, add the following to your `.env` file: ```yaml TELESCOPE_ENABLED=true ``` 7\. Create a Pull Request [#7-create-a-pull-request] 1. After making changes or adding a new service: * Commit your changes to your forked repository. * Push the changes to your GitHub account. 2. Creating the Pull Request (PR): * Navigate to the main Coolify repository on GitHub. * Click the "Pull requests" tab. * Click the green "New pull request" button. * Choose your fork and branch as the compare branch. * Click "Create pull request". 3. Filling out the PR details: * Give your PR a descriptive title. * Use the Pull Request Template provided and fill in the details. Always set the base branch for your PR to the `next` branch of the Coolify repository, not the `v4.x` branch. 4. Submit your PR: * Review your changes one last time. * Click "Create pull request" to submit. Make sure your PR is out of draft mode as soon as it's ready for review. PRs that are in draft mode for a long time may be closed by maintainers. After submission, maintainers will review your PR and may request changes or provide feedback. Development Notes [#development-notes] When working on Coolify, keep the following in mind: 1. **Database Migrations**: After switching branches or making changes to the database structure, always run migrations: ```bash docker exec -it coolify php artisan migrate ``` 2. **Resetting Development Setup**: To reset your development setup to a clean database with default values: ```bash docker exec -it coolify php artisan migrate:fresh --seed ``` 3. **Troubleshooting**: If you encounter unexpected behavior, ensure your database is up-to-date with the latest migrations and if possible reset the development setup to eliminate any environment-specific issues. Forgetting to migrate the database can cause problems, so make it a habit to run migrations after pulling changes or switching branches. Resetting Development Environment [#resetting-development-environment] If you encounter issues or break your database or something else, follow these steps to start from a clean slate (works since `v4.0.0-beta.342`): 1. Stop all running containers `ctrl + c`. 2. Remove all Coolify containers: ```bash docker rm coolify coolify-db coolify-redis coolify-realtime coolify-testing-host coolify-minio coolify-vite-1 coolify-mail ``` 3. Remove Coolify volumes (it is possible that the volumes have no `coolify` prefix on your machine, in that case remove the prefix from the command): ```bash docker volume rm coolify_dev_backups_data coolify_dev_postgres_data coolify_dev_redis_data coolify_dev_coolify_data coolify_dev_minio_data ``` 4. Remove unused images: ```bash docker image prune -a ``` 5. Start Coolify again: ```bash spin up ``` 6. Run database migrations and seeders: ```bash docker exec -it coolify php artisan migrate:fresh --seed ``` After completing these steps, you'll have a fresh development setup. Always run database migrations and seeders after switching branches or pulling updates to ensure your local database structure matches the current codebase and includes necessary seed data. Additional Contribution Guidelines [#additional-contribution-guidelines] Contributing a New Service [#contributing-a-new-service] To add a new service to Coolify, please refer to our documentation: [Adding a New Service](/get-started/contribute/service) Contributing to Documentation [#contributing-to-documentation] To contribute to the Coolify documentation, please refer to this guide: [Contributing to the Coolify Documentation](/get-started/contribute/documentation) # Contributing to Documentation (/docs/get-started/contribute/documentation) Coolify Docs Contribution Guide [#coolify-docs-contribution-guide] This guide outlines the process for contributing updates and fixes to our docs. Please follow the steps below to ensure a smooth and efficient workflow. 1\. Repository Workflow [#1-repository-workflow] * **Release Process:**\ We follow a weekly production release cycle. The **main** branch represents production, while the **next** branch is used as our development branch. * **Branching Guidelines:** * **Do not create pull requests (PRs) to the main branch.** * All contributions should be made to the **next** branch. * **Clone the repository from the next branch** to your GitHub account, then start working on your changes. 2\. Getting Started [#2-getting-started] Step 1: Fork and Clone the Repository [#step-1-fork-and-clone-the-repository] * First fork the docs repository to your github account, then clone your fork to your local system using: ```bash git clone https://github.com/your-username/your-repo-name.git ``` * Navigate to the cloned repository: ```bash cd your-repo-name ``` Step 2: Install Dependencies and Run the Dev Server [#step-2-install-dependencies-and-run-the-dev-server] We use [bun](https://bun.sh/) as our preferred package manager for local development. If you choose to use a different package manager, please **do not include its configuration files** in your commit. To set up your environment, run: ```bash bun install && bun run dev ``` The development server will start on `localhost` at port `5173`. You can view the documentation by navigating to: ```bash http://localhost:5173/docs/ ``` 3\. Image Guidelines [#3-image-guidelines] * **Format:**\ All images used in the documentation must be in `.webp` format. * **Location:**\ Place all image files in the `/docs/public` directory. * **Usage:**\ Use the Zoomable image component on the docs to attach your images ```text ``` 4\. Writing and Structuring Content [#4-writing-and-structuring-content] Best Practices for Documentation: [#best-practices-for-documentation] * **Clear and Simple Language:**\ Use plain and easily understandable English. Remember that not all readers are native English speakers. * **Beginner-Friendly Guides:**\ Break down instructions into small, easy-to-follow steps. Include screenshots wherever possible to help visualize the process, especially for users new to self-hosting or Coolify. * **Content Organization:**\ Structure your content with clear headings, bullet points, and numbered steps where applicable. This makes it easier for readers to follow along. 5\. Submitting Your Contribution [#5-submitting-your-contribution] 1. **Commit your changes to your repository** 2. **Create a Pull Request:** * Open a pull request (PR) to merge your changes into the **next** branch on the docs repository. * Provide a detailed description of your updates to help maintainers review your contribution effectively. 6\. Questions and Support [#6-questions-and-support] If you have any questions or run into issues while contributing: * **Create an Issue:** Open an issue on the repository detailing your issue. * **Discord:** Reach out to us on contribute channel on the [Coolify Discord community](https://coolify.io/discord). 7\. Important Notes [#7-important-notes] * **Documentation Updates:**\ The current docs are bit outdated and missing some information. The docs maintainers are actively rewriting parts of the documentation to improve structure and clarity before new content is added. * **PR Approval:**\ Merging of your PR is subject to review by the maintainers. Please be patient as they work through the process. We appreciate your contribution and effort in making the Coolify docs better for everyone. # Add a new service template to Coolify (/docs/get-started/contribute/service) Adding a new service template to Coolify [#adding-a-new-service-template-to-coolify] Services in Coolify are templates made from normal [docker-compose](https://docs.docker.com/reference/compose-file/) files with some added Coolify magic. The service’s Git repository must have at least 1,000 stars to be added to Coolify as a one click service. See [Coolify's docker-compose specs](/knowledge-base/docker/compose#coolify-s-magic-environment-variables) to learn more about Coolify's magic and how to benefit from generated variables and storage handling. Please use this magic when submitting your PR to make the merging process smoother. 1. Add metadata At the top of your `docker-compose` file, add the following metadata: ```yaml # documentation: https://docs.example.com/ # slogan: A brief description of your service # category: One word, broad app type # tags: tag1,tag2,tag3 # logo: svgs/your-service.svg # port: 1234 ``` * `documentation`: Link to the service's official documentation * `slogan`: A short description of the service * `category`: A one word broad app type * `tags`: Comma-separated list for better searchability * `logo`: Path to the service's logo (see step 3) * `port`: The main entrypoint port of the service Always specify a port, as Caddy Proxy cannot automatically determine the service's port. 2. Create the docker-compose file Below the metadata, add your docker-compose configuration. Use Coolify's environment variable magic [here](/knowledge-base/docker/compose#coolifys-magic-environment-variables). Example: ```yaml services: app: image: your-service-image:tag environment: - DATABASE_URL=${COOLIFY_DATABASE_URL} volumes: - ${COOLIFY_VOLUME_APP}:/data ``` **Using Required Environment Variables:** When creating service templates, mark critical configuration as required to improve user experience: ```yaml services: app: image: your-service:latest environment: # Required - critical configuration that must be set by the user - DATABASE_URL=${DATABASE_URL:?} - API_KEY=${API_KEY:?} # Required with sensible defaults - improves usability - PORT=${PORT:?8080} - LOG_LEVEL=${LOG_LEVEL:?info} # Optional - features that can be left empty - DEBUG=${DEBUG:-false} - CACHE_TTL=${CACHE_TTL:-3600} ``` This helps users understand which configuration is essential and prevents deployment failures. 3. Add a logo * Create or obtain an SVG logo for your service (strongly preferred format) * If SVG is unavailable, use a high-quality.webp or JPG as a last resort * Add the logo file to the `svgs` folder in the Coolify repository * The logo filename should match the docker-compose service name exactly * For example, if your service name is `wordpress`, your logo should be `wordpress.svg` and the final path then is `svgs/wordpress.svg` use this path in the `logo` metadata. 4. Test your template Use the `Docker Compose Empty` deployment option in Coolify to test your template. This process mimics the one-click service deployment. 5. Submit a Pull Request Once your template works correctly: * Open a [PR](https://github.com/coollabsio/coolify/compare) * Add your new `.yaml` compose file under `/templates/compose` * Include the logo file in the `svgs` folder Coolify uses a [parsed version](https://github.com/coollabsio/coolify/blob/main/templates/service-templates.json) of the templates for deployment. Adding a new service template to the Coolify Documentation [#adding-a-new-service-template-to-the-coolify-documentation] Once your service template is merged into Coolify, it will be important to also add documentation for it in the Coolify docs. In the [Coolify Docs Contribute section](/get-started/contribute/documentation) we explain how to contribute and run the documentation on your own PC. The services overview page and the [All Services](/services/all) directory are **generated automatically** from the frontmatter of each markdown file in `docs/services/`. You do **not** need to edit `List.vue` or `all.md` manually anymore. The generators run as part of `bun run dev`, `bun run build`, and `bun run preview`. * `scripts/generate-service-list.mjs` → writes `src/generated/services.json` (consumed by the services overview component) * `scripts/generate-services-page.mjs` → writes `docs/services/all.md` * Both scripts share `scripts/services-data.mjs`, which parses each service's frontmatter and resolves its logo from `docs/public/images/services/` As soon as you have your local setup ready, follow these steps to add your new service: 1. Add the service logo under `/docs/public/images/services/` * Use the same base name as your service slug, e.g. `my-service.svg` or `my-service-logo.svg`. The icon resolver tries `-logo`, `_logo`, `logo`, then bare ``, then the same variants based on the title. * Prefer SVG; otherwise WebP, then PNG. Avoid JPEG for logos. 2. Create the documentation file Create `/docs/services/.md`. The slug must be lowercase and kebab-case, and must match the filename. Use this frontmatter: ```yaml --- title: "Service Name" description: "Short description that appears on the service card and search results." og: description: "SEO/social-card description (optional, longer than `description`)." category: "Analytics" icon: "/docs/images/services/service-name-logo.svg" --- ``` | Field | Required | Notes | | ---------------- | -------- | ------------------------------------------------------------------------------------------------- | | `title` | yes | Display name shown on the card | | `description` | yes | Used as the card description and in `all.md` | | `category` | yes | Determines the heading the service appears under in `all.md` and the filter in the overview | | `icon` | optional | Only set if auto-resolution can't find your logo | | `og.description` | optional | Longer description used for social/SEO meta tags | | `disabled` | optional | Set to `true` to hide the service from the listing while keeping the page reachable by direct URL | 3. Write the documentation Start writing your documentation under the frontmatter. Use the following template as a starting point: ```text # Service Name ![Service Name](/docs/images/services/service-name-logo.svg) ## What is Service Name? Brief description and use cases. ## Links - [Official website](https://example.com?utm_source=coolify.io) - [GitHub](https://github.com/example/repo?utm_source=coolify.io) ``` Use `` only for screenshots that benefit from a zoomable view, not for the logo. 4. Regenerate the listings (optional — happens automatically on `dev`/`build`) ```bash bun run generate:services ``` This refreshes `src/generated/services.json` and `docs/services/all.md`. Commit both regenerated files alongside your new service page. 5. Submit a Pull Request * Target the `next` branch * Verify the service renders correctly with `bun run dev`, including the listing card, the filter category, and the entry in `/services/all` Request a new service [#request-a-new-service] If there's a service template you'd like to see in Coolify: 1. Search [GitHub discussions](https://github.com/coollabsio/coolify/discussions/categories/service-template-requests) for existing requests. 2. If the service has been requested, upvote it. If not, create a new request. # Concepts (/docs/get-started/dev) This draws attention to important information This draws attention to important information This draws attention to important information This draws attention to important information This draws attention to important information This draws attention to important information # Downgrading (/docs/get-started/downgrade)
If you're using [Coolify Cloud](https://coolify.io/pricing/), the Coolify team handles all updates so you **cannot** downgrade the version of Coolify. If you are facing any issues, please contact [support](/get-started/support). For those who **self-host** Coolify, you can easily downgrade to the previous version. Follow the steps below to perform a downgrade on to a previous version. * Always back up your Coolify data before performing an downgrade. * Downgrading can introduce issues that can be difficult to fix. The Downgrade process involves the following three steps: * [Disable Auto Update](#_1-disable-auto-update) * [Login to Your Server via SSH](#_2-login-to-your-server-via-ssh) * [Execute the Downgrade Command](#_3-execute-the-downgrade-command) 1\. Disable Auto Update [#1-disable-auto-update] Before downgrading, it's important to disable the Auto Update feature to prevent Coolify from automatically upgrading again after you perform the downgrade. 1. Log in as the root user (or any user who has access to the root or initial team). 2. Navigate to the Settings menu in your Coolify dashboard. 3. In the Settings menu, disable the **Auto Update** feature. Disabling auto-update is essential, as it ensures that Coolify doesn’t override your downgrade with a newer version. 2\. Login to Your Server via SSH [#2-login-to-your-server-via-ssh] Next, you need to SSH into your server to execute the downgrade command. 3\. Execute the Downgrade Command [#3-execute-the-downgrade-command] To downgrade Coolify to the desired version, run the following command in your terminal: ```bash curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash -s 4.0.0-beta.369 ``` Replace `4.0.0-beta.369` with the version number you want to downgrade to. For example, you can downgrade to `4.0.0-beta.333` or any previous version. Double-check the version number you are specifying to ensure you are downgrading to the correct version. You can check the Coolify [release notes](https://github.com/coollabsio/coolify/releases) for version details. Potential Issues with Downgrading [#potential-issues-with-downgrading] While downgrading is possible, be aware of the following risks: * [Database Schema Compatibility](#database-schema-compatibility) * [Feature Incompatibility](#feature-incompatibility) *** Database Schema Compatibility: [#database-schema-compatibility] Downgrading can cause issues since the database schema may not be backward compatible. Some features may not work as expected due to changes in the database structure between versions. Feature Incompatibility: [#feature-incompatibility] Some features might not function properly after downgrading, as certain features in the newer version may rely on changes that are not present in the older version. # Installation (/docs/get-started/installation)
If you decide to go with **Coolify Cloud**, there's no installation required. Simply visit [Coolify Cloud Registration](https://app.coolify.io/register) to create an account and start using Coolify within minutes! Below, you'll find instructions for installing Coolify if you prefer to **self-host** it. Self-hosted Installation [#self-hosted-installation] If you like taking control and managing everything yourself, self-hosting Coolify is the way to go. It's completely free (apart from your server costs) and gives you full control over your setup. ```bash curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash ``` Run this script in your terminal, and Coolify will be installed automatically. For more details, including firewall configuration and prerequisites, check out the guide below. The automatic installation script only works with Ubuntu LTS versions (20.04, 22.04, 24.04). If you're using a non-LTS version (e.g., 24.10), please use the [Manual Installation](#manual-installation) method below. Before You Begin [#before-you-begin] Before installing Coolify, make sure your server meets the necessary requirements. 1\. Server Requirements [#1-server-requirements] You need a server with SSH access. This could be: * A VPS (Virtual Private Server) * A Dedicated Server * A Virtual Machine (VM) * A Raspberry Pi (see our [Raspberry Pi OS Setup Guide](/knowledge-base/how-to/raspberry-pi-os#prerequisites)) * Or any other server with SSH access It’s best to use a fresh server for Coolify to avoid any conflicts with existing applications. If you haven't picked a server provider yet, consider using [Hetzner](https://coolify.io/hetzner). You can even use our [referral link](https://coolify.io/hetzner) to support the project. 2\. Supported Operating Systems [#2-supported-operating-systems] Coolify supports several Linux distributions: * Debian-based (e.g., Debian, Ubuntu - all versions supported, but non-LTS Ubuntu requires manual installation) * Redhat-based (e.g., CentOS, TencentOS, Fedora, Redhat, AlmaLinux, Rocky, Asahi) * SUSE-based (e.g., SLES, SUSE, openSUSE) * Arch Linux (Note: Not all Arch derivatives are supported) * Alpine Linux * Raspberry Pi OS 64-bit (Raspbian) For some distros (like AlmaLinux), Docker must be pre-installed. If the install script fails, manually install Docker and re-run the script. Other Linux distributions may work with Coolify, but have not been officially tested. 3\. Supported Architectures [#3-supported-architectures] Coolify runs on 64-bit systems: * AMD64 * ARM64 Be sure to use the 64-bit version of Raspberry Pi OS (Raspbian). For details, check our [Raspberry Pi OS Setup Guide](/knowledge-base/how-to/raspberry-pi-os#prerequisites). 4\. Minimum Hardware Requirements [#4-minimum-hardware-requirements] Your server should have at least: * **CPU**: 2 cores * **Memory (RAM)**: 2 GB * **Storage**: 30 GB of free space Coolify may function properly on servers with lower specs than those mentioned above, but we recommend slightly higher minimum requirements. This ensures that users have sufficient resources to deploy multiple applications without performance issues. If you’re running both builds and Coolify on the same server, monitor your resource usage. High resource usage could make your server unresponsive. Consider enabling swap space or upgrading your server if needed. 5\. Server Resources for Your Projects [#5-server-resources-for-your-projects] The resources you need depend on your projects. For example, if you're hosting multiple services or larger applications, choose a server with higher CPU, memory, and storage. Andras runs his production apps on a server with: * **Memory**: 8GB (average usage: 3.5GB) * **CPU**: 4 cores (average usage: 20–30%) * **Storage**: 150GB (average usage: 40GB) This setup comfortably supports: * 3 NodeJS apps * 4 Static sites * Plausible Analytics * Fider (feedback tool) * UptimeKuma (uptime monitoring) * Ghost (newsletters) * 3 Redis databases * 2 PostgreSQL databases Installation Methods [#installation-methods] There are two ways to install Coolify: * [Quick Installation](#quick-installation-recommended) (Recommended) * [Manual Installation](#manual-installation) We highly recommend the **Quick Installation** method as it automates the process and reduces the chance of errors. *** Quick Installation (Recommended) [#quick-installation-recommended] This is the simplest and fastest way to get Coolify up and running. 1\. Prepare Your Server [#1-prepare-your-server] * Log in as the root user (non-root users are not fully supported yet). * Configure SSH by following the [SSH Settings Guide](/knowledge-base/server/openssh#ssh-settings-configuration). * Set up your firewall with the help of the [Firewall Guide](/knowledge-base/server/firewall). * Ensure that [curl](https://curl.se/) is installed (it usually comes pre-installed). 2\. Run the Installation Script [#2-run-the-installation-script] Once your server is ready, run: ```bash curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash ``` View the [Script's Source Code](https://github.com/coollabsio/coolify/blob/main/scripts/install.sh) If you're not logged in as the root user, run the script with sudo: ```bash curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash ``` Advanced: Customizing Installation with Environment Variables [#advanced-customizing-installation-with-environment-variables] The installation script supports several environment variables to customize your Coolify installation. These are completely optional. You can set these environment variables before running the installation script to customize your Coolify setup: | Environment Variable | Description | Default Value | Example | | ---------------------------- | ----------------------------------------------------- | ------------- | -------------------- | | `ROOT_USERNAME` | Predefined root username for first admin account | - | `admin` | | `ROOT_USER_EMAIL` | Predefined root user email for first admin account | - | `admin@example.com` | | `ROOT_USER_PASSWORD` | Predefined root user password for first admin account | - | `SecurePassword123!` | | `DOCKER_ADDRESS_POOL_BASE` | Custom Docker address pool base (CIDR notation) | `10.0.0.0/8` | `172.16.0.0/12` | | `DOCKER_ADDRESS_POOL_SIZE` | Custom Docker address pool size (must be 16-28) | `24` | `20` | | `DOCKER_POOL_FORCE_OVERRIDE` | Force override existing Docker pool configuration | `false` | `true` | | `AUTOUPDATE` | Enable/disable automatic Coolify updates | `true` | `false` | | `REGISTRY_URL` | Custom Docker registry URL for Coolify images | `ghcr.io` | `your-registry.com` | **Usage Examples:** **1. Create Admin Account During Installation:** ```bash env ROOT_USERNAME=admin \ ROOT_USER_EMAIL=admin@example.com \ ROOT_USER_PASSWORD=SecurePassword123 \ bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash' ``` See the [Create Root User with Environment Variables](/knowledge-base/create-root-user-with-env) guide for more details. **2. Custom Docker Network Pool:** ```bash env DOCKER_ADDRESS_POOL_BASE=172.16.0.0/12 \ DOCKER_ADDRESS_POOL_SIZE=20 \ bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash' ``` See the [Define Custom Docker Network with ENV](/knowledge-base/define-custom-docker-network-with-env) guide for more details. **3. Disable Auto-Updates:** ```bash env AUTOUPDATE=false \ bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash' ``` **4. Use Custom Docker Registry:** ```bash env REGISTRY_URL=your-registry.com \ bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash' ``` When using a custom registry, make sure all required Coolify images are available in your registry. **5. Combine Multiple Variables:** ```bash env ROOT_USERNAME=admin \ ROOT_USER_EMAIL=admin@example.com \ ROOT_USER_PASSWORD=SecurePassword123 \ AUTOUPDATE=false \ DOCKER_ADDRESS_POOL_BASE=172.16.0.0/12 \ bash -c 'curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash' ``` 3\. Access Coolify [#3-access-coolify] After installation, the script will display your Coolify URL (e.g., `http://203.0.113.1:8000`). Visit this URL, and you'll be redirected to a registration page to create your first admin account. **Immediately create your admin account after installation. If someone else accesses the registration page before you, they might gain full control of your server.** If you installed Coolify on a Raspberry Pi within your home network, use your private IP address to access it, as the public IP may not work. What the Installer Does: [#what-the-installer-does] * Installs essential tools (curl, wget, git, jq, openssl) * Installs Docker Engine (version 24+) * Configures Docker settings (logging, daemon) * Sets up directories at `/data/coolify` * Configures SSH keys for server management * Installs and starts Coolify Docker installed via snap is not supported! **The quick installation guide ends here. If you’ve followed the steps above, you can start using Coolify now. The guide below is for those who want to manually install and set up Coolify.** *** Manual Installation [#manual-installation] For those who prefer more control, you can install Coolify manually. This method requires a few extra steps. This manual installation method is required for: * Non-LTS Ubuntu versions (e.g., 24.10) * Systems where the automatic script encounters issues Prerequisites [#prerequisites] * **SSH**: Ensure SSH is enabled and set up correctly (see [SSH Configuration Guide](/knowledge-base/server/openssh)). * **curl**: Confirm that [curl](https://curl.se/) is installed. * **Docker Engine**: Install Docker by following the official [Docker Engine Installation guide](https://docs.docker.com/engine/install/#server) (version 24+). Docker installed via snap is not supported! *** Follow these steps for a manual setup: 1\. Create Directories [#1-create-directories] Create the base directories for Coolify under `/data/coolify`: ```bash mkdir -p /data/coolify/{source,ssh,applications,databases,backups,services,proxy,webhooks-during-maintenance} mkdir -p /data/coolify/ssh/{keys,mux} mkdir -p /data/coolify/proxy/dynamic ``` 2\. Generate & Add SSH Key [#2-generate--add-ssh-key] Generate an SSH key for Coolify to manage your server: ```bash ssh-keygen -f /data/coolify/ssh/keys/id.root@host.docker.internal -t ed25519 -N '' -C root@coolify ``` Then, add the public key to your `~/.ssh/authorized_keys`: ```bash cat /data/coolify/ssh/keys/id.root@host.docker.internal.pub >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys ``` If you already have an SSH key, you can skip generating a new one, but remember to add it to your Coolify instance after installation. 3\. Setup Configuration Files [#3-setup-configuration-files] Download the necessary files from Coolify’s CDN to `/data/coolify/source`: ```bash curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o /data/coolify/source/docker-compose.yml curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o /data/coolify/source/docker-compose.prod.yml curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o /data/coolify/source/.env curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh -o /data/coolify/source/upgrade.sh ``` 4\. Set Permissions [#4-set-permissions] Set the correct permissions for the Coolify files and directories: ```bash chown -R 9999:root /data/coolify chmod -R 700 /data/coolify ``` 5\. Generate Values [#5-generate-values] Update the `.env` file with secure random values: ```bash sed -i "s|APP_ID=.*|APP_ID=$(openssl rand -hex 16)|g" /data/coolify/source/.env sed -i "s|APP_KEY=.*|APP_KEY=base64:$(openssl rand -base64 32)|g" /data/coolify/source/.env sed -i "s|DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env sed -i "s|REDIS_PASSWORD=.*|REDIS_PASSWORD=$(openssl rand -base64 32)|g" /data/coolify/source/.env sed -i "s|PUSHER_APP_ID=.*|PUSHER_APP_ID=$(openssl rand -hex 32)|g" /data/coolify/source/.env sed -i "s|PUSHER_APP_KEY=.*|PUSHER_APP_KEY=$(openssl rand -hex 32)|g" /data/coolify/source/.env sed -i "s|PUSHER_APP_SECRET=.*|PUSHER_APP_SECRET=$(openssl rand -hex 32)|g" /data/coolify/source/.env ``` Run these commands only the first time you install Coolify. Changing these values later can break your installation. Keep them safe! 6\. Create Docker Network [#6-create-docker-network] Ensure the Docker network is created: ```bash docker network create --attachable coolify ``` 7\. Start Coolify [#7-start-coolify] Launch Coolify using Docker Compose: ```bash docker compose --env-file /data/coolify/source/.env -f /data/coolify/source/docker-compose.yml -f /data/coolify/source/docker-compose.prod.yml up -d --pull always --remove-orphans --force-recreate ``` You might have to do `docker login` at this point if you have any issues above. You can customize Coolify's containers (ports, resource limits, labels, etc.) in a way that survives upgrades by creating a `docker-compose.custom.yml` file. See [Custom Compose Overrides](/knowledge-base/custom-compose-overrides) for details. 8\. Access Coolify [#8-access-coolify] You can now access Coolify by visiting `http://203.0.113.1:8000` (replace the `203.0.113.1` with the IP address of your server). If you get stuck at any step, feel free to join our [Discord community](https://coolify.io/discord) and create a post in the support forum channel. # Upgrading (internal Postgresql) (/docs/get-started/internal-postgresql-upgrade) Internal PostgreSQL upgrade [#internal-postgresql-upgrade] Coolify self-hosted instances use an internal PostgreSQL database container named `coolify-db`. Normal Coolify updates do **not** automatically upgrade PostgreSQL to a new major version. PostgreSQL major upgrades, for example `15` to `18`, require a data migration. Changing only the Docker image is not enough, because PostgreSQL will reject data directories created by a different major version. Create or verify a recent Coolify backup before upgrading the internal PostgreSQL database. The upgrade script keeps the previous Docker volume for rollback, but you should still have an external backup before changing database versions. When to use this [#when-to-use-this] Use this only when you need to upgrade the **internal Coolify database** to a newer PostgreSQL major version. Do not use this for PostgreSQL databases that you created as project resources in Coolify. Those databases have their own lifecycle and backup/restore process. Upgrade PostgreSQL [#upgrade-postgresql] Run the script on your Coolify server: ```bash /data/coolify/source/upgrade-postgres.sh 18 ``` Replace `18` with the target PostgreSQL major version. The script will: 1. Detect the current `coolify-db` PostgreSQL version. 2. Stop the `coolify` application container to prevent writes. 3. Create a compressed `pg_dumpall` backup in `/data/coolify/backups/internal-postgres/`. 4. Create a new Docker volume, for example `coolify-db-pg18`. 5. Restore the dump into a temporary PostgreSQL container using the target version. 6. Smoke-test the restored database. 7. Write `/data/coolify/source/docker-compose.postgres-upgrade.yml`. 8. Restart the Coolify stack using the new PostgreSQL image and volume. 9. Save rollback metadata in `/data/coolify/source/postgres-upgrade-rollback.env`. PostgreSQL 18 and newer use `/var/lib/postgresql` as the container mount path. Older versions use `/var/lib/postgresql/data`. The script chooses the correct path automatically. What changes in Docker Compose [#what-changes-in-docker-compose] The script does not modify `docker-compose.yml` or `docker-compose.prod.yml`. Instead, it creates this override file: ```text /data/coolify/source/docker-compose.postgres-upgrade.yml ``` For PostgreSQL 18, it looks similar to this: ```yaml services: postgres: image: "postgres:18-alpine" volumes: - coolify-db:/var/lib/postgresql volumes: coolify-db: name: "coolify-db-pg18" external: true ``` Future Coolify updates include this override file automatically, so the upgraded image and volume stay active after normal upgrades. If you also have `/data/coolify/source/docker-compose.custom.yml`, the PostgreSQL upgrade override is loaded after the custom compose file. For conflicting `postgres` service settings, the PostgreSQL upgrade override takes precedence. Roll back [#roll-back] If the upgraded database does not work, run: ```bash /data/coolify/source/upgrade-postgres.sh rollback ``` Rollback uses the metadata saved during the last successful upgrade. It restores the previously active PostgreSQL image, Docker volume, and mount path. For example: ```text 15 → 18 → rollback = 15 15 → 18 → 19 → rollback = 18 ``` Rollback is one-step only. Each successful upgrade replaces the rollback metadata with the previously active version. The upgraded Docker volume is not deleted during rollback. You can inspect or remove it manually after you confirm the rollback works. Files created by the script [#files-created-by-the-script] | File | Purpose | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `/data/coolify/source/docker-compose.postgres-upgrade.yml` | Compose override that points Coolify to the upgraded PostgreSQL image and Docker volume. | | `/data/coolify/source/postgres-upgrade-rollback.env` | Metadata used by `upgrade-postgres.sh rollback`. | | `/data/coolify/source/postgres-upgrade-*.log` | Upgrade or rollback logs. | | `/data/coolify/backups/internal-postgres/postgres-upgrade-*.sql.gz` | Compressed database dump created before migration. | Verify the active compose configuration [#verify-the-active-compose-configuration] To inspect the final Compose configuration that will be used by Coolify, run: ```bash docker compose \ --env-file /data/coolify/source/.env \ -f /data/coolify/source/docker-compose.yml \ -f /data/coolify/source/docker-compose.prod.yml \ -f /data/coolify/source/docker-compose.custom.yml \ -f /data/coolify/source/docker-compose.postgres-upgrade.yml \ config ``` If you do not have `docker-compose.custom.yml`, remove that line from the command. # Introduction (/docs/get-started/introduction)
What is Coolify? [#what-is-coolify] Coolify is a software that makes self-hosting simple and powerful. It lets you run your applications, databases, and services on your own server, whether that’s an old laptop, a Raspberry Pi, or a rented server from a provider like [Hetzner](https://coolify.io/hetzner). With Coolify, you get full control over your projects, your data, and your costs. It’s completely free to use, open-source, and has no features locked behind a paywall. Think of Coolify as your personal alternative to cloud platforms like [Vercel](https://vercel.com?utm_source=coolify.io), [Railway](https://railway.com/?utm_source=coolify.io), or [Heroku](https://www.heroku.com/?utm_source=coolify.io), but without the huge bills or privacy trade-offs. What Coolify Is Not [#what-coolify-is-not] Coolify isn’t a cloud service that hosts everything for you, you need your own server. That could be your old laptop, a Raspberry Pi, or a rented server from a hosting provider like [Hetzner](https://coolify.io/hetzner), and you’ll need SSH access to use it. It’s not a zero-effort solution either, if you choose to self-host, you’ll need to set up your server and install Coolify. But once it’s running, managing your projects becomes very easy. Features of Coolify [#features-of-coolify] Coolify is loaded with tools to make self-hosting smooth and powerful. Here’s a detailed look at what it offers: | Features | Explanation | | :------------------------ | :-------------------------------------------------------------------------------------------------------- | | **Any Language** | Deploy static sites, APIs, backends, databases, and more with support for all major frameworks. | | **Any Server** | Deploy to any server - VPS, Raspberry Pi, EC2, your laptop via SSH. | | **Any Use-Case** | Supports single servers, multi-server setups, and Docker Swarm clusters (Kubernetes support coming soon). | | **Any Service** | Deploy any Docker-compatible service, plus a wide range of one-click options. | | **Push to Deploy** | Git integration with GitHub, GitLab, Bitbucket, Gitea, and other platforms. | | **Free SSL Certificates** | Automatically sets up and renews Let's Encrypt SSL certificates for custom domains. | | **No Vendor Lock-In** | Your data and settings stay on your servers for full control and easy portability. | | **Automatic Backups** | Back up data to S3-compatible storage and restore it with one click if needed. | | **Webhooks** | Integrate with CI/CD tools like GitHub Actions, GitLab CI, or Bitbucket Pipelines. | | **Powerful API** | Automate deployments, manage resources, and integrate with your existing tools easily. | | **Real-Time Terminal** | Run server commands directly from your browser in real-time. | | **Collaborative** | Share projects with your team, control roles, and manage permissions. | | **PR Deployments** | Deploy commits and pull requests separately for quick reviews and faster teamwork. | | **Server Automations** | Handles server setup tasks automatically after connection, saving you time. | | **Monitoring** | Monitor deployments, servers, disk usage, and receive alerts for issues. | Benefits of Using Coolify [#benefits-of-using-coolify] Coolify delivers unbeatable advantages for developers who want to self-host. Here’s why it stands out: | Benefits | Explanation | | :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cost Savings** | Avoid skyrocketing cloud costs. Use your own server for a steady, predictable price. | | **No Hidden Costs** | Transparent pricing with no unexpected charges. | | **Highly Cost-Efficient** | Save thousands monthly compared to traditional cloud platforms. Real examples can be found [here](https://twitter.com/heyandras/status/1742078215986860460), [here](https://twitter.com/heyandras/status/1752209429276086688), and [here](https://twitter.com/heyandras/status/1724510876256944244) | | **Complete Data Privacy** | Your data stays on your server, ensuring total control and security. | | **No Feature Restrictions** | All features are included in the open-source version—nothing locked behind a paywall. | | **Unlimited Usage** | Deploy unlimited websites and applications across any number of servers. | | **Quick Setup** | Start hosting in minutes with minimal maintenance required. | | **User-Friendly Interface** | Manage your infrastructure through a clean, simple dashboard designed for developers. | | **100% Open Source** | Review the code, contribute to development, and help shape the platform’s future. | | **Active Community** | Join over 16,000 people on Discord and 204,000+ servers running Coolify worldwide. | Getting Started with Coolify [#getting-started-with-coolify] Before you jump into using Coolify, it’s worth understanding a few key concepts to make your journey smoother. Learn about servers, SSH access, and how Coolify manages your projects by checking out our [concepts guide](/get-started/concepts). You have two ways to use Coolify: * [Self-Host Coolify](#self-host-coolify) * [Use Coolify Cloud](#use-coolify-cloud) *** Self-Host Coolify [#self-host-coolify] * Install Coolify on your own server. This requires setting up the server, installing Coolify, and handling updates yourself. * You’ll also need to allocate some server resources to run Coolify. * It’s completely free (except your server bills) and gives you full control over your infrastructure. Use Coolify Cloud [#use-coolify-cloud] * Let the Coolify team manage Coolify for you. * With Coolify Cloud, you don’t need to install or update Coolify yourself, and no server resources are required for Coolify itself, it runs on the Coolify team’s managed servers. * Simply create an account from [here](https://app.coolify.io/register), connect your servers via SSH keys, and start deploying. This is a paid service (starting at $5/mo), as it costs the team to host and maintain the infrastructure. * Updates on Coolify Cloud are thoroughly tested by the core team, so they might be slightly delayed for added stability. Join Our Community [#join-our-community] Got questions or need support? Our [discord community](https://coollabs.io/discord) is here to help. Connect with other Coolify users on our community server to get assistance and share your experiences. # UI Screenshots (/docs/get-started/screenshots) Coolify UI Screenshots [#coolify-ui-screenshots] The Coolify team is currently developing a brand new UI design. Below are the images showing the current UI.
















# Coolify Sponsors (/docs/get-started/sponsors) Coolify Sponsors [#coolify-sponsors] We have amazing sponsors who support the development of Coolify. # Support (/docs/get-started/support)
Community Support [#community-support] Join our [Discord community](https://coollabs.io/discord) with over **19K members**, where you can create a post in the **support forum channel** for assistance. While the community does provide some help, the [Core team](/get-started/team) is actively involved in the forum to ensure questions are addressed. Direct Support from Core Developers [#direct-support-from-core-developers] If you are a **Coolify Cloud user**, you can reach out via email at **[hi@coollabs.io](mailto:hi@coollabs.io)** for direct support from [Andras (Coolify’s founder)](https://x.com/heyandras). Since he personally handles emails, response times may be delayed. We highly recommend posting in the **Discord support forum** first, as core team members can escalate issues to the developers ([Andras](https://x.com/heyandras) & [Peak](https://x.com/peaklabs_dev)) if necessary. Important Notes [#important-notes] * We are a **small team** (fewer than **6 people**) supporting **325K+ users**, making it challenging to offer direct assistance to everyone. However, we do our best to help as much as possible. * We are planning a **paid support option** for **self-hosted users**. If you need dedicated support for your **self-hosted instance**, email **[hi@coollabs.io](mailto:hi@coollabs.io)** to discuss options. # coolLabs Team (/docs/get-started/team) coolLabs Team [#coollabs-team] The development of Coolify is guided by an international team, some of whom have chosen to be featured below.
Andras Bacsai

Andras Bacsai

Founder, Lead Developer

GitHub · Website · X · Bluesky

Peaklabs Dev

Peaklabs Dev

Core Developer

GitHub · X · Bluesky · Mastodon

ShadowArcanist

ShadowArcanist

Community Lead, Docs Maintainer

GitHub · Website · X

Aditya Tripathi

Aditya Tripathi

Developer, Community Moderator

GitHub · Website · X

Oren Aksakal

Oren Aksakal

Developer

GitHub · X

Join the coolLabs team

You?

Will You Be Next?

# Uninstalling (/docs/get-started/uninstallation)
If you're using [Coolify Cloud](https://coolify.io/pricing/), you don't need to uninstall Coolify since the Coolify Team manages everything on their servers. To stop using Coolify Cloud, simply visit the [Billing page](https://app.coolify.io/subscription/) and cancel your subscription. For those who **self-host** Coolify and wish to remove it from your server, follow the steps below to uninstall it safely: * [Stop and Remove Containers](#_1-stop-and-remove-containers) * [Remove Docker Volumes](#_2-remove-docker-volumes) * [Remove Docker Network](#_3-remove-docker-network) * [Delete Coolify Data Directory](#_4-delete-coolify-data-directory) * [Remove Docker Images](#_5-remove-docker-images) 1\. Stop and Remove Containers [#1-stop-and-remove-containers] Stop all Coolify-related Docker containers and remove them to free up system resources. Run the following commands in your terminal: ```bash sudo docker stop -t 0 coolify coolify-realtime coolify-db coolify-redis coolify-proxy coolify-sentinel sudo docker rm coolify coolify-realtime coolify-db coolify-redis coolify-proxy coolify-sentinel ``` The `-t 0` flag ensures that the containers stop immediately without waiting for a timeout. 2\. Remove Docker Volumes [#2-remove-docker-volumes] To remove the persistent data stored in Docker volumes for Coolify, run: ```bash sudo docker volume rm coolify-db coolify-redis ``` Removing volumes will delete all data stored in them permanently. Ensure you have backups if needed. 3\. Remove Docker Network [#3-remove-docker-network] Coolify uses a custom Docker network named coolify. Remove it with the following command: ```bash sudo docker network rm coolify ``` If you encounter an error indicating the network is in use, ensure that no containers are using the network before retrying. 4\. Delete Coolify Data Directory [#4-delete-coolify-data-directory] Remove the directory where Coolify stores its data on your server: ```bash sudo rm -rf /data/coolify ``` This will permanently delete all Coolify-related data. Double-check the directory path before executing this command. 5\. Remove Docker Images [#5-remove-docker-images] To free up disk space, remove all Docker images used by Coolify by running the following commands: ```bash sudo docker rmi ghcr.io/coollabsio/coolify:latest sudo docker rmi ghcr.io/coollabsio/coolify-helper:latest sudo docker rmi quay.io/soketi/soketi:1.6-16-alpine sudo docker rmi postgres:15-alpine sudo docker rmi redis:alpine ``` If you were using the default proxy, also remove its image: ```bash sudo docker rmi traefik:v3.1 ``` If you switched to the Caddy proxy, remove its image instead: ```bash sudo docker rmi lucaslorentz/caddy-docker-proxy:2.8-alpine ``` *** Coolify Successfully Uninstalled [#coolify-successfully-uninstalled] After completing these steps, Coolify and all its related resources will be completely removed from your server. # Upgrading (/docs/get-started/upgrade)
If you're using [Coolify Cloud](https://coolify.io/pricing/), the Coolify team handles all updates so you don’t need to worry about them. For those who **self-host** Coolify, there are three ways to upgrade your instance: * [Automatic Upgrade:](#_1-automatic-upgrade) For users who want easy, hands-off updates. * [Semi-Automatic Upgrade:](#_2-semi-automatic-upgrade) For users who want control over when to apply updates. * [Manual Upgrade:](#_3-manual-upgrade) For advanced users who prefer to manage the upgrade process themselves. - Always back up your Coolify data before starting an upgrade. 1\. Automatic Upgrade [#1-automatic-upgrade] Coolify can update itself automatically. This option keeps your instance always up-to-date without any extra effort. How it works? [#how-it-works] Coolify periodically checks the [CDN](https://cdn.coollabs.io/coolify/versions.json) for updates. When a new version is available, it automatically fetches the latest release from the [official repository](https://github.com/orgs/coollabsio/packages?repo_name=coolify) and starts the upgrade process on its own. Customize Automatic Updates [#customize-automatic-updates] If you’d rather manage updates yourself, you can disable auto-updates in your Coolify dashboard’s Settings. Turning off automatic updates lets you test a new version on a staging setup before updating your live environment. 2\. Semi-Automatic Upgrade [#2-semi-automatic-upgrade] This option gives you a bit more control. Coolify notifies you when an update is available, and you decide when to apply it. How it works? [#how-it-works-1] Coolify periodically checks the [CDN](https://cdn.coollabs.io/coolify/versions.json) for updates. When a new version is available, you will see an "**Upgrade**" button in the sidebar of your Coolify dashboard. Click the upgrade button to start the update process. Set Update Frequency [#set-update-frequency] You can also choose how often Coolify checks for updates by adjusting the settings (daily, weekly, etc.). This method is perfect if you want to review update details or test the upgrade before applying it. 3\. Manual Upgrade [#3-manual-upgrade] For those who prefer full control, you can upgrade Coolify manually. How to do this? [#how-to-do-this] Open your server's terminal and run the command below: ```bash curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash ``` To upgrade to a specific version, run the following command in your terminal: ```bash curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash -s 4.0.0-beta.400 ``` Replace `4.0.0-beta.400` with the version number you want to upgrade to. How it works? [#how-it-works-2] This command runs the official [Coolify installation script](https://github.com/coollabsio/coolify/blob/main/scripts/install.sh). The script checks the [CDN](https://cdn.coollabs.io/coolify/versions.json) for the latest version and updates your Coolify Instance. In the Automatic and Semi-Automatic methods, Coolify runs the installation script automatically in the background. In the Manual upgrade method, you run the script yourself. # Usage (/docs/get-started/usage)
So, you’ve decided to use Coolify, awesome choice! Now, you might be wondering whether to go with **Coolify Cloud** or set it up yourself through **self-hosting**. Let’s break it down so you can pick the best option for you. Coolify Cloud [#coolify-cloud] Coolify Cloud is the easy way to get started. It’s a paid service (starting at just **$5 a month**) where you bring your own servers and connect them to a Coolify instance that’s fully managed by our team. **We host and update the Coolify instance for you, so you don't have to allocate any of your server resources to Coolify, but you’re still responsible for your own servers and any other services running on them** Coolify Self-Hosted [#coolify-self-hosted] If you’re more of a hands-on person, self-hosting Coolify might be your thing. It’s completely free (except for your server costs, of course), and you get to control everything. You’ll install Coolify on your own server, keep it updated, and manage all the related services yourself. How Do They Compare? [#how-do-they-compare] *All of the features below refer only to the Coolify instance, not your entire server or other services.* | Feature | Coolify Cloud | Self-Hosted Coolify | | ----------------------- | ------------------------------------------------------------------- | --------------------------------------------------------- | | **Maintenance** | We take care of hosting and updating the Coolify instance for you | You’re in charge of keeping the instance running smoothly | | **Support** | Help from Coolify experts and our core team | Chat with the community on Discord | | **Email Notifications** | Pre-configured and ready to use for free | You’ll need to set this up yourself | | **Backups** | We handle automatic backups for your Coolify instance | Set up your own backup system for the Coolify instance | | **High Availability** | We’ve got you covered with reliable uptime for the Coolify instance | Depends on how you set things up | | **Stability** | We test updates thoroughly before rolling them out | Test updates yourself before upgrading | | **Cost** | Starts at **$5/month** | Free forever (just pay for your server) | And just so you know, we don’t play the “**feature lock**” game. Whether you choose Coolify Cloud or self-host, you get all the same powerful features. We’re all about giving you the full Coolify experience, no matter which path you take. Which One is Right for You? [#which-one-is-right-for-you] If you want a quick, easy setup and don’t mind paying a small fee for convenience, **Coolify Cloud** is perfect. But if you love getting hands-on, want to save every penny, and enjoy being in full control, **Self-Hosting** is the way to go. If you're still not sure which path to take, join our [Discord community](https://coolify.io/discord) and ask any questions you might have! We're here to help you decide what's best for your needs. # Tutorial videos (/docs/get-started/videos) Video Tutorials created by the community [#video-tutorials-created-by-the-community] Only few of the videos are listed here Syntax: 1.5 hours long complete walkthrough [#syntax-15-hours-long-complete-walkthrough]