Dokku Mini PaaS Installation

Dokku is a lightweight, open-source Platform-as-a-Service that delivers Heroku-like git-push deployments on your own Linux server. Supporting both buildpacks and Dockerfiles, Dokku's plugin system extends it with databases, Redis, SSL management, and more — all on a single server you control.

Prerequisites

  • Ubuntu 20.04+, Debian 11+, or CentOS 7+ (fresh install recommended)
  • Minimum 1 GB RAM (2 GB recommended for multiple apps)
  • A domain name with DNS pointed to your server
  • Root or sudo access
  • SSH key pair on your local machine

Installing Dokku

# Download and run the Dokku installer
wget -NP . https://dokku.com/install/v0.34.6/bootstrap.sh
sudo DOKKU_TAG=v0.34.6 bash bootstrap.sh

# The installer will:
# 1. Install dependencies (nginx, git, docker)
# 2. Install Dokku
# 3. Create the dokku system user

# Verify installation
dokku version

Post-Install: Add SSH Key

# On your LOCAL machine, display your public key
cat ~/.ssh/id_ed25519.pub

# On the SERVER, add the key to Dokku
echo "your-public-key-content" | sudo dokku ssh-keys:add admin

# Or pass via file
sudo dokku ssh-keys:add admin < ~/.ssh/id_ed25519.pub

# Verify key was added
sudo dokku ssh-keys:list

Initial Configuration

# Set your server's hostname/domain
sudo dokku domains:set-global yourdomain.com

# Verify configuration
dokku config
sudo cat /home/dokku/VHOST

Access the Dokku admin interface via SSH from any machine with the key added:

# All Dokku commands run via SSH from local machine
ssh -t dokku@your-server-ip help

Git-Push Deployment

Create an app and deploy via git push — same as Heroku:

# On the SERVER: create the app
sudo dokku apps:create myapp

# On your LOCAL machine: add the Dokku remote
cd /path/to/your/project
git remote add dokku dokku@your-server-ip:myapp

# Deploy by pushing to Dokku
git push dokku main

# Deploy a different branch or tag
git push dokku mybranch:main

Dokku output during deployment:

Enumerating objects: 245, done.
...
-----> Building myapp...
-----> Node.js app detected
-----> Installing dependencies
...
-----> Releasing myapp
=====> Application deployed:
       http://myapp.yourdomain.com

Managing Deployments

# List all apps
dokku apps:list

# View deployment logs
dokku logs myapp
dokku logs myapp --tail

# Run one-off commands in the app container
dokku run myapp node -e "console.log(process.version)"
dokku run myapp bash

# Restart an app
dokku ps:restart myapp

# Stop/start an app
dokku ps:stop myapp
dokku ps:start myapp

Buildpack and Dockerfile Support

Buildpacks

Dokku uses Heroku buildpacks by default. Language is auto-detected:

# Auto-detected buildpacks: Node.js, Python, Ruby, Go, PHP, Java, etc.
# Check which buildpack was used
dokku buildpacks:report myapp

# Set a specific buildpack version
dokku buildpacks:set myapp https://github.com/heroku/heroku-buildpack-nodejs.git#v240

# Use multiple buildpacks
dokku buildpacks:add myapp https://github.com/heroku/heroku-buildpack-ruby.git
dokku buildpacks:list myapp

Dockerfile Deployments

# Dokku auto-uses Dockerfile if present at repository root
# Customize the Dockerfile path:
dokku builder-dockerfile:set myapp dockerfile-path ./docker/Dockerfile.prod

# Force Docker image builder (skip buildpacks)
dokku builder:set myapp selected dockerfile

Example Dockerfile for a Python app:

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 5000
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:application"]

Procfile

# Procfile - define process types
web: node dist/server.js
worker: node dist/worker.js

# Scale process types
dokku ps:scale myapp web=2 worker=1
dokku ps:report myapp

Plugin System and Database Provisioning

Dokku's plugin system adds databases, queues, and other services:

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

# Create a PostgreSQL database
dokku postgres:create myapp-db

# Link database to app (injects DATABASE_URL env var)
dokku postgres:link myapp-db myapp

# Connect to the database interactively
dokku postgres:connect myapp-db

# Export/import database
dokku postgres:export myapp-db > backup.dump
dokku postgres:import myapp-db < backup.dump

Other Useful Plugins

# Redis
sudo dokku plugin:install https://github.com/dokku/dokku-redis.git redis
dokku redis:create myapp-cache
dokku redis:link myapp-cache myapp

# MySQL/MariaDB
sudo dokku plugin:install https://github.com/dokku/dokku-mysql.git mysql
dokku mysql:create myapp-mysql
dokku mysql:link myapp-mysql myapp

# MongoDB
sudo dokku plugin:install https://github.com/dokku/dokku-mongo.git mongo
dokku mongo:create myapp-mongo
dokku mongo:link myapp-mongo myapp

# List installed plugins
dokku plugin:list

Environment Variables

# Set environment variables
dokku config:set myapp NODE_ENV=production SECRET_KEY=mysecret

# Set multiple variables from file
dokku config:set myapp $(cat .env | xargs)

# View all env vars
dokku config myapp

# Remove a variable
dokku config:unset myapp SECRET_KEY

Domain Management

# Add a custom domain to an app
dokku domains:add myapp myapp.com
dokku domains:add myapp www.myapp.com

# Remove a domain
dokku domains:remove myapp www.myapp.com

# List domains for an app
dokku domains:report myapp

# Set global domain (auto-creates subdomains)
dokku domains:set-global yourdomain.com
# myapp → myapp.yourdomain.com automatically

SSL with Let's Encrypt

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

# Set your email for Let's Encrypt notifications
dokku letsencrypt:set --global email [email protected]

# Enable SSL for an app
dokku letsencrypt:enable myapp

# Enable for all apps at once
dokku letsencrypt:enable --all

# Set up auto-renewal (runs daily cron)
dokku letsencrypt:cron-job --add

# Check certificate status
dokku letsencrypt:ls

# Manually renew
dokku letsencrypt:auto-renew myapp

Troubleshooting

Push rejected - permission denied:

# Verify SSH key is registered
dokku ssh-keys:list

# Test SSH connection
ssh -v dokku@your-server-ip help

# Check SSH config
cat /etc/ssh/sshd_config | grep -E "AllowUsers|DenyUsers"

Build fails - out of memory:

# Check available memory
free -h

# Add swap space
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

App crashes after deployment:

# Check app logs for startup errors
dokku logs myapp --tail

# Inspect container
dokku ps:inspect myapp

# Check if port is configured correctly
# Dokku expects app to listen on $PORT env variable
dokku config myapp | grep PORT

Database link not working:

# Verify link exists
dokku postgres:list
dokku postgres:info myapp-db

# Re-link database
dokku postgres:unlink myapp-db myapp
dokku postgres:link myapp-db myapp

Conclusion

Dokku delivers a true git-push deployment workflow on your own server with minimal overhead. Its plugin ecosystem handles everything from PostgreSQL provisioning to Let's Encrypt SSL, while buildpack auto-detection makes it a drop-in replacement for Heroku with no application code changes. Running on a single $5-20/month VPS, Dokku is one of the most cost-effective PaaS solutions available for small-to-medium application portfolios.