Getting Started with Coolify: A Complete Guide to Building Your Own PaaS on a VPS

"I'm looking for a Heroku alternative, but setting up my own PaaS sounds daunting"—if that resonates with you, you're not alone. I used to spend exhausting hours SSHing into servers and manually configuring things with every deploy. That's when I discovered Coolify.

This article walks through the entire process from VPS setup to Coolify installation and actual application deployment. By the end, you should have your own PaaS environment up and running.

What Is Coolify?

Coolify is an open-source, self-hosted PaaS (Platform as a Service). It's gaining attention as a tool that brings the convenience of Heroku, Vercel, and Netlify to your own VPS.

Development is led by coollabs, and the project has surpassed 35,000 stars on GitHub as of 2025. The v4 series brought a major UI overhaul, making it intuitive even for first-time users.

Here's how it compares to major PaaS offerings:

Feature	Coolify	Heroku	Vercel
Pricing model	VPS costs only	Usage-based	Usage-based
Hosting	Self-hosted	Managed	Managed
Docker support	Excellent	Limited	None
Database management	Built-in	Add-ons	External integration
Git integration	GitHub/GitLab/Bitbucket	GitHub	GitHub/GitLab
SSL certificates	Let's Encrypt auto-issuance	Automatic	Automatic
Custom Dockerfile	Excellent	Limited	None
Docker Compose support	Excellent	None	None
One-click services	80+	Marketplace	None

What I found most appealing is the ability to manage applications and databases on a single VPS. For small to mid-sized projects, this alone dramatically reduces infrastructure management overhead.

When Coolify Shines

Coolify isn't the optimal choice for every project. Based on my experience, it's particularly powerful in these scenarios:

Solo development or early-stage startups: You can run multiple apps and databases on a single VPS costing just a few dollars per month. Achieving the same setup on Heroku can easily run into tens of dollars monthly.
Internal tool hosting: Tools like Metabase, n8n, and Gitea can be deployed with a single click, making internal tool setup dramatically easier.
Client staging environments: The ability to isolate environments per project while managing everything on a single server is invaluable in freelance and agency work.

Conversely, for production environments handling large-scale traffic or requiring multi-region redundancy, managed services from AWS or GCP are the more realistic choice.

VPS Requirements and Server Preparation

Before proceeding with installation, let's verify server requirements. The official documentation recommends the following specs:

OS: Ubuntu 22.04 or later (Debian-based recommended)
CPU: 2+ cores
Memory: 2GB+ (4GB recommended)
Storage: 30GB+ free space
Ports: 80, 443, and 8000 must be open

I initially tried a 1GB memory instance, but builds would fail due to insufficient memory, and I ended up switching to 2GB or more. If you're planning to start with minimum specs, I'd recommend leaving some headroom. Node.js applications in particular consume significant memory during builds, so 4GB provides peace of mind.

Choosing a VPS Provider

Coolify works on essentially any major VPS provider, domestic or international. Here are some providers I've actually tested along with my impressions:

Hetzner: Based in Europe, but offers exceptional cost-performance. A 2-core, 4GB plan runs about 5 euros per month.
ConoHa VPS: Offers domestic (Japan) regions with comprehensive Japanese language support. A strong choice for Japan-targeted services.
DigitalOcean: Referenced in Coolify's official documentation and works well with the platform.

Initial Server Setup

After provisioning your VPS, first SSH in and bring the system up to date.

sudo apt update && sudo apt upgrade -y

Coolify assumes installation under the root user, so verify that you can SSH in as root. If you're connecting as a regular user, enable root login as follows:

# Set root password
sudo passwd root

# Temporarily allow root SSH login
sudo sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
sudo systemctl restart sshd

Note that disabling root login after Coolify installation is complete is recommended.

Don't forget to configure the firewall as well.

sudo ufw allow 22
sudo ufw allow 80
sudo ufw allow 443
sudo ufw allow 8000
sudo ufw enable

After configuration, verify that the rules are correctly applied.

sudo ufw status verbose

You should see output like this:

Status: active

To                         Action      From
--                         ------      ----
22                         ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
8000                       ALLOW       Anywhere

Port 8000 is used for the Coolify admin panel. For security, you may want to restrict it by IP or limit access via VPN once you're in production.

# Example: allow access to port 8000 only from a specific IP
sudo ufw delete allow 8000
sudo ufw allow from 203.0.113.10 to any port 8000

Installation Steps

With the server prepared, it's time to install Coolify. The simplest method is using the official one-liner script.

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

This automatically installs Docker and Docker Compose, pulls the necessary containers, and sets everything up. Depending on your environment, it takes about 2–5 minutes. Progress is displayed in real-time in the terminal, so watch for any errors.

When installation completes, you'll see a message like this:

Congratulations! Coolify has been installed successfully.
Please visit http://<your-server-IP>:8000 to get started.

Open http://<your-server-IP>:8000 in your browser to begin the initial setup.

Initial Setup Flow

The initial configuration follows these steps:

