eco Beginner Tutorial/How-to

Deploying Dokku on a VPS:

calendar_month Jul 09, 2026 schedule 22 min read visibility 15 views

Развёртывание Dokku на VPS: Heroku-подобная PaaS для быстрого деплоя приложений

info

Need a server for this guide? We offer dedicated servers and VPS in 50+ countries with instant setup.

Need a server for this guide?

Deploy a VPS or dedicated server in minutes.

VPS Plans arrow_forward Dedicated

Deploying Dokku on a VPS: Heroku-like PaaS for Rapid Application Deployment

TL;DR

In this comprehensive guide, we will set up Dokku on your Virtual Private Server (VPS), transforming it into a powerful Heroku-like Platform as a Service (PaaS). Dokku allows developers to easily deploy, scale, and manage applications with a simple git push command, utilizing Docker containers. You will gain full control over your infrastructure, cost savings compared to cloud PaaS, and the ability to quickly launch projects.

Dokku Installation: Transforming a clean VPS into a full-fledged PaaS with Docker support.
Automatic Deployment: Deploy applications by simply pushing code to a Git repository on your server.
Application Management: Easily add databases, caches, configure environment variables, and SSL certificates.
Full Control: You own all infrastructure, data, and configurations, avoiding vendor lock-in to a specific cloud provider.
Resource Efficiency: Optimal utilization of your VPS resources for multiple applications.
Up-to-date: All steps and software versions are current for 2026, ensuring long-term applicability.

What We Are Setting Up and Why

In this guide, we will set up Dokku — a lightweight PaaS (Platform as a Service) that allows you to run and manage applications on your own server, leveraging the benefits of Docker. Dokku is often called "Heroku for VPS" because it provides a similar deployment experience: you simply push your code to a Git repository on the server, and Dokku automatically builds it into a Docker image, runs, and manages it.

Ultimately, you will get a fully functional platform for deploying web applications in various programming languages (Node.js, Python, Ruby, Go, PHP, and others) with minimal effort. This is an ideal solution for developers, startups, and small teams who need the simplicity of Heroku, but with full control over the infrastructure and lower costs.

Why Dokku?

Deployment Simplicity: Application deployment is reduced to a git push command.
Resource Efficiency: Dokku runs on a single server, making it a cost-effective solution.
Flexibility: Support for many languages and frameworks thanks to Buildpacks and Dockerfiles.
Extensibility: A rich ecosystem of plugins for databases (PostgreSQL, MySQL, Redis), message brokers, and other services.
Control: You retain full control over your server, data, and configurations, unlike fully managed cloud PaaS.

Alternatives: Cloud-managed vs. Self-hosted

There are several approaches to deploying applications:

Cloud-managed PaaS (e.g., Heroku, Render, Netlify):
- Pros: Maximum simplicity, no need to manage infrastructure, automatic scaling.
- Cons: High cost, less control, vendor lock-in, limited customization options.
Self-hosted PaaS (e.g., Dokku, CapRover, Coolify):
- Pros: Significant cost savings, full control over the server and data, flexibility in configuration choice, ability to install on any VPS.
- Cons: Requires initial setup and minimal server maintenance, scaling can be more complex than in cloud-managed solutions.
Manual Deployment on VPS (without PaaS):
- Pros: Maximum control and flexibility, suitable for very specific tasks.
- Cons: Most labor-intensive process, requires deep knowledge of system administration, manual management of each component (web server, database, CI/CD).

Dokku strikes a golden mean, providing the simplicity of PaaS with the control and savings of a self-hosted solution. It's an ideal choice for those who want to quickly deploy applications without delving into the complexities of Kubernetes or manual Docker container management.

What VPS Configuration is Needed for This Task

Choosing the right VPS configuration for Dokku depends on the number and type of applications you plan to deploy. Dokku itself is quite lightweight, but each deployed application and its accompanying services (databases, caches) consume resources.

Minimum Requirements (for 1-2 small applications, without heavy databases):

CPU: 2 vCPU
RAM: 4 GB
Disk: 80 GB SSD (for the system, Dokku, and several applications)
Network: 1 Gbit/s port, unlimited traffic or a large limit (e.g., 1 TB/month)

Recommended Configuration (for 3-5 medium applications, with multiple databases):

CPU: 4 vCPU
RAM: 8 GB
Disk: 160 GB NVMe SSD (for better disk I/O performance)
Network: 1 Gbit/s port, unlimited traffic

