Running Dokku Locally

by Alexis Hope,

Dokku is a self-hosted PaaS (Platform as a Service) that gives you a Heroku-like deployment experience on your own Linux box. A single wget command installs all the necessary tooling. From there, you configure SSH key access, set a git remote on your project, and git push to deploy — Dokku handles the build process, waits for a health check, and performs a zero-downtime swap of the running instance.

It operates on a single host, so scaling is vertical rather than horizontal. In practice this takes you further than you might expect — a modest VPS is capable of running multiple applications simultaneously, and cloud providers can scale resources substantially before Kubernetes becomes a meaningful consideration. If you do need to move beyond a single host, the Dockerfile-based build process keeps your containers portable to GCP, AWS, or wherever you land.

Running Locally

Dokku publishes an official Docker image to DockerHub, which makes local testing straightforward. The official documentation covers the basics, but a few steps needed to get an app deploying locally are missing. Here is the complete sequence.

1. Pull the Dokku image

docker pull dokku/dokku:latest

2. Run the container

docker run \
  --env DOKKU_HOSTNAME=dokku.me \
  --name dokku \
  --publish 3022:22 \
  --publish 8080:80 \
  --publish 8443:443 \
  --volume /var/lib/dokku:/mnt/dokku \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  dokku/dokku:latest

This maps the container’s SSH port to 3022 on your local machine and binds the hostname dokku.me. The next two steps configure your local machine to resolve and connect to that hostname correctly.

3. Add dokku.me to your hosts file

The hosts file is checked before DNS, making it the right place to map a local domain to the loopback address.

sudo vim /etc/hosts
# Linux/macOS: /etc/hosts
# Windows: C:\Windows\System32\drivers\etc\hosts

Add:

127.0.0.1 dokku.me

4. Configure the SSH port

Git pushes to dokku.me will use the default SSH port (22) unless told otherwise. Add a host entry to your SSH config to redirect to the mapped port:

vim ~/.ssh/config

Host dokku.me
  AddKeysToAgent yes
  IdentityFile ~/.ssh/id_rsa
  Port 3022
  User dokku

5. Copy your public SSH key

# macOS
cat ~/.ssh/id_rsa.pub | pbcopy

# Linux
cat ~/.ssh/id_rsa.pub | xclip -selection clipboard

6. Register your SSH key with Dokku

Exec into the running container and add your key:

docker exec -it dokku bash

Then inside the container:

echo "YOUR_PUBLIC_KEY" | dokku ssh-keys:add devmachine

Or pipe it directly without entering the container:

cat ~/.ssh/id_rsa.pub | docker exec -i dokku dokku ssh-keys:add devmachine

7. Create your app

Still inside the container (or via docker exec -it dokku bash):

dokku apps:create my-app

8. Add the git remote

Back on your local machine, add a remote pointing to the Dokku server. The remote URL format is dokku@<host>:<app-name> — the SSH config you set in step 4 handles the port mapping transparently:

git remote add dokku [email protected]:my-app

9. Deploy

git push dokku main

Dokku will detect your Dockerfile, build the image, run a health check, and swap the container with zero downtime.

Notes

  • The --volume /var/run/docker.sock:/var/run/docker.sock mount gives the Dokku container access to the host Docker daemon. This is necessary for Dokku to build and run containers, but means the Dokku container has elevated privileges — appropriate for local development, worth being deliberate about in production.
  • If you need to persist data between container restarts, configure a Dokku storage mount with dokku storage:mount.
  • Dokku supports environment variables via dokku config:set my-app KEY=value, which is the correct way to handle secrets rather than baking them into the image.
Tags: