How To Install Coolify on Debian 12

Self-hosting applications has become increasingly popular among developers and businesses seeking greater control over their deployment infrastructure. Coolify emerges as a powerful solution for those looking to create their own deployment platform without the complexity of traditional DevOps tools. This comprehensive guide will walk you through the entire process of installing Coolify on Debian 12, from initial server preparation to deploying your first application.

Debian 12 (Bookworm) provides an excellent foundation for hosting Coolify due to its stability, security features, and extensive package repository. Whether you’re a seasoned system administrator or a developer venturing into self-hosting, this tutorial will equip you with the knowledge needed to successfully deploy Coolify on your Debian 12 server. You’ll learn both quick installation methods and manual setup procedures, ensuring you can choose the approach that best fits your requirements and technical expertise.

What is Coolify?

Coolify is an open-source, self-hosted deployment platform that serves as an alternative to popular cloud services like Vercel, Netlify, and Heroku. This powerful tool enables developers and organizations to deploy, manage, and scale applications on their own infrastructure while maintaining complete control over their data and deployment processes.

The platform offers a comprehensive suite of features including automated deployments from Git repositories, built-in SSL certificate management through Let’s Encrypt, database provisioning, and application monitoring. Coolify supports multiple programming languages and frameworks, making it versatile enough to handle diverse project requirements. Its web-based dashboard provides an intuitive interface for managing applications, monitoring resource usage, and configuring deployment settings.

One of Coolify’s most significant advantages is its emphasis on simplicity without sacrificing functionality. Unlike complex orchestration platforms that require extensive DevOps knowledge, Coolify abstracts much of the underlying complexity while still providing advanced users with the flexibility they need. The platform supports Docker containers natively, ensuring consistent deployments across different environments.

Self-hosting with Coolify offers several benefits over cloud platforms, including cost savings for high-traffic applications, enhanced data privacy, and freedom from vendor lock-in. Organizations can maintain complete control over their infrastructure, implement custom security policies, and avoid the unpredictable pricing models often associated with cloud providers. Additionally, Coolify’s no-vendor lock-in policy ensures that users retain full access to their configurations and data even if they decide to migrate to different solutions.

Prerequisites and System Requirements

Hardware Requirements

Before installing Coolify on Debian 12, ensure your server meets the minimum hardware specifications. Coolify requires at least a two-core processor, 2GB of RAM, and 30GB of storage space. However, these are baseline requirements for basic functionality.

For production environments or servers hosting multiple applications, consider upgrading to more robust specifications. A quad-core processor with 4GB of RAM and 50GB of SSD storage will provide better performance and accommodate growth. The actual resource requirements will vary depending on the number and complexity of applications you plan to deploy.

Storage considerations are particularly important as Coolify will store application data, database files, backups, and Docker images. SSD storage is recommended for optimal performance, especially for database-intensive applications.

Software Requirements

Debian 12 (Bookworm) compatibility is essential for this installation guide. Ensure you have SSH access to your server with root privileges, as Coolify installation requires administrative access for system-level configurations. The installation process will fail if not executed with proper permissions.

Internet connectivity is mandatory throughout the installation process, as the installer downloads Docker images, configuration files, and dependencies from remote repositories. A stable connection ensures smooth installation without interruptions that could corrupt the setup process.

The curl utility must be available on your system, though it typically comes pre-installed on most Debian distributions. This tool is essential for downloading the Coolify installation script and various components during setup.

Server Setup Preparation

Choose between Virtual Private Servers (VPS), dedicated servers, or virtual machines based on your performance requirements and budget constraints. Cloud providers like Hetzner are recommended for their reliability and competitive pricing, with many users reporting excellent experiences with Coolify deployments.

Fresh server installations are strongly recommended to avoid conflicts with existing applications or services. If you must install Coolify on a server with existing software, carefully review running services and potential port conflicts, particularly around port 8000, which Coolify uses for its web interface.

Consider the geographic location of your server relative to your users, as this will impact application performance. Choose data centers close to your target audience for optimal response times.

Pre-Installation Server Configuration

Initial System Update

Connect to your server via SSH as the root user to begin the configuration process. If you’re not logged in as root, use sudo -i to access a root shell, as the Coolify installation will fail without root privileges.

Execute a comprehensive system update to ensure all packages are current:

apt update && apt dist-upgrade -y

This command updates the package repository information and upgrades all installed packages to their latest versions. The process may take several minutes depending on the number of available updates and your internet connection speed.

Install essential packages that may be required during the installation process:

apt install curl wget gnupg lsb-release ca-certificates -y

These tools are fundamental for secure downloads and repository management throughout the Coolify installation process.

Docker Installation Verification

Coolify requires Docker Engine version 24 or higher to function properly. Check if Docker is already installed on your system:

docker --version

If Docker is not installed or you’re running an older version, install the latest Docker Engine using the official repository method. First, add Docker’s official GPG key and repository:

sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Add the Docker repository to your system’s sources:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update the package index and install Docker:

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Verify the installation by running a test container:

sudo docker run hello-world

Important Warning: Docker installed via snap is not supported by Coolify and will cause installation failures. Always use the official Docker repository installation method.

Security and Network Configuration

Configure your firewall to allow necessary traffic while maintaining security. If using UFW (Uncomplicated Firewall), install and configure it with these commands:

sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 8000/tcp
sudo ufw enable

Port 8000 must be accessible for the Coolify web interface. If you plan to serve applications through Coolify’s proxy, also open ports 80 and 443 for HTTP and HTTPS traffic respectively.

Consider implementing additional security measures such as changing the default SSH port and configuring fail2ban for brute-force protection.

Quick Installation Method (Recommended)

Using the Official Installation Script

The quick installation method is the most straightforward approach for deploying Coolify on Debian 12. This automated process handles all necessary configurations and significantly reduces the possibility of installation errors.

Execute the official Coolify installation script:

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

For non-root users, prefix the command with sudo:

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

The installation script automatically performs several critical tasks. It downloads and installs the latest Coolify version, creates necessary directory structures under /data/coolify, generates SSH keys for server management, configures Docker containers, and sets up the web interface on port 8000.

During installation, the script will display progress information and any potential issues. The process typically takes 5-10 minutes depending on your server’s specifications and internet connection speed. Do not interrupt the installation process as this could result in an incomplete or corrupted setup.

Post-Installation Verification

Once the installation completes successfully, you’ll see a congratulations message with instructions to access your Coolify instance:

Congratulations, Your Coolify instance is ready to use.
Please visit http://YOUR_SERVER_IP:8000 to get started.

Verify that Coolify containers are running properly:

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

Look for containers with “coolify” in their names and ensure their status shows as “healthy” or “running”. If any containers show unexpected statuses, restart them using:

docker restart CONTAINER_NAME

Check the installation logs for any error messages or warnings that might indicate configuration issues:

docker logs coolify

Accessing the Coolify Dashboard

Open your web browser and navigate to http://YOUR_SERVER_IP:8000, replacing YOUR_SERVER_IP with your actual server’s IP address. The Coolify welcome screen should appear, indicating a successful installation.

If you cannot access the dashboard, verify that your firewall allows traffic on port 8000 and that the Coolify containers are running. Common connectivity issues include firewall restrictions, incorrect IP addresses, or proxy configuration problems.

Security Notice: Immediately create an administrator account upon first access to prevent unauthorized access to your Coolify instance. The system is vulnerable until proper authentication is configured.

Manual Installation Method (Advanced Users)

Creating Directory Structure

For users requiring more control over the installation process, manual setup provides complete transparency and customization options. Begin by creating the essential directory structure that Coolify uses for data storage and configuration management.

Create the base directories under /data/coolify:

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

These directories serve specific purposes within the Coolify ecosystem. The applications directory stores deployed application data, databases contains database files and configurations, backups holds automated backup files, and the ssh directory manages SSH keys for server connections.

