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

   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

3. Create a .env file.

   console Copy

   $ nano .env
   

   Explain Code

4. Add the following environment variables:

   ini Copy

   DOKKU_HOSTNAME=dokku.example.com
   DOKKU_VERSION=0.37.6
   

   Explain Code

   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

2. Apply the new group membership.

   console Copy

   $ newgrp docker
   

   Explain Code

3. Create and edit a Docker Compose manifest file.

   console Copy

   $ nano docker-compose.yml
   

   Explain Code

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

   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

6. Verify the service's status.

   console Copy

   $ docker compose ps
   

   Explain Code

   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
   • 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

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
   • 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

   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

2. Add the following content:

   ini Copy

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

   Explain Code

   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

   The Dokku command list confirms SSH access is configured correctly.

4. Verify the Dokku version.

   console Copy

   $ ssh dokku-server version
   

   Explain Code

   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

   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

   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

4. Navigate to the application directory.

   console Copy

   $ cd ruby-getting-started
   

   Explain Code

5. Add the Dokku Git remote.

   console Copy

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

   Explain Code

   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

   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

   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

3. View all configured environment variables.

   console Copy

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

   Explain Code

   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

   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

   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

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

   console Copy

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

   Explain Code

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

   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

   Replace dokku.example.com with your registered domain.

5. Start the Traefik proxy.

   console Copy

   $ ssh dokku-server traefik:start
   

   Explain Code

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

   console Copy

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

   Explain Code

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.