In this guide, we will install Coolify on a VPS and deploy a test application directly from a Git repository. Then we will configure a domain, HTTPS, environment variables, automatic deployment after a push, persistent storage, log viewing, updates, and backups for the Coolify panel itself.
In the process, we will:
- Install Coolify on an Ubuntu VPS;
- Create a project and connect a GitHub repository;
- Perform the initial application deployment;
- Connect a domain and configure SSL;
- Add environment variables;
- Configure persistent storage;
- Set up automatic redeployment after a push to the repository;
- Check deployment and runtime logs;
- Review the Coolify update process;
- Configure backups for the platform configuration.
As a result, we will have a self-hosted PaaS platform that can build, publish, and update the application from Git without manually starting Docker containers after every change.
What We’ll Deploy
In this guide, we’ll install Coolify on a separate VPS and use it as a self-hosted platform for deploying an application from a Git repository. Coolify will handle building the application, starting containers, HTTP/HTTPS routing, environment variable management, logs, and subsequent deployments.
As an example, we’ll deploy a small test application from GitHub. After the first launch, we’ll link a domain to it, enable HTTPS, add persistent storage, and verify automatic redeployment after changing the code in the repository.
How the workflow works
The overall workflow is as follows:
The developer pushes changes to the Git repository, after which Coolify retrieves the new version of the source code and starts a new deployment.
With Auto Deploy enabled, this process can be automated:
At the same time, persistent application data must not be stored solely inside the container’s file system. For this data, we will attach separate persistent storage that is retained when the container is recreated.
What you’ll need
To follow this guide, you will need:
- A VPS running Ubuntu 24.04;
- SSH access with sudo privileges;
- A public IPv4 address;
- TCP ports 80 and 443 available;
- A GitHub account;
- A Git repository with a test application;
- A domain or subdomain that can be pointed to the VPS;
- Several gigabytes of free disk space for Docker images, containers, and Coolify data.
We will use a separate subdomain for the test application. In the documentation examples, we will use 203.0.113.10 instead of the VPS’s actual public address.
Installing Coolify on a VPS
Coolify is deployed directly on a Linux server and uses Docker to run both the platform itself and applications. Before installation, make sure the VPS is up to date and that no services are already using the required web ports.
Server preparation
Connect to the VPS via SSH and update the installed packages:
sudo apt update
sudo apt upgrade -y
Check the operating system version: lsb_release -a
You can also check the available memory and free disk space:
free -h
df -h /
Coolify installs and configures the required components automatically, so you usually do not need to deploy Docker manually before using the official installer.
If Nginx, Apache, Caddy, or another reverse proxy is already running on the server and using ports 80 and 443, you need to resolve the port conflict before installation. This guide uses a separate, clean VPS.
Running the Official Installation Script
To install Coolify, run the official script: curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash
The script will check the environment, install the required dependencies, and deploy the Coolify components.
We do not recommend running scripts downloaded from the internet automatically. In production, it is better to download the script, review it, and only then run it.
The process may take several minutes. Once it is complete, the installer will display the information needed to access the dashboard.
You can open it at the address provided by the installer. During the initial setup, this may be the server address with the dashboard port, for example: http://203.0.113.10:8000
In a real configuration, use the actual public IP address of the VPS instead of the documentation IP address.
First Login and Administrator Setup
When you open Coolify for the first time, it will prompt you to create an administrator account.
Enter:
- administrator name;
- email;
- a strong, unique password.
After registration, the main Coolify dashboard will open. From there, you can create projects, connect servers and Git sources, add applications and databases, monitor deployments, and manage the platform settings.
Because Coolify is installed on the same VPS in this setup, the local server can be used as the host for subsequent application deployments.
After the initial setup, Coolify is ready to use. Next, we will create a project and connect it to a Git repository containing a test application.
Connecting a Git Repository
After installing Coolify, we will create a project and connect a Git repository containing a test application. From then on, the platform will use this repository as the source code for builds and subsequent deployments.
Creating a Project and Environment
In the Coolify panel, open the Projects and create a new project.
For example: Project name: coolify-demo
Within the project, create an environment: Environment: production
Environments let you separate different versions of the same application, such as production, staging, and development.
After creating the project, open it and add a new resource of type Application.
Connecting GitHub or GitLab
Coolify can pull code from GitHub, GitLab, and other Git sources.
For GitHub, you can use the GitHub App integration. This option is convenient because Coolify gets access only to the repositories you authorize and can automatically receive events for new pushes.
In the Coolify dashboard, select GitHub as the application source and complete the account connection process.
During setup, GitHub may ask you to authorize the installation of the Coolify GitHub App and select the repositories it will be allowed to access.
For a test project, it is enough to grant access only to the specific repository.
For GitLab, the principle is similar: Coolify gets access to the repository and uses it as the source for deployment.
If the repository is public and a more complex integration is not required, you can use a standard Git URL in some scenarios. However, for the later Auto Deploy demonstration, a full GitHub integration is more convenient.
Selecting the Repository and Branch
After connecting the Git source, select the test repository.
For example:
Repository: coolify-demo
Branch: main
Coolify will use the specified branch as the source for the production version of the application.
If the project is not located at the root of the repository, you can also specify a working directory. For a simple test application, we will leave the repository root: Base Directory: /
Deploying a test application
Now we will configure the build method and perform the first deployment.
Coolify can automatically detect the application’s technology stack or use an explicitly specified build method. The specific option depends on the contents of the repository.
Configuring the Build Method
For a standard application without its own Dockerfile, you can use Nixpacks. Coolify analyzes the repository contents, detects the language and dependencies, and then sets up the build environment.
For example, the repository for a small Node.js application might contain:
package.json
package-lock.json
server.js
The startup method must be defined in package.json:
{
"scripts": {
"start": "node server.js"
}
}
The application must listen not only on localhost, but also on the container’s network interface. For example: app.listen(process.env.PORT || 3000, ‘0.0.0.0’);
In Coolify, specify the application’s internal port: Ports Exposes: 3000
If the repository already contains a Dockerfile, you can choose to build directly from it instead of using Nixpacks. This gives you more control over the image and the startup process.
For our demo application, an automatic build with Nixpacks is sufficient.
First Deployment
After configuring the Git source and build method, click Deploy.
Coolify will perform the following steps in sequence:
- Fetch the source code from the repository;
- Prepare the build environment;
- Install dependencies;
- Build the application;
- Create and start the container;
- Connect it to the internal network and reverse proxy.
You can track progress directly in the deployment logs.
If the deployment completes successfully, it will have a status such as: Deployment successful
or the application will change to the state: Running
If the build fails, the first thing to check is the deployment logs. Common causes include a missing start command, an incorrect internal port, a dependency installation error, or an incompatible runtime version.
Testing the Application
After a successful deployment, Coolify may provide a temporary application URL or a URL configured through the proxy.
Open it in a browser.
For a test project, a simple page is sufficient, for example:
Coolify Demo
Application deployed successfully from Git.
If the page opens, the entire core workflow is already working.
Configuring the Domain and HTTPS
After the first successful deployment, the application is already running within the Coolify infrastructure. Now we will connect a custom domain to it and enable HTTPS so users can access the service at a familiar address without specifying a technical port.
DNS record for the application
First, create a DNS record with your domain registrar or DNS provider.
For the app.example.com subdomain, you will need an A record:
Type: A
Name: app
Value: 203.0.113.10
Here, 203.0.113.10 is an example public IPv4 address for the VPS. In a real configuration, specify the actual address of the server where Coolify is installed.
If you are using the root domain, the record name field may be labeled as @ or left blank, depending on the DNS provider.
After saving the record, wait for DNS to update. You can verify the result with dig +short app.example.com or nslookup app.example.com.
The domain must resolve to the public IP address of the Coolify server.
Adding a Domain in Coolify
Open the application in Coolify and go to its general settings.
In the domain field, enter the full address, for example: https://app.example.com
Coolify uses a built-in reverse proxy to route requests to the correct application. As a result, multiple services on a single VPS do not need to expose their own HTTP ports directly to the internet, and there is no need to configure a proxy such as Nginx.
After you save the settings, a request to:
will be routed by the reverse proxy to the application container and its internal port.
Before a certificate is issued, the DNS record must already point to the server, and inbound connections to ports 80 and 443 must be allowed at the cloud firewall or security group level.
Obtaining an SSL Certificate Automatically
When a domain is configured for HTTPS, Coolify can automatically obtain a TLS certificate and configure it for the reverse proxy.
For this to work, the following conditions must be met:
- The domain must point correctly to the VPS;
- The server must be accessible from the internet;
- Ports 80 and 443 must not be blocked by the firewall;
- No other service on the server must be using the reverse proxy ports.
After successful configuration, the application will be available at: https://app.example.com
The browser should show a secure HTTPS connection.
The certificate will be renewed automatically, so you usually do not need to run Certbot manually for each application.
Adding Environment Variables
Applications often require configuration that differs between development, staging, and production: API endpoints, runtime mode, service names, database connection settings, and keys for external systems.
Storing these values directly in the source code is inconvenient. Coolify lets you define them through Environment Variables and pass them to the application during the build or at startup.
Runtime Variables
Open the application and go to the Environment Variables.
Let’s add a few simple parameters:
APP_NAME=Coolify Demo
APP_ENV=production
After saving, these values can be accessed inside the application using the standard mechanisms of the language being used.
For example, in Node.js:
const appName = process.env.APP_NAME;
const appEnv = process.env.APP_ENV;
This allows the same code to be used across multiple environments by changing only the configuration in Coolify.
Depending on the application type, some variables may require a new deployment for the updated values to be passed into the container.
Secret values
Environment variables can also be used to pass sensitive parameters, such as:
DATABASE_URL
API_KEY
JWT_SECRET
These values should not be committed directly to a Git repository.
For example, instead of: const apiKey = “my-secret-key”;
the application reads the value from the environment: const apiKey = process.env.API_KEY;
This keeps the source code and configuration separate and allows different secrets to be used for different environments.
For a test application, you can keep regular sample values:
APP_NAME=Coolify Demo
APP_ENV=production
After changing the variables, we will redeploy the application and verify that the new configuration is applied inside the container.
Environment variables allow you to change an application’s configuration without placing the corresponding values directly in the source code, and they are especially convenient when using automatic deployment from Git.
Setting up persistent storage
Application containers in Coolify may be recreated during a new deployment, configuration update, or manual restart. Therefore, any data that needs to persist independently of the container lifecycle must be moved to persistent storage.
Why an application needs persistent storage
Files created only within a container’s filesystem may be lost after the container is recreated.
This is especially important for applications that store:
- User-uploaded files;
- Local databases;
- Generated content;
- Cache data that must be preserved;
- Configuration or auxiliary files.
For this type of data, Coolify lets you mount persistent storage to a specific path inside the container.
For example, a test application may write data to the following directory: /app/data
Without persistent storage, this directory is part of the current container’s filesystem. After a redeploy, the new container may have an empty directory.
With a mounted volume, the setup changes:
The container can be replaced, and the data will remain in a separate Docker volume.
Creating a Docker Volume
Open the application settings in Coolify and go to the Storages or Persistent Storage.
Create a new storage entry and specify the destination path inside the container: Destination Path: /app/data
You can assign a separate name to the Docker volume, for example: coolify-demo-data
After saving, Coolify will attach the volume to the application container.
To the application, it will look like a regular /app/data directory, but the contents will actually be stored directly on our VPS, separately from the container’s file system.
If the application uses a different directory for persistent data, specify that directory as the destination. For example, uploads may be stored in /app/uploads, while some applications use their own data directory defined by the developer.
Verifying data persistence after a redeploy
Let’s verify that persistent storage actually survives the application being recreated.
First, the application should create a test file in the mounted directory, for example: /app/data/persistent.txt
The contents can be simple: Persistent storage is working.
After that, run a new deployment of the application.
Coolify will build a new version and replace the running container, but it will mount the same volume to it.
After the redeploy is complete, check whether the file is present. If persistent.txt is still available, the data is stored outside the container’s temporary file system and is preserved between deployments.
Persistent storage does not replace backups. Deleting the volume itself, a disk failure, or losing the VPS can result in data loss, so important volumes must be backed up separately.
Configuring Automatic Deployment After a Push
You do not need to manually start a new deployment after every change in Git. Coolify can receive a notification from the Git provider and automatically deploy a new version of the application after a push to the selected branch.
How Auto Deploy Works
After automatic deployment is configured, the process looks like this:
Coolify receives an event indicating a repository change, pulls the current state of the selected branch, and starts the same build process that was used for the initial deployment.
This allows the production version of the application to automatically track the main branch.
For more complex projects, instead of deploying directly after every push, you can use separate branches, a staging environment, or CI/CD checks before publishing.
Configuring a GitHub App or webhook
If the repository is connected through a GitHub App, Coolify can use GitHub events to trigger new deployments.
In the application settings, enable automatic deployment for the selected branch:
Branch: main
Auto Deploy: Enabled
After that, changes to main will be used as the source for a new version of the application.
For other Git sources, a similar workflow can be implemented through a webhook. The Git provider sends an HTTP request to Coolify when a new commit appears, and the platform starts a deployment for the corresponding application.
A webhook is also useful when the repository is connected using a standard Git URL but updates need to be automated.
Modifying the application and pushing changes
To test Auto Deploy, let’s change the content of the test page.
For example, the application initially displayed:
Coolify Demo
Application deployed successfully from Git.
Change the second line:
Coolify Demo
Application automatically redeployed after push.
Commit the change:
git add .
git commit -m "Test Coolify auto deploy"
git push origin main
After a push, Coolify should receive an event from GitHub and create a new deployment without manually clicking the button Deploy.
A new run associated with the latest commit will appear in the deployment history.
After the build completes, open the application again. If the updated text is displayed, the push → webhook → build → deploy chain is working correctly.
Automatic deployment is especially convenient for small projects and continuous delivery because the server retrieves and deploys changes from the Git repository on its own.
Viewing application logs
After deployment, it is useful to check not only the container status but also its logs. They help you understand how the build went, whether the application started successfully, and whether any errors occur during runtime.
In Coolify, logs can be viewed directly through the web interface, so basic diagnostics do not require connecting to the VPS and manually searching for the relevant Docker container.
Deployment Logs
Deployment Logs are directly related to the deployment process.
They show the following stages:
- Retrieving the source code;
- Preparing the build environment;
- Installing dependencies;
- Running build commands;
- Creating an image;
- Starting the new application version.
When a deployment completes successfully, the end of the log will show that the build has completed and the new application version has been started.
If a deployment fails, this is the first log you should check. For example, it may show a missing dependency, an incorrect build command, or a problem creating the Docker image.
Coolify stores a separate log for each new deployment, so you can correlate errors with specific Git changes.
Runtime Logs
A deployment may complete successfully, but an error can occur after the application starts. Runtime Logs are used for situations like this.
They contain the output streams of the running container — everything the application writes to stdout and stderr.
For example, a Node.js application might output the following on startup:
Coolify Demo started
Environment: production
Listening on port 3000
If the application exits with an error or cannot connect to an external service, the corresponding messages will also appear in the runtime log.
These two types of logs therefore serve different purposes:
Deployment Logs → build and deployment
Runtime Logs → operation of an already running application
When diagnosing an issue, start by determining at which stage it occurred. If the new version does not deploy at all, review the Deployment Logs. If the deployment succeeds but the application is not working correctly, move on to the Runtime Logs.
Updating and Backing Up Coolify
Coolify manages applications and part of the server infrastructure, so the platform itself must also be kept up to date and its configuration backed up.
Updating Coolify and backing up user applications are separate tasks. A backup of the platform itself should not be treated as a substitute for backing up application databases and persistent volumes.
Checking for and Installing Updates
Coolify supports updating an installed instance through its own interface.
You can check the current version and any available updates in the Coolify settings. If a new version is available, the platform can be updated from the dashboard.
Before updating a production system, it is advisable to review the changelog for the new version and make sure your backups are up to date.
Updating the platform itself does not require manually reinstalling all applications: Coolify preserves their configuration and continues to manage the resources it created after the update.
For critical infrastructure, it is best to test updates in a staging environment first or install them during a scheduled maintenance window.
Automatic Updates
Coolify can automate updates to the platform itself.
This is convenient for small servers where there is no need to manually manage the installation of each new version. However, fully automatic updates are not suitable for every production system.
On a server running critical applications, it is safer to separate two tasks:
- Automatically check for new versions;
- Install updates manually after reviewing the changes.
This allows you to review the release notes in advance and choose an appropriate maintenance window.
If the infrastructure allows automatic updates, they can remain enabled, with application status monitored regularly after each new version is installed.
Creating a Coolify Backup
Coolify stores its own configuration, information about projects and resources, and other data required to manage the platform instance.
To recover from a failure, you need to configure backups for this data.
It is best not to store the backup only on the same VPS where Coolify is running. A local copy can be useful for quick recovery, but if the disk fails completely, the local copy may be lost along with the primary instance.
For this reason, it is better to use external storage for backups, such as S3-compatible storage.
The general workflow is as follows:
In the backup settings, specify the remote storage parameters and the schedule for creating backups. The required frequency depends on how often the platform configuration changes.
It is important to distinguish between backing up Coolify itself and backing up the services deployed through it. A Coolify backup is needed to restore the platform configuration, but persistent application data requires its own backup strategy.
For example:
Conclusion
Coolify lets you turn a standard VPS into a self-hosted platform for deploying applications from Git repositories, without having to manually build Docker images or restart containers after every change.
In this guide, we installed Coolify, connected a GitHub repository, performed the first deployment, configured a domain and HTTPS, and added environment variables and persistent storage. We then enabled automatic deployment after each push, reviewed the deployment and runtime logs, and covered updating and backing up the platform itself.
For a production environment, it is important to plan application data backups separately. Coolify backups help restore the platform configuration, but databases, Docker volumes, and user files require their own backup strategy.
FAQ
Can you deploy multiple applications on a single VPS with Coolify?
Yes. In Coolify, you can create multiple projects and resources, each deployed in a separate container or set of containers.
Each application can use its own domain, environment variables, persistent storage, and a separate Git repository.
Is GitHub required?
No. Coolify supports not only GitHub but also other Git sources, including GitLab and standard Git repositories.
The specific connection method depends on where the source code is stored and whether automatic deployment is required when changes are made.
Do I need a Dockerfile?
Not always. Coolify can build many applications automatically, for example, using Nixpacks.
If the project requires a custom environment or full control over the build process, you can add your own Dockerfile.
How does Coolify obtain an SSL certificate?
After a domain is connected, Coolify uses a reverse proxy and automatically issues a Let’s Encrypt TLS certificate, provided DNS is configured correctly and ports 80 and 443 are accessible.
The application then becomes available over HTTPS, and certificate renewal is handled automatically.
What happens after a push to GitHub?
If Auto Deploy is enabled and the GitHub integration is configured correctly, Coolify will receive a new commit event and start a new deployment.
The platform will pull the latest version of the branch, build the application, and replace the running container with the new version.
Are application files preserved after redeployment?
Only if they are stored in persistent storage.
Data written only to the container’s temporary file system may be lost when the container is recreated. For persistent files, use a Docker volume or another supported storage option.
Where can I view deployment errors?
Build and deployment errors are displayed in Deployment Logs.
If the application has been deployed successfully but is not working correctly after startup, check Runtime Logs.
Should you enable automatic updates for Coolify?
It depends on your infrastructure requirements. For small projects, automatic updates can be convenient.
For production systems, it is often safer to check for new versions automatically but install them manually after reviewing the changelog and creating an up-to-date backup.
Does a Coolify backup include application data?
Not necessarily. A Coolify backup is intended primarily for restoring the platform’s own configuration.
Databases, Docker volumes, user uploads, and other persistent data should be backed up separately.
