How to Deploy Dokku – Lightweight Open-Source PaaS Introduction

Dokku is an open-source Platform-as-a-Service (PaaS) that transforms a Linux server into a lightweight application deployment platform. Built on Docker, it enables Git-based deployments similar to Heroku while maintaining full control over your infrastructure. Dokku supports multiple programming languages, automatic SSL certificate provisioning, environment variable management, and zero-downtime deployments through a simple command-line interface.

This article explains how to deploy Dokku on a Linux-based server using Docker Compose, configure SSH-based Git deployments, manage application environment variables, and enable automatic HTTPS with Let's Encrypt certificates through Traefik integration.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server (with at least 2 CPU cores and 4 GB of RAM) as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Create a DNS A record pointing to your server's IP address (for example, dokku.example.com).

Set Up the Directory Structure, Configuration, and Environment Variables

Dokku requires a project directory for Docker Compose files and a data directory for persistent application storage. The .env file defines the hostname and version variables that Docker Compose injects into the container at runtime.

1. Create the project directory structure.

   CONSOLE

   Copy

   $ mkdir -p ~/dokku/data

   Explain Code

   Powered by Vultr AgentBeta

   The ~/dokku directory stores your Docker Compose project files (docker-compose.yml, .env), and ~/dokku/data holds Dokku's persistent application data that mounts into the container.

2. Navigate to the project directory.

   CONSOLE

   Copy

   $ cd ~/dokku

   Explain Code

   Powered by Vultr AgentBeta

3. Create a .env file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following environment variables:

   INI

   Copy

   DOKKU_HOSTNAME=dokku.example.com
   DOKKU_VERSION=0.37.6

   Explain Code

   Powered by Vultr AgentBeta

   Replace dokku.example.com with your registered domain. The next section uses these values to create a Docker Compose manifest and start Dokku as a containerized service on your server.

   Save and close the file.

Deploy with Docker Compose

Docker Compose manages Dokku as a containerized service with persistent storage volumes. The configuration exposes port 3022 for SSH-based Git deployments and mounts the Docker socket to enable Dokku to create and manage application containers on the host.

1. Add your user account to the Docker user group. This allows you to run Docker commands without sudo.

   CONSOLE

   Copy

   $ sudo usermod -aG docker $USER

   Explain Code

   Powered by Vultr AgentBeta

2. Apply the new group membership.

   CONSOLE

   Copy

   $ newgrp docker

   Explain Code

   Powered by Vultr AgentBeta

3. Create and edit a Docker Compose manifest file.

   CONSOLE

   Copy

   $ nano docker-compose.yml

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following contents:

   YAML

   Copy

   services:
     dokku:
       image: dokku/dokku:${DOKKU_VERSION}
       container_name: dokku
       network_mode: bridge
       ports:
         - "3022:22"
       volumes:
         - "./data:/mnt/dokku"
         - "/var/run/docker.sock:/var/run/docker.sock"
       environment:
         DOKKU_HOSTNAME: ${DOKKU_HOSTNAME}
         DOKKU_HOST_ROOT: /var/lib/dokku/home/dokku
         DOKKU_LIB_HOST_ROOT: /var/lib/dokku/var/lib/dokku
       restart: unless-stopped

   Explain Code

   Powered by Vultr AgentBeta

   The configuration does the following:

   • image: Pins the Dokku container image version from your .env file.
   • ports: Publishes the Dokku SSH port on the host, mapping host port 3022 to container port 22 for Git deployments.
   • "./data:/mnt/dokku": Persists Dokku state (apps, config, plugins, certificates) in the ~/dokku/data directory.
   • "/var/run/docker.sock:/var/run/docker.sock": Bind-mounts the host Docker socket into the container, allowing Dokku to create and manage application containers directly on the host Docker daemon.
   • restart: Ensures Dokku starts automatically after reboots.

   Save and close the file.

5. Start the services.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

6. Verify the service's status.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   Verify that the Dokku container is in the running state and the mapped ports are correct.

   For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Access and Configure Dokku

Dokku uses SSH for all application management tasks, including creating apps, deploying code via Git, and managing domains and configuration. SSH key authentication eliminates the need for password-based login and provides secure communication between your local machine and the Dokku server. The key must be registered with Dokku before remote operations can proceed.