Set appropriate permissions for the directory structure:

chown -R root:root /data/coolify
chmod -R 755 /data/coolify

SSH Key Generation and Configuration

Generate SSH keys that Coolify will use for server management and application deployments:

ssh-keygen -f /data/coolify/ssh/keys/id.root@host.docker.internal -t ed25519 -N '' -C root@coolify

The Ed25519 algorithm provides excellent security with smaller key sizes compared to traditional RSA keys. The empty passphrase (-N ”) enables automated operations without manual intervention.

Add the generated public key to your authorized_keys file:

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

Verify SSH key functionality by testing the connection:

ssh -i /data/coolify/ssh/keys/id.root@host.docker.internal root@localhost

If you already have SSH keys configured, you can skip the generation step but ensure the keys are properly added to your Coolify instance after installation.

Configuration Files Setup

Download the necessary configuration files from the Coolify CDN. These files include Docker Compose configurations, environment variables, and service definitions:

cd /data/coolify/source
curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.yml -o docker-compose.yml
curl -fsSL https://cdn.coollabs.io/coolify/docker-compose.prod.yml -o docker-compose.prod.yml
curl -fsSL https://cdn.coollabs.io/coolify/.env.production -o .env

Review and customize the environment variables in the .env file according to your requirements. Key variables include database passwords, application secrets, and network configurations.

Generate secure random values for sensitive environment variables:

openssl rand -hex 32

Use the generated values to replace placeholder passwords and secret keys in your configuration files.

Setting Permissions and Generating Secure Values

Ensure all configuration files have appropriate permissions to prevent unauthorized access:

chmod 600 /data/coolify/source/.env
chmod 644 /data/coolify/source/docker-compose*.yml

Start the Coolify services using Docker Compose:

cd /data/coolify/source
docker compose --env-file .env -f docker-compose.yml -f docker-compose.prod.yml up -d

Monitor the startup process and verify all containers are running successfully:

docker compose logs -f

Initial Setup and Configuration

Creating Your First Admin Account

Access your Coolify instance through a web browser at http://YOUR_SERVER_IP:8000. The registration page will appear on first access, prompting you to create an administrator account.

Choose a strong password that includes uppercase and lowercase letters, numbers, and special characters. Avoid using common passwords or personal information that could be easily guessed. The admin account has full access to all Coolify functions, making security paramount.

Complete the registration form with your email address and preferred username. The email address is used for notifications and password recovery, so ensure it’s accessible and monitored regularly.

After account creation, you’ll be automatically logged into the Coolify dashboard where you can begin configuring your deployment environment.

Basic Coolify Configuration

The initial dashboard provides an overview of your Coolify installation status and available features. Navigate through the main sections to familiarize yourself with the interface layout and available options.

Configure basic settings including your organization name, default time zone, and notification preferences. These settings affect how Coolify displays information and sends alerts about application status and system events.

Review the security settings and enable two-factor authentication if available. This additional security layer protects your deployment environment from unauthorized access even if your password is compromised.

Server Connection Setup

Add your Debian 12 server to Coolify’s management interface by navigating to the Servers section and clicking “Add Server.” Enter your server’s IP address, SSH connection details, and authentication information.

If you used the quick installation method, Coolify should automatically detect and configure the local server connection. For manual installations or remote servers, you’ll need to provide SSH key details and verify connectivity.

Test the server connection using Coolify’s built-in connectivity checker. Successful connections will show green status indicators and allow you to proceed with application deployments.

Configure server-specific settings such as resource limits, backup schedules, and monitoring preferences. These configurations ensure optimal performance and help prevent resource exhaustion during high-traffic periods.

Troubleshooting Common Issues

Installation Failures

Permission-related issues are among the most common installation problems. Ensure you’re running the installation script as the root user or with proper sudo privileges. Non-root installations frequently fail due to insufficient permissions for Docker and system configuration.

