How to install Dokku on a VPS

Prerequisites

• Ubuntu 22.04 or 24.04 VPS with a public IP address
• At least 1 GB RAM (add 1 GB swap for smaller VMs)
• SSH root access to the VPS
• A domain with a wildcard A record pointing to the VPS IP (e.g. *.apps.example.com)
• Git and an SSH key pair on your local machine

Dokku is not a Docker container. It is an apt-managed PaaS that installs Docker Engine as a dependency. Start with a clean server — do not pre-install Docker, nginx, or any container tooling. Dokku manages all of these itself.

Step 1: Connect to the server

Log in and update the system packages:

ssh root@SERVER_IP
apt update && apt upgrade -y
hostnamectl set-hostname dokku.example.com

Verify the hostname resolves correctly and that ports 80 and 443 are free:

ss -ltnp

Reboot if the kernel was updated. After reboot, reconnect and proceed.

Step 2: Install Dokku via the bootstrap script

Download the official bootstrap script for a specific version and run it. Do not install Docker manually — the bootstrap script handles that.

wget -NP . https://dokku.com/install/v0.38.25/bootstrap.sh
sudo DOKKU_TAG=v0.38.25 bash bootstrap.sh

During installation, the script shows a blue debconf configuration screen. It asks for:

1. Global domain — enter apps.example.com (or the domain you set up)
2. SSH key — leave this blank. You will register your key in the next step.

Use the Tab key to move between fields and Enter to confirm. If you miss the prompt, run sudo dpkg-reconfigure dokku afterward.

After the script finishes, verify everything is working:

dokku version
docker version
sudo systemctl status dokku

Dokku bundles its own nginx instance. Ports 80 and 443 are now managed by Dokku.

Step 3: Register SSH key and set domain

This is the most critical step. Without a registered SSH key, Dokku rejects all git push attempts.

cat ~/.ssh/authorized_keys | sudo dokku ssh-keys:add admin

This registers the public key from the root user's authorized keys (which contains the key you used to SSH in). Replace admin with any label you prefer.

Set the global domain so every app gets a hostname automatically:

sudo dokku domains:set-global apps.example.com

Confirm the key and domain are registered:

dokku ssh-keys:list
dokku domains:report --global

Step 4: Deploy your first app

Create an app on the server:

dokku apps:create hello

From your local machine, add the Dokku remote and push:

git remote add dokku [email protected]:hello
git push dokku main

Dokku detects the project type (Dockerfile or buildpack), builds it, runs the container, and configures nginx routing automatically. The app is now reachable at http://hello.apps.example.com.

Check the app status:

dokku ps:report hello
dokku logs hello -t

Step 5: SSL with Let's Encrypt

Dokku does not include HTTPS out of the box. Install the official Let's Encrypt plugin:

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

Configure the plugin with your email (for renewal notices):

dokku config:set --global [email protected]

Enable the certificate for your app:

dokku letsencrypt:enable hello

After this, https://hello.apps.example.com serves HTTPS. Dokku handles automatic renewal via a cron job installed by the plugin.

Verify renewal is scheduled:

dokku letsencrypt:cron-job --add

Maintenance

Update Dokku and all plugins via apt. Do not update only dokku without also updating the system Docker, which the same apt source manages:

sudo apt update && sudo apt upgrade -y

Back up persistent plugin data (e.g. databases) to a separate location before any major upgrade. Monitor disk usage — old build images and Docker layers accumulate over time. Clean unused Docker resources periodically:

docker system prune -af

Reboot the server after a kernel update and confirm Dokku starts the proxy and all apps:

dokku proxy:report
dokku ps:rebuildall

When a deploy fails, inspect the logs and the process report rather than removing volumes. Roll back with dokku ps:rebuild on a previous release.