1. On your local machine (the machine from which you SSH into your server), generate an SSH key.

   CONSOLE

   Copy

   $ ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "dokku"

   Explain Code

   Powered by Vultr AgentBeta
   • ssh-keygen: Generates an SSH key pair (private + public key) for secure, passwordless authentication.
   • -t ed25519: Uses the Ed25519 algorithm (modern, fast, secure).
   • -f ~/.ssh/id_ed25519: Saves the private key as ~/.ssh/id_ed25519 and the public key as ~/.ssh/id_ed25519.pub.
   • -C "dokku": Adds a label to the public key so you can identify its purpose later (in this case, it labels the key as Dokku).

2. Display your public key and copy the output to your clipboard.

   CONSOLE

   Copy

   $ cat ~/.ssh/id_ed25519.pub

   Explain Code

   Powered by Vultr AgentBeta

3. On the server (the instance where Dokku runs), add your public key to Dokku. Replace YOUR_SSH_KEY with your own key.

   CONSOLE

   Copy

   $ echo "YOUR_SSH_KEY" | docker compose exec -T dokku dokku ssh-keys:add admin

   Explain Code

   Powered by Vultr AgentBeta
   • docker compose exec -T dokku: Runs a command inside the running Dokku container that the Docker Compose file defines as the Dokku service. -T disables pseudo-TTY allocation, which piping input into the container requires.
   • dokku ssh-keys:add admin: Registers the incoming public key in Dokku under the name admin, allowing SSH/Git deployments with the matching private key.

4. Verify the SSH key registration.

   CONSOLE

   Copy

   $ docker compose exec -it dokku dokku ssh-keys:list

   Explain Code

   Powered by Vultr AgentBeta

   The output lists your registered SSH key with the name admin. Dokku now recognizes your SSH key, allowing secure access and deployments.

Set Up Remote Access to Dokku

The SSH config file creates a host alias that simplifies Dokku commands by storing the server IP, username, port, and identity file path. The alias enables short command syntax like ssh dokku-server instead of full connection strings.

1. Open ~/.ssh/config on your local machine.

   CONSOLE

   Copy

   $ nano ~/.ssh/config

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following content:

   INI

   Copy

   Host dokku-server
     HostName YOUR_SERVER_IP
     User dokku
     Port 3022
     IdentityFile ~/.ssh/id_ed25519

   Explain Code

   Powered by Vultr AgentBeta

   Replace YOUR_SERVER_IP with your server's public IP address.

   Save and close the file.

3. Test the connection from your local machine.

   CONSOLE

   Copy

   $ ssh dokku-server

   Explain Code

   Powered by Vultr AgentBeta

   The Dokku command list confirms SSH access is configured correctly.

4. Verify the Dokku version.

   CONSOLE

   Copy

   $ ssh dokku-server version

   Explain Code

   Powered by Vultr AgentBeta

   The output displays the installed Dokku version.

Deploy a Sample Application

Dokku receives code through Git push operations, automatically detects the application type using buildpacks, builds the application, and exposes it through the configured domain. The deployment process requires creating an application in Dokku, adding a Git remote, and pushing code to trigger the build.

1. Create an application from your local machine.

   CONSOLE

   Copy

   $ ssh dokku-server apps:create ruby-getting-started

   Explain Code

   Powered by Vultr AgentBeta

   This creates a new Dokku application named ruby-getting-started and configures its virtual host settings.

2. Verify that the application is created.

   CONSOLE

   Copy

   $ ssh dokku-server apps:list

   Explain Code

   Powered by Vultr AgentBeta

   The output lists all deployed applications, including ruby-getting-started.

3. Clone the sample application locally.

   CONSOLE

   Copy

   $ git clone https://github.com/heroku/ruby-getting-started

   Explain Code

   Powered by Vultr AgentBeta

4. Navigate to the application directory.

   CONSOLE

   Copy

   $ cd ruby-getting-started

   Explain Code

   Powered by Vultr AgentBeta

5. Add the Dokku Git remote.

   CONSOLE

   Copy

   $ git remote add dokku dokku-server:ruby-getting-started

   Explain Code

   Powered by Vultr AgentBeta

   This command adds a Git remote named dokku that points to your Dokku server and application.