Docker-related problems often stem from incompatible versions or improper installations. Verify that Docker Engine version 24 or higher is installed using the official repository method. Remove any snap-installed Docker packages as they’re incompatible with Coolify.

Network connectivity issues during installation can cause timeouts or incomplete downloads. Check your internet connection and ensure that your server can reach external repositories and CDN endpoints.

Access and Connectivity Issues

Port 8000 accessibility problems are frequently caused by firewall restrictions or cloud provider security groups. Verify that your firewall rules allow inbound traffic on port 8000 and that no other services are using this port.

If the Coolify dashboard is inaccessible, check container status using docker ps and restart any stopped containers. The proxy service is particularly critical for dashboard access and may require specific troubleshooting steps.

DNS resolution issues can prevent access via domain names while IP-based access continues working. Verify DNS configuration and ensure proper A record pointing to your server’s IP address.

Performance Optimization

Resource monitoring reveals performance bottlenecks and helps optimize server configurations. Monitor CPU usage, memory consumption, and disk I/O using system tools like htop, iotop, and df.

Swap space configuration can improve performance on servers with limited RAM. Configure a swap file equal to your RAM size for optimal performance:

fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

Database performance tuning may be necessary for application-heavy deployments. Consider optimizing PostgreSQL or MySQL configurations based on your specific workload patterns.

Best Practices and Security Considerations

Security Hardening

Regular security updates are essential for maintaining a secure Coolify installation. Implement automated update schedules for system packages while carefully testing Coolify updates in staging environments before production deployment.

Configure fail2ban to protect against brute-force attacks on SSH and web services:

apt install fail2ban -y
systemctl enable fail2ban
systemctl start fail2ban

Implement strong firewall rules that only allow necessary traffic. Consider using VPN access for administrative functions and restricting management interface access to specific IP addresses.

Enable SSL certificates for all web-facing applications using Coolify’s built-in Let’s Encrypt integration. This ensures encrypted communication and builds user trust in your applications.

Performance Optimization

Resource allocation strategies should match your application requirements and server capabilities. Monitor resource usage patterns and adjust container limits accordingly to prevent resource contention.

Implement comprehensive monitoring solutions that track application performance, server health, and user experience metrics. Tools like Prometheus and Grafana integrate well with Coolify deployments.

Database optimization techniques include regular maintenance tasks, proper indexing strategies, and connection pooling to improve performance and reduce resource consumption.

Deploying Your First Application

Navigate to the Applications section in your Coolify dashboard and click “Add Application” to begin your first deployment. Choose between Git repository deployment, Docker image deployment, or one-click application installation from Coolify’s marketplace.

For Git repository deployments, provide your repository URL and configure branch settings, build commands, and environment variables. Coolify supports GitHub, GitLab, and other popular Git hosting services with webhook integration for automatic deployments.

Configure build settings including the runtime environment, build commands, and output directory. Popular frameworks like Next.js, React, Vue.js, and Laravel have predefined configurations that simplify the setup process.

Monitor deployment logs in real-time to identify and resolve any build or runtime issues. Successful deployments will show green status indicators and provide access URLs for your applications.

Maintenance and Updates

Keep your Coolify installation current by regularly checking for updates through the dashboard’s System section. The update process typically involves downloading new container images and restarting services with minimal downtime.

Implement automated backup strategies for application data, databases, and Coolify configurations. Store backups in secure, off-site locations using S3-compatible storage services or other reliable backup solutions.

Monitor system health through Coolify’s built-in monitoring tools and external monitoring services. Set up alerts for critical events such as service failures, resource exhaustion, or security incidents.

Regular maintenance tasks include log rotation, database optimization, certificate renewal verification, and security audit reviews to ensure continued reliable operation.

Congratulations! You have successfully installed Coolify. Thanks for using this tutorial for installing Coolify open-source panel on Debian 12 “Bookworm” system. For additional help or useful information, we recommend you check the official Coolify website.