Create an admin account: Register your email address and password. This account becomes the Coolify administrator.
Register the server: localhost (the installation server itself) is auto-detected. Click "Validate Server" to verify Docker and SSH connections.
SSH key verification: Verifies that the key generated by Coolify is correctly configured.
Domain configuration: Specify the domain for the admin panel (can be changed later).

In my case, I ran into an error at step 3 during SSH key verification. The cause was that Coolify's public key hadn't been correctly added to root's authorized_keys. I resolved it by checking and manually appending the key.

# Check the public key generated by Coolify
cat /data/coolify/ssh/keys/id.root@host.docker.internal.pub

# Verify it's in authorized_keys
cat ~/.ssh/authorized_keys

If the key isn't there, manually add it:

cat /data/coolify/ssh/keys/id.root@host.docker.internal.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Verifying Coolify Operation

Checking what's running behind the scenes right after installation helps deepen your understanding.

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

You should see the following containers running:

NAMES                  STATUS          PORTS
coolify                Up 3 minutes    0.0.0.0:8000->80/tcp
coolify-db             Up 3 minutes    5432/tcp
coolify-redis          Up 3 minutes    6379/tcp
coolify-realtime       Up 3 minutes
coolify-proxy          Up 3 minutes    0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp

coolify-proxy is a Traefik-based reverse proxy that handles all HTTP/HTTPS traffic routing. Thanks to this architecture, even when running multiple applications on a single server, requests are automatically routed based on domain names.

Domain Configuration and Automatic SSL Certificates

To unlock Coolify's full potential, custom domain configuration is essential. Point your DNS A record to the VPS IP address, then enter the domain in the admin panel under "Settings."

coolify.example.com → <VPS IP address>

Specifically, add an A record in your DNS provider's management panel like this:

Hostname	Type	Value
coolify	A	203.0.113.50

DNS propagation may take anywhere from a few minutes to several hours depending on the provider. You can check propagation status with this command:

dig coolify.example.com +short

If your VPS IP address is returned, DNS configuration is complete.

Once the domain is configured, Coolify automatically obtains and renews SSL certificates through Let's Encrypt. This works because Traefik reverse proxy operates internally, eliminating the need to think about certificate management. Certificates are valid for 90 days, but Traefik handles automatic renewal, so no manual renewal work is required.

Looking back, the operational burden has decreased dramatically compared to when I was manually configuring Nginx reverse proxy and SSL. Setting up certbot renewal crons and still having renewals fail in the middle of the night—if you've experienced that, you can appreciate how valuable this automation is.

Leveraging Wildcard Domains

When running multiple applications, setting up wildcard DNS is convenient.

*.app.example.com → <VPS IP address>

This way, when deploying apps on Coolify, you can freely assign subdomains like myapp.app.example.com or api.app.example.com. Eliminating the need to edit DNS records every time you add an app is subtle but remarkably convenient.

Deploying Applications

Now for the most enjoyable part of Coolify. Let's actually deploy an application. Here I'll walk through the GitHub integration deployment process using a Next.js app as an example.

GitHub Integration Setup

First, connect Coolify to GitHub.

Select "Sources" from the left menu in the Coolify admin panel
Choose "GitHub App" from "+ Add"
Click the "Register a GitHub App" link on the displayed page
Enter an application name on GitHub's page and select the repositories to install
Once authentication completes, you'll be automatically redirected back to Coolify

With this integration complete, automatic deployments trigger on pushes to the selected repositories.

Next.js App Deployment Steps

From the dashboard, select "+ Add New Resource" → "Application"
Select the GitHub App you just connected as the source
Specify the target repository and branch
"Nixpacks" is automatically selected as the build pack (it auto-detects Next.js)
Enter the app domain in the "Domains" field (e.g., myapp.example.com)
Click "Deploy"

Coolify uses Nixpacks internally as a build tool, which automatically detects from package.json that it's a Next.js project and configures the appropriate build commands and runtime.

Build logs can be monitored in real-time from the admin panel. The first build may take 5–10 minutes since there's no Docker image cache, but subsequent builds are significantly faster thanks to caching.

Environment Variable Configuration

You can add environment variables from the "Environment Variables" tab in the application settings.

For example, you might commonly configure variables like these:

DATABASE_URL=postgresql://user:password@coolify-db:5432/myapp
NEXT_PUBLIC_API_URL=https://api.example.com
NODE_ENV=production

The ability to distinguish between "Build Variable" and "Runtime Variable" is also a handy feature. You can separately manage variables needed only during build (such as API keys) and those needed at runtime.

Deploying with Dockerfile

You can also deploy using your own Dockerfile instead of relying on Nixpacks auto-detection. Simply place a Dockerfile at the repository root and select "Dockerfile" in the build pack settings.

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

Being able to bring in projects with existing Dockerfiles as-is significantly lowers the migration barrier.

Database Setup

With Coolify, you can set up databases with a single click from the GUI, not just applications. A wide range of databases are supported:

PostgreSQL
MySQL / MariaDB
MongoDB
Redis
ClickHouse

PostgreSQL Setup Example

From the dashboard, select "+ Add New Resource" → "Database"
Select "PostgreSQL"
Specify the version (e.g., 16)
Click "Start"