For comfortable work with multiple applications and databases, consider a VPS with 4 vCPU, 8 GB RAM, and 160 GB SSD. This will provide sufficient performance headroom for most development tasks and small production projects.

When a Dedicated Server is Needed, Not a VPS

A dedicated server should be considered if:

High Load: Your applications expect thousands of concurrent users or require significant computational resources.
Large Data Volume: You need to store hundreds of gigabytes or terabytes of data, which can be expensive or inefficient on a VPS.
Specific Performance Requirements: Direct access to hardware is needed for maximum disk, network, or CPU performance, which a VPS cannot always guarantee due to virtualization.
Security and Compliance Requirements: Some regulations may require physical server isolation.
Scaling: If you plan to deploy more than 10-15 medium applications or several very large ones, a single dedicated server can be a more economical and performant solution than multiple powerful VPS. In this case, a suitable dedicated server might be needed.

For most Dokku-related tasks, a powerful VPS will be more than sufficient, offering an excellent balance between performance and cost.

Location: What It Affects

Choosing a VPS location has several key aspects:

Latency: Place the server as close as possible to your primary audience or users to minimize delays in accessing the application.
Legislation: If your application handles sensitive data, it's important to consider data protection laws (e.g., GDPR in Europe) of the country where the server is physically located.
Price: The cost of a VPS may vary slightly across different regions.
Availability: Some providers offer a wider range of services or more stable infrastructure in certain data centers.

It is usually recommended to choose a data center in the same geographical region as most of your users, or in an adjacent one.

Server Preparation

Before installing Dokku, you need to perform basic setup and security hardening of your VPS. We will use Ubuntu Server 24.04 LTS (Noble Numbat) as the most current and stable version for 2026.

1. Connecting to the Server

Connect to your VPS via SSH using the credentials provided by your provider. This is usually the root user and password, or an SSH key.


ssh root@ВАШ_IP_АДРЕС_VPS

Replace ВАШ_IP_АДРЕС_VPS with your server's actual IP address.

2. System Update

Always start by updating the package list and installed packages to their latest versions. This ensures you have the most recent security fixes and functionality.


sudo apt update && sudo apt upgrade -y

Updates the list of available packages and installs all updates without prompting for confirmation.

3. Creating a New User with Sudo Privileges

Operating as the root user is not recommended for daily tasks due to security reasons. Create a new user and grant them sudo privileges.


adduser dokkuadmin

Creates a new user dokkuadmin and prompts for a password and additional information.


usermod -aG sudo dokkuadmin

Adds the user dokkuadmin to the sudo group, giving them the ability to execute commands with superuser privileges.

4. Setting up SSH Keys for the New User

It is recommended to use SSH keys for authentication instead of passwords. This significantly enhances security.

On your local machine, if you don't already have an SSH key pair, generate them:


ssh-keygen -t rsa -b 4096 -C "[email protected]"

Then, copy the public key to the server for the new user:


ssh-copy-id dokkuadmin@ВАШ_IP_АДРЕС_VPS

This command will add your public key to the ~/.ssh/authorized_keys file on the server. After this, you will be able to log in as dokkuadmin without a password.

Now, exit the root session and log in as dokkuadmin:


exit
ssh dokkuadmin@ВАШ_IP_АДРЕС_VPS

5. SSH Security Hardening

Edit the SSH server configuration file to disable root login and password authentication (if you are sure that SSH keys are working).


sudo nano /etc/ssh/sshd_config

Find and change (or add) the following lines:


PermitRootLogin no
PasswordAuthentication no

Save changes (Ctrl+O, Enter) and exit (Ctrl+X). Then restart the SSH service:


sudo systemctl restart ssh

Important: Make sure you can log in as dokkuadmin with an SSH key before disabling PermitRootLogin and PasswordAuthentication, otherwise you risk losing access to the server.

6. Firewall Configuration (UFW)

UFW (Uncomplicated Firewall) is a convenient interface for managing iptables. Configure it to allow only the necessary ports.


sudo apt install ufw -y

Installs the UFW utility.


sudo ufw allow OpenSSH

Allows incoming connections on the SSH port (default 22).


sudo ufw allow http

Allows incoming connections on the HTTP port (80).


sudo ufw allow https

Allows incoming connections on the HTTPS port (443).


sudo ufw enable

Enables the firewall. Confirm the action by pressing y.


