---

name: dokku
description: >-
Deploy apps with Dokku — self-hosted Heroku alternative on any VPS. Use when: self-hosting
web apps without Kubernetes, setting up git-push deployments, running PaaS on your own server.
license: Apache-2.0
compatibility: "Ubuntu 22.04/20.04 or Debian 11/12 VPS"
metadata:
author: terminal-skills
version: "1.0.0"
category: devops
tags: [dokku, self-hosted, paas, heroku-alternative, deployment]
use-cases:
- "Deploy a Node.js/Python/Ruby app to a DigitalOcean droplet with git push"
- "Set up Postgres and Redis for a self-hosted SaaS app"
- "Add custom domain with automatic SSL via Let's Encrypt"
agents: [claude-code, openai-codex, gemini-cli, cursor]

Dokku

Overview

Dokku is an open-source PaaS that turns any VPS into a Heroku-like platform. Deploy apps with git push, manage databases with plugins, and get automatic SSL — all on infrastructure you control.

Install on VPS

# Ubuntu 22.04 (run as root)
wget -NP . https://dokku.com/install/v0.35.0/bootstrap.sh
sudo DOKKU_TAG=v0.35.0 bash bootstrap.sh

# Set up SSH key and hostname
cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin
dokku domains:set-global yourdomain.com

Deploy an App

# On your VPS: create app
dokku apps:create myapp

# On your local machine: add remote and push
git remote add dokku dokku@your-server.com:myapp
git push dokku main

Dokku auto-detects buildpacks (Node.js, Python, Ruby, Go, etc.) or uses your Dockerfile.

Procfile

web: node server.js
worker: node worker.js
release: npm run migrate

Environment Variables

# Set config vars
dokku config:set myapp NODE_ENV=production SECRET_KEY=abc123

# View all vars
dokku config:show myapp

# Import from .env file
cat .env | xargs dokku config:set myapp

PostgreSQL Plugin

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

# Create database and link to app
dokku postgres:create myapp-db
dokku postgres:link myapp-db myapp
# Sets DATABASE_URL automatically

Redis Plugin

sudo dokku plugin:install https://github.com/dokku/dokku-redis.git redis
dokku redis:create myapp-redis
dokku redis:link myapp-redis myapp
# Sets REDIS_URL automatically

Custom Domains + SSL

# Add domain
dokku domains:add myapp myapp.com www.myapp.com

# Install Let's Encrypt plugin
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
dokku config:set --global DOKKU_LETSENCRYPT_EMAIL=you@email.com

# Enable SSL
dokku letsencrypt:enable myapp
dokku letsencrypt:cron-job --add  # auto-renew

Zero-Downtime Deploys

# Enable checks (waits for app to respond before switching)
dokku checks:enable myapp

# Or use rolling restarts
dokku ps:set-restart-policy myapp always

Scaling

# Scale web processes
dokku ps:scale myapp web=2 worker=1

# View process status
dokku ps:report myapp

Persistent Storage

# Mount a directory (for uploads, etc.)
dokku storage:mount myapp /var/lib/dokku/data/storage/myapp:/app/uploads

Useful Commands

dokku apps:list           # List all apps
dokku logs myapp -t       # Tail logs
dokku run myapp bash      # Open shell in container
dokku ps:restart myapp    # Restart app
dokku backup              # Backup all data

Dockerfile Deploy

Dokku auto-uses your Dockerfile if present. Expose a port and Dokku routes traffic to it:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Multi-Server Setup

# Add additional nodes (Dokku Scheduler)
dokku scheduler:set myapp selected docker-local

# Or use Kubernetes scheduler plugin for K8s deployments
sudo dokku plugin:install https://github.com/dokku/dokku-scheduler-kubernetes.git