That's all it takes to spin up PostgreSQL in a Docker container. Connection details are displayed on the post-creation screen.

Host: <container-name>
Port: 5432
Database: postgres
Username: postgres
Password: <auto-generated password>

Applications running on the same Coolify instance can connect via Docker's internal network using the hostname. If you want to connect from outside, enable the "Publicly accessible" option to expose the port.

Backup Configuration

Database backups can be configured from the "Backups" tab in the admin panel.

Register an S3-compatible storage destination in the "S3 Storages" menu (supports AWS S3, Cloudflare R2, MinIO, etc.)
Add "Scheduled Backups" from the database settings
Specify the schedule in cron syntax (e.g., 0 3 * * * for daily at 3:00 AM)

I configure weekly production backups and daily staging backups separately. Restoration can also be executed with a single click from the GUI, providing peace of mind for emergencies.

Deploying Docker Compose Projects

Beyond single applications, you can also deploy multi-service configurations defined in docker-compose.yml. This is one of Coolify's major strengths.

For example, consider deploying a WordPress environment like this:

version: '3.8'
services:
  wordpress:
    image: wordpress:latest
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DB_NAME: wordpress
    ports:
      - "80:80"
    depends_on:
      - db
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

The deployment steps are as follows:

Select "+ Add New Resource" → "Docker Compose"
Select a GitHub repository as the source, or paste the docker-compose.yml directly
Configure environment variables and click "Deploy"

Coolify interprets the compose file and spins up all necessary containers. Domain assignment and SSL configuration work the same way as regular applications through the GUI.

Leveraging One-Click Services

Coolify includes over 80 templates for deploying commonly used OSS tools with a single click. Here are some I've found particularly useful:

Plausible Analytics: A privacy-focused, lightweight alternative to Google Analytics
n8n: A workflow automation tool—essentially a self-hosted Zapier
Uptime Kuma: A server and service monitoring tool with a simple UI and easy notification setup
Gitea: A lightweight Git hosting solution, ideal for managing private internal repositories

To deploy, simply select "+ Add New Resource" → "Service" and search for the service you want. Environment variables are pre-defined in the templates, so in most cases you can start with default settings.

Recommended Settings for Production

While it works right after installation, setting up the following early gives you peace of mind for production operations:

Enable automatic backups: Configure periodic backups to S3-compatible storage from the admin panel
Webhook notifications: Set up deploy notifications to Slack or Discord for smoother team operations
Resource monitoring: Coolify v4 lets you view server CPU and memory usage on the dashboard

Updating Coolify Itself

Coolify is actively developed with frequent updates. New version notifications appear at the top of the admin panel, and you can update with a single "Update" button click.

To update from the command line:

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

This is the same script used for installation, but it updates while preserving existing settings and data. However, major version updates may include breaking changes, so don't forget to check the release notes.

Server Disk Management

During long-term operation, Docker images and build caches can fill up disk space. Perform regular cleanup.

# Remove all unused Docker resources
docker system prune -a --volumes -f

# Check disk usage
df -h
docker system df

I perform this manually once a month. If you want to automate it, you can register it as a cron job.

# Run cleanup every Sunday at 3 AM
echo "0 3 * * 0 root docker system prune -a --volumes -f" | sudo tee /etc/cron.d/docker-cleanup

Troubleshooting

Here's a compilation of common issues encountered during Coolify operation and their solutions.

Build Failures

The most common cause is insufficient memory. If the build log shows Killed or OOMKilled, increase the server's memory or add a swap file.

# Create a 2GB swap file
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make it persistent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Adding swap alone has resolved build failures for me many times. While adding more memory is the proper fix, swap works well as a stopgap measure.

Containers Not Starting

The first step is to check the application logs. You can view them from the "Logs" tab in the admin panel or from the command line.

# List containers managed by Coolify
docker ps -a --filter "label=coolify.managed=true"

# Check logs for a specific container
docker logs <container-name> --tail 100

Common causes include missing environment variables, port conflicts, and health check failures.

SSL Certificate Acquisition Failures

If you deploy before DNS has propagated, Let's Encrypt authentication will fail. First verify that DNS is resolving correctly.

dig myapp.example.com +short

If the correct IP is returned but certificate acquisition still fails, you may have hit Let's Encrypt rate limits. Sending too many requests for the same domain in a short period results in temporary blocking, so wait a while before retrying.

Conclusion

Coolify is a tool that pleasantly defies the preconception that "self-hosted PaaS must be a nightmare to operate." As this article has shown, you can build a complete environment from VPS preparation to application deployment without specialized expertise.

Since adopting Coolify, the time I spend on deployment tasks has decreased significantly, freeing me to focus on actual application development. Of course, being self-hosted means server maintenance is your responsibility. It's not universally "better than managed services," but for teams that value cost transparency and configuration flexibility, it's a compelling option.

Start by trying it on a spare VPS or a minimal instance. Once you get hands-on, you'll likely be surprised by how easy it is.

If you need help with Coolify adoption or VPS environment setup, feel free to contact us. We provide end-to-end support from infrastructure design to CI/CD pipeline construction.