sudo ufw status

Checks the firewall status and the list of allowed rules.

7. Installing Fail2ban

Fail2ban helps protect against brute-force attacks by blocking IP addresses from which numerous failed login attempts originate.


sudo apt install fail2ban -y

Installs Fail2ban.

Fail2ban is configured by default to protect SSH. Additional configuration can be done by copying the default configuration file:


sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

Now you can edit /etc/fail2ban/jail.local to change parameters such as ban time or number of attempts.


sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Enables Fail2ban to start automatically on boot and starts it.

8. Hostname Configuration

Set a descriptive hostname for your server. This will help with identification.


sudo hostnamectl set-hostname dokku-server

Sets the hostname to dokku-server.


echo "127.0.0.1 dokku-server" | sudo tee -a /etc/hosts

Adds an entry to the /etc/hosts file for correct resolution of the new hostname.

Your VPS is now ready for Dokku installation.

Dokku Software Installation

After preparing the server, you can proceed with Dokku installation. We will use the official Dokku repository, which ensures you get the latest and stable versions.

1. Adding the Dokku Repository

First, install the necessary utilities for working with repositories and add the Dokku GPG key.


# Устанавливаем необходимые пакеты для работы с HTTPS-репозиториями
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

Installs utilities for working with secure repositories and determining the distribution version.


# Добавляем GPG-ключ Dokku
curl -fsSL https://packagecloud.io/dokku/dokku/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/dokku-archive-keyring.gpg

Downloads the Dokku public GPG key and saves it for package authenticity verification.


# Добавляем репозиторий Dokku в список источников
echo "deb [signed-by=/usr/share/keyrings/dokku-archive-keyring.gpg] https://packagecloud.io/dokku/dokku/ubuntu/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/dokku.list

Adds the official Dokku repository for Ubuntu 24.04 LTS (Noble Numbat) to the package sources list.


# Обновляем список пакетов после добавления нового репозитория
sudo apt update

Updates the package cache so the system is aware of new packages from the Dokku repository.

2. Installing Dokku

Now that the repository has been added, you can install Dokku. As of 2026, Dokku will be version 0.30.x or newer.


# Устанавливаем Dokku. Это также установит Docker и все необходимые зависимости.
sudo apt install dokku -y

Installs Dokku and all its dependencies, including Docker Engine, which is the foundation of Dokku's operation.

3. Initial Dokku Setup (via Web Interface)

After installation, Dokku requires initial setup. This can be done via the web interface, which is available immediately after installation.

Open http://ВАШ_IP_АДРЕС_VPS in your browser. You will see the Dokku setup page.

On this page, you will need to:

Public Key: Paste your public SSH key that you used to log in to the server (cat ~/.ssh/id_rsa.pub on your local machine). This will allow you to deploy applications via Git.
Hostname: Enter the domain name you want to use for Dokku (e.g., dokku.yourdomain.com). Make sure you have configured a DNS record (A-record or CNAME) for this domain, pointing to your VPS's IP address.
Use Virtual Host Naming: Leave this option enabled. It allows Dokku to automatically route requests to your applications based on the domain name.

Click "Finish Setup". After this, Dokku will be ready for use.

4. Verifying Dokku Installation (via SSH)

You can verify that Dokku is installed and working correctly by running the command:


dokku version

The output should show the current Dokku version, for example: dokku version 0.30.x.

Also check the status of Dokku and Docker:


sudo systemctl status dokku
sudo systemctl status docker

Both services should be in an active (running) state.

5. Adding Your SSH Key to Dokku (if not done via Web Interface)

If you skipped the step of adding the SSH key in the web interface, you can do it manually:


# On your local machine:
cat ~/.ssh/id_rsa.pub

Copy the output of this command.


# On the Dokku server (via SSH):
dokku ssh-keys:add my_local_key "ssh-rsa AAAAB3NzaC..."

Replace my_local_key with any name for your key and "ssh-rsa AAAAB3NzaC..." with your copied public key.

Dokku is now fully installed and ready to deploy your first applications.

Application Configuration and Deployment

After installing Dokku, the next step is to deploy your first application and configure it. Dokku makes this process as simple as possible by using the concept of Git deployment.

1. Creating a New Application

Before deploying your code, you need to create a "slot" for your application in Dokku.


dokku apps:create my-web-app

Creates a new application named my-web-app. This name will be used in subsequent commands.

2. Configuring DNS for the Application