6. Deploy the application to Dokku.

   CONSOLE

   Copy

   $ git push dokku main

   Explain Code

   Powered by Vultr AgentBeta

   Dokku receives the code, builds the application, and deploys it. The output displays the application URL where it's accessible.

Manage Environment Variables

Environment variables store sensitive configuration values such as API keys, database credentials, and authentication tokens outside your application code. This approach prevents committing secrets to version control and allows different configurations across development, staging, and production environments.

Add Environment Variables

1. Set a single environment variable for your application.

   CONSOLE

   Copy

   $ ssh dokku-server config:set ruby-getting-started SECRET_KEY=your-secret-value

   Explain Code

   Powered by Vultr AgentBeta

   Dokku automatically restarts the application to apply the new configuration.

2. Set multiple environment variables in a single command.

   CONSOLE

   Copy

   $ ssh dokku-server config:set ruby-getting-started DB_HOST=localhost DB_USER=admin DB_PASS=secret

   Explain Code

   Powered by Vultr AgentBeta

3. View all configured environment variables.

   CONSOLE

   Copy

   $ ssh dokku-server config:show ruby-getting-started

   Explain Code

   Powered by Vultr AgentBeta

   The output displays all environment variables currently set for the application.

   Note

   Your application code accesses these environment variables using standard language methods: ENV["SECRET_KEY"] in Ruby, os.environ["SECRET_KEY"] in Python, or process.env.SECRET_KEY in Node.js.

Remove Environment Variables

1. Remove an environment variable when you no longer need it.

   CONSOLE

   Copy

   $ ssh dokku-server config:unset ruby-getting-started SECRET_KEY

   Explain Code

   Powered by Vultr AgentBeta

   This removes the variable and restarts the application.

2. Verify that the variable is removed.

   CONSOLE

   Copy

   $ ssh dokku-server config:show ruby-getting-started

   Explain Code

   Powered by Vultr AgentBeta

   The output confirms the variable no longer appears in the configuration.

Configure Traefik Proxy and SSL/TLS Certificates

Dokku includes Traefik integration that automatically provisions and renews Let's Encrypt certificates for deployed applications. The Traefik proxy replaces the default nginx proxy and handles TLS termination, routing, and certificate management through ACME protocol.

1. Stop the default nginx proxy.

   CONSOLE

   Copy

   $ ssh dokku-server nginx:stop

   Explain Code

   Powered by Vultr AgentBeta

2. Set Traefik as the global default proxy for all applications.

   CONSOLE

   Copy

   $ ssh dokku-server proxy:set --global traefik

   Explain Code

   Powered by Vultr AgentBeta

3. Set the Let's Encrypt email address globally for certificate registration and expiry notifications.

   CONSOLE

   Copy

   $ ssh dokku-server traefik:set --global letsencrypt-email username@example.com

   Explain Code

   Powered by Vultr AgentBeta

   Replace username@example.com with your email address.

4. Set the domain for your application.

   CONSOLE

   Copy

   $ ssh dokku-server domains:set ruby-getting-started dokku.example.com

   Explain Code

   Powered by Vultr AgentBeta

   Replace dokku.example.com with your registered domain.

5. Start the Traefik proxy.

   CONSOLE

   Copy

   $ ssh dokku-server traefik:start

   Explain Code

   Powered by Vultr AgentBeta

6. Rebuild the application to inject Traefik labels into the app containers.

   CONSOLE

   Copy

   $ ssh dokku-server ps:rebuild ruby-getting-started

   Explain Code

   Powered by Vultr AgentBeta

7. Open your web browser and navigate to your application domain using HTTPS.

   https://dokku.example.com

   Replace dokku.example.com with your registered domain.

   

   The browser displays a padlock icon, confirming a secure TLS connection. Traefik successfully obtained and installed the Let's Encrypt certificate for the domain.

Conclusion

You have successfully deployed Dokku as a containerized Platform-as-a-Service using Docker Compose. The setup provides Git-based deployments, SSH authentication, environment variable management, and automatic SSL/TLS certificates through Traefik. For more information, visit the official Dokku documentation.