If you want your application to be accessible via its own domain name (e.g., app.yourdomain.com), you need to configure a DNS record. In your domain registrar's control panel, create an A-record (or CNAME, if you are using a Dokku subdomain) pointing to your VPS's IP address.

Then, inform Dokku about your application's domain:


dokku domains:add my-web-app app.yourdomain.com

Adds the domain app.yourdomain.com to the my-web-app application. Dokku will now route traffic for this domain to your application.

3. Deploying the Application

The deployment process in Dokku is very similar to Heroku. You add a remote Git repository and push your code to it.

On your local machine, in your project directory:


# Initialize a Git repository if you haven't already
git init

# Add the Dokku remote repository
git remote add dokku dokku@YOUR_DOKKU_IP_OR_DOMAIN:my-web-app

# Push your code to Dokku
git push dokku master

The command git push dokku master will send your code to the Dokku server. Dokku will automatically detect your application type (Node.js, Python, PHP, etc.) using Buildpacks, build a Docker image, run it, and make it accessible.

4. Managing Environment Variables

For sensitive data such as API keys, database credentials, and other secrets, use environment variables. Dokku allows you to manage them easily.


dokku config:set my-web-app MY_API_KEY="your_secret_api_key_here" DATABASE_URL="postgres://user:pass@host:port/db"

Sets environment variables for the my-web-app application. These variables will be available to your application at runtime.


dokku config:unset my-web-app MY_API_KEY

Removes an environment variable.


dokku config:get my-web-app MY_API_KEY

Retrieves the value of a specific variable (unless it's a secret variable, which is hidden by default).


dokku config my-web-app

View all environment variables for the application.

5. Installing and Connecting Databases (Dokku Plugins)

Dokku supports many plugins for various services, including databases. For example, for PostgreSQL:


# Install the PostgreSQL plugin
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres

Installs the Dokku plugin for managing PostgreSQL databases.


# Create a new database
dokku postgres:create my-web-app-db

Creates a PostgreSQL database instance named my-web-app-db.


# Link the database to the application
dokku postgres:link my-web-app-db my-web-app

Links the database to the my-web-app application. This automatically sets the DATABASE_URL environment variable in the application, containing the connection details.

Similarly, you can install plugins for MySQL, Redis, MongoDB, and other services.

6. Configuring TLS/HTTPS with Let's Encrypt

To ensure the security and trustworthiness of your application, it is crucial to use HTTPS. Dokku has excellent integration with Let's Encrypt for automatic SSL certificate acquisition and renewal.


# Install the Let's Encrypt plugin
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git letsencrypt

Installs the Dokku plugin for working with Let's Encrypt certificates.


# Set email for Let's Encrypt notifications
dokku letsencrypt:set my-web-app email [email protected]

Specifies your email address, which Let's Encrypt will use for important certificate notifications.


# Enable Let's Encrypt for the application
dokku letsencrypt:enable my-web-app

Requests and installs an SSL certificate for my-web-app. Ensure that the DNS record for app.yourdomain.com already points to your VPS, otherwise the certificate request will fail.

Dokku will automatically configure Nginx (or Caddy, if you are using the corresponding plugin) to use the certificate and redirect HTTP to HTTPS.

7. Checking Application Health

After deployment and configuration, ensure that your application is working correctly.


dokku apps:report my-web-app

Shows a detailed report on the application's status, its URL, domains, used ports, etc.


dokku logs my-web-app --tail 100

View the last 100 lines of application logs. This is extremely useful for debugging.


curl -I https://app.yourdomain.com

Performs an HTTP HEAD request to your application to check its availability and response status (e.g., HTTP/1.1 200 OK).


ping app.yourdomain.com

Checks the network accessibility of your application's domain.

You can also set custom health-checks for Dokku to more intelligently determine application health after deployment:


dokku ps:set my-web-app deploy-wait-period 30
dokku ps:set my-web-app deploy-wait-healthcheck /health

These commands set a wait period of 30 seconds after a new container starts and specify the URL /health for health checking. If the application does not respond to this URL within 30 seconds, the deployment will be considered unsuccessful.

Backups and Maintenance

Even with Dokku, backups and regular maintenance are critically important for ensuring the reliability and security of your applications. This is your responsibility as the owner of a self-hosted PaaS.

1. What to Back Up

For a Dokku installation, several categories of data need to be backed up:

Dokku Configuration: Dokku configuration files, SSH keys, application and plugin information. Typically located in /etc/dokku and /home/dokku.
Application Data: If your application uses persistent volumes to store files (e.g., user-uploaded images), these need to be backed up. Dokku mounts volumes in /var/lib/dokku/data/APP_NAME.
Databases: Data from all linked databases (PostgreSQL, MySQL, Redis, etc.). Dokku plugins provide convenient export commands.

2. Simple Auto-Backup Script

Let's create a simple script that will archive key data and databases. For storage, you can use a local directory with subsequent synchronization to external storage.

Create the file /usr/local/bin/dokku-backup.sh:


#!/bin/bash

# Directory for temporary backup storage
BACKUP_BASE_DIR="/mnt/backups/dokku"
DATE=$(date +%Y%m%d%H%M%S)
LOG_FILE="/var/log/dokku_backup.log"

# Create backup directory if it doesn't exist
mkdir -p "$BACKUP_BASE_DIR"

echo "--- Dokku Backup Started: $DATE ---" >> "$LOG_FILE"

# 1. Dokku Configuration Backup
echo "Backing up Dokku configuration..." >> "$LOG_FILE"
sudo tar -czf "$BACKUP_BASE_DIR/dokku_config_$DATE.tar.gz" /etc/dokku /home/dokku 2>> "$LOG_FILE"
if [ $? -eq 0 ]; then
    echo "Dokku config backup successful." >> "$LOG_FILE"
else
    echo "Dokku config backup failed!" >> "$LOG_FILE"
fi

# 2. Backup all Dokku applications
echo "Backing up Dokku applications and databases..." >> "$LOG_FILE"
dokku apps:list --quiet | while read APP_NAME; do
    if [ -z "$APP_NAME" ]; then
        continue
    fi
    echo "  Processing app: $APP_NAME" >> "$LOG_FILE"

    # Backup persistent application volumes (if any)
    dokku storage:export "$APP_NAME" > "$BACKUP_BASE_DIR/${APP_NAME}_storage_${DATE}.tar" 2>> "$LOG_FILE"
    if [ $? -eq 0 ]; then
        echo "  Storage for $APP_NAME backed up." >> "$LOG_FILE"
    else
        echo "  Storage backup for $APP_NAME failed or no storage configured." >> "$LOG_FILE"
    fi

    # Backup databases linked to the application
    # PostgreSQL
    if dokku postgres:linked "$APP_NAME" &>/dev/null; then
        DB_NAME=$(dokku postgres:linked "$APP_NAME" | head -n 1)
        echo "  Backing up PostgreSQL database $DB_NAME for $APP_NAME..." >> "$LOG_FILE"
        dokku postgres:export "$DB_NAME" > "$BACKUP_BASE_DIR/${APP_NAME}_${DB_NAME}_${DATE}.sql" 2>> "$LOG_FILE"
        if [ $? -eq 0 ]; then
            echo "  PostgreSQL database $DB_NAME for $APP_NAME backed up." >> "$LOG_FILE"
        else
            echo "  PostgreSQL database $DB_NAME backup failed!" >> "$LOG_FILE"
        fi
    fi
    # MySQL
    if dokku mysql:linked "$APP_NAME" &>/dev/null; then
        DB_NAME=$(dokku mysql:linked "$APP_NAME" | head -n 1)
        echo "  Backing up MySQL database $DB_NAME for $APP_NAME..." >> "$LOG_FILE"
        dokku mysql:export "$DB_NAME" > "$BACKUP_BASE_DIR/${APP_NAME}_${DB_NAME}_${DATE}.sql" 2>> "$LOG_FILE"
        if [ $? -eq 0 ]; then
            echo "  MySQL database $DB_NAME for $APP_NAME backed up." >> "$LOG_FILE"
        else
            echo "  MySQL database $DB_NAME backup failed!" >> "$LOG_FILE"
        fi
    fi
    # Redis (can be exported as an RDB file or via AOF)
    if dokku redis:linked "$APP_NAME" &>/dev/null; then
        REDIS_NAME=$(dokku redis:linked "$APP_NAME" | head -n 1)
        echo "  Backing up Redis instance $REDIS_NAME for $APP_NAME..." >> "$LOG_FILE"
        # For Redis, it is usually recommended to take a snapshot via the SAVE command or copy the RDB file
        # This example merely demonstrates that something can be done.
        # A real Redis backup requires more complex logic (e.g., copying the RDB file from the container)
        echo "  (Redis backup requires direct access to container or SAVE command)" >> "$LOG_FILE"
        # Example: dokku redis:cli $REDIS_NAME SAVE
        # Then copy the .rdb file from /var/lib/dokku/services/redis/$REDIS_NAME/data/dump.rdb
    fi

done >> "$LOG_FILE" 2>&1

# 3. Clean up old backups (e.g., keep backups for the last 7 days)
echo "Cleaning old backups (older than 7 days)..." >> "$LOG_FILE"
find "$BACKUP_BASE_DIR" -type f -name "*.tar.gz" -mtime +7 -delete 2>> "$LOG_FILE"
find "$BACKUP_BASE_DIR" -type f -name "*.tar" -mtime +7 -delete 2>> "$LOG_FILE"
find "$BACKUP_BASE_DIR" -type f -name "*.sql" -mtime +7 -delete 2>> "$LOG_FILE"
echo "Old backups cleaned." >> "$LOG_FILE"

echo "--- Dokku Backup Finished: $DATE ---" >> "$LOG_FILE"

Make the script executable:


sudo chmod +x /usr/local/bin/dokku-backup.sh

3. Where to Store Backups

Storing backups on the same server as the original data is extremely risky. In the event of a disk failure or server compromise, you will lose both your data and your backups.

Recommended backup storage options:

External S3-compatible object storage: For example, AWS S3, DigitalOcean Spaces, Backblaze B2, MinIO. Use utilities like s3cmd, rclone, or aws cli to synchronize backups from /mnt/backups/dokku.
Separate VPS: An inexpensive VPS in another data center, where you can copy backups via rsync or scp.
Network Attached Storage (NAS): If you have your own network storage, you can mount it via NFS or SMB.

Example of synchronization with S3 using rclone (after installation and configuration):


# Add this line to the end of the dokku-backup.sh script
rclone sync /mnt/backups/dokku remote_s3_bucket:dokku-backups --log-file="$LOG_FILE" --log-level INFO

Replace remote_s3_bucket:dokku-backups with your configured remote storage name and path.

4. Automating Backups with Cron

Configure Cron to run the backup script daily or weekly.


sudo crontab -e

Add the following line to run the script daily at 3:00 AM:


0 3 * * * /usr/local/bin/dokku-backup.sh >> /var/log/dokku_backup.log 2>&1

This entry will run the script every day at 3 AM and record all output to /var/log/dokku_backup.log.

5. Updates: Rolling vs. Maintenance Window

OS and Dokku Updates:
- Rolling updates: For minor Dokku and OS package updates (sudo apt update && sudo apt upgrade -y), these can be performed regularly, perhaps once every week or two. Dokku usually handles updates well without stopping applications, but there is always a small risk.
- Maintenance window: For major Dokku or OS updates (e.g., upgrading from Ubuntu 24.04 to 26.04), it is highly recommended to schedule a maintenance window. Stop applications, perform a full backup, execute the update, and verify functionality. This minimizes downtime risks.
Application Updates:
- Updates to your own applications occur via git push dokku master. Dokku performs a "rolling deployment" by default: a new container is started, and only after its successful launch is traffic switched to it. The old container is removed. This minimizes downtime.

Regularly check official Dokku sources for new versions and update recommendations.

Troubleshooting + FAQ

Even with a convenient platform like Dokku, issues can sometimes arise. Below are typical questions and their solutions.

Application Fails to Start After Deploy (Deploy failed)

What to check: First, examine the deploy and application execution logs. Dokku outputs them to the console during git push. If you missed them, use the command dokku logs my-app --tail 100.

How to fix: Look for errors related to missing dependencies, incorrect startup commands (e.g., in Procfile), code errors, or issues with environment variables. Ensure your Procfile is correct, and all necessary ports (e.g., PORT for the web server) are configured correctly and the application is listening on them. Verify that all required Buildpacks have been applied.

Cannot Connect via SSH to Dokku or Deploy Applications

What to check:

Check your SSH key: cat ~/.ssh/id_rsa.pub on your local machine and dokku ssh-keys on the server. Ensure the public key is added to Dokku.
Check SSH server settings: sudo nano /etc/ssh/sshd_config. Ensure that PasswordAuthentication no is not blocking you if you are not using keys, and that PermitRootLogin no is not interfering if you are trying to log in as root.
Check the firewall (UFW): sudo ufw status. Ensure that port 22 (SSH) is allowed.
Ensure that the Dokku user (usually dokku) has correct permissions.

How to fix: If the key is not added, add it. If there's a firewall issue, allow the port. If you've locked yourself out, you might need to use your VPS provider's control panel for console access or recovery.

HTTPS Not Working or Let's Encrypt Not Issuing Certificate

What to check:

DNS records: Ensure that your application's domain name (e.g., app.yourdomain.com) correctly points to your Dokku server's IP address. Use dig app.yourdomain.com.
Firewall: Ensure that ports 80 (HTTP) and 443 (HTTPS) are allowed in UFW (sudo ufw status).
Email for Let's Encrypt: Ensure that you have specified a correct email address using dokku letsencrypt:set my-app email [email protected].
Let's Encrypt limits: Check if you have exceeded the certificate request limits.
Let's Encrypt logs: dokku logs --app my-app --ps letsencrypt or dokku letsencrypt:list my-app to get the status.

How to fix: Correct DNS records, open ports in the firewall, and ensure the email is correct. If limits are exceeded, you will have to wait or use a different domain.

Application is Slow or Consumes Too Many Resources

What to check:

Application logs: dokku logs my-app can show errors, memory leaks, or inefficient database queries.
Server monitoring: Use htop, free -h, iotop to check CPU, RAM, disk, and network usage.
Scaling: You might need to increase the number of processes for your application: dokku ps:scale my-app web=2.
DB resources: Check if the database is a bottleneck.

How to fix: Optimize application code, database queries. Increase VPS resources or consider scaling the application (horizontal or vertical). Check Dokku configuration for container resource limits.

What is the minimum suitable VPS configuration?

To run Dokku and 1-2 small applications, such as a simple blog or REST API, you will need a minimum of 2 vCPU, 4 GB RAM, and 80 GB SSD. This will be sufficient for basic tasks and learning the platform. However, if you plan to deploy multiple applications, use databases, caches, or expect moderate load, it is recommended to choose a configuration with 4 vCPU, 8 GB RAM, and 160 GB NVMe SSD for better performance and stability.

What to choose — VPS or dedicated for this task?

For most Dokku use cases (development, small production projects, SaaS for small teams), a VPS is the optimal choice. It offers an excellent balance between cost, flexibility, and performance. A dedicated server should only be considered in cases of very high load, mission-critical applications with strict performance and isolation requirements, large volumes of stored data, or stringent regulatory compliance requirements that demand physical hardware isolation. If you are just starting, always choose a VPS.

How to add a domain to an application?

To add a domain name to your Dokku application, first ensure that you have configured the corresponding DNS A-record with your domain registrar, pointing to your VPS's IP address. Then, use the command dokku domains:add my-app yourdomain.com, replacing my-app with your application's name and yourdomain.com with the desired domain. After this, Dokku will automatically configure traffic routing.

Conclusions and Next Steps

Congratulations! You have successfully deployed Dokku on your VPS, transforming it into a powerful and flexible PaaS. Now you can enjoy the simplicity of deploying applications with Git, while maintaining full control over your infrastructure and significantly saving on cloud services. Dokku provides developers the freedom to focus on code, not on complex server setup.

What's next?

Explore Dokku Plugins: Explore Dokku's rich plugin ecosystem to add Redis, MongoDB, RabbitMQ, and other services to your applications. This will significantly expand the functionality of your PaaS.
CI/CD Integration: Automate the deployment process using continuous integration and delivery tools such as GitHub Actions, GitLab CI/CD, or Jenkins. Configure them so that every successful commit to the master branch automatically triggers git push dokku master.
Monitoring and Logging: Implement solutions for server and application performance monitoring (e.g., Prometheus + Grafana) and centralized logging (ELK Stack or Graylog) to get a complete picture of your infrastructure's status.

bolt Ready to deploy?

Get a fast, reliable Valebyte server

NVMe storage. 24/7 support. 60-second deployment. Plans from $4/month with full root access and DDoS protection on every node.

check_circle Choose VPS, dedicated, or GPU
check_circle Hourly billing, cancel anytime
check_circle EU + US + Asia datacenters

rocket_launch View VPS plans arrow_forward dns Browse dedicated servers

Trusted by developers and agencies worldwide

Was this guide helpful?

Dokku deployment on VPS: Heroku-like PaaS for rapid app deployment