Dokku Deployment Guide: A Comprehensive Approach

Introduction
Basic Dokku Deployment
SSH Configuration
Docker Firewall Setup
Common Workflows (TLDR Style)
Security Considerations
Troubleshooting Guide
Conclusion

1. Introduction

Dokku provides a lightweight, yet powerful Platform as a Service (PaaS) solution that transforms a simple server into a flexible deployment platform. This guide documents practical approaches to deploying applications with Dokku, covering everything from basic setup to advanced configuration.

2. Basic Dokku Deployment

2.1 Prerequisites

Dokku installed on your server
SSH access to your Dokku server
Git repository with your application

2.2 Creating and Deploying an Application

# Create a new Dokku application
dokku apps:create frontend

# Add Dokku remote to your repository
git remote add dokku dokku@your-dokku-server:frontend

# Deploy your application
git push dokku master

2.3 SSL Configuration

# Configure SSL with Let's Encrypt
dokku letsencrypt:set frontend email your-email@domain.com
dokku letsencrypt:enable frontend

3. SSH Configuration

3.1 Standard Port Configuration

# Add remote with default SSH port
git remote add dokku dokku@your-dokku-server:frontend

3.2 Custom Port Configuration

Using SSH config file (~/.ssh/config):

Host dokku-server
    HostName your-server-ip-or-domain
    Port 2222
    User dokku
    IdentityFile ~/.ssh/your_private_key

Alternative SSH URL format:

git remote add dokku ssh://dokku@your-server-ip-or-domain:2222/frontend

4. Docker Firewall Setup

4.1 Basic UFW Configuration

# Essential port access
ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 2222/tcp  # If using custom SSH port

4.2 Docker Network Rules

# Docker communication
ufw allow in on docker0
ufw allow out on docker0

# Docker subnet access
ufw allow from 172.16.0.0/12
ufw allow from 10.0.0.0/8
ufw allow from 192.168.0.0/16

5. Common Workflows (TLDR Style)

5.1 New Application Deployment

# Create and configure app
dokku apps:create myapp
dokku domains:add myapp myapp.example.com
dokku letsencrypt:enable myapp

# Deploy application
git push dokku main:master

5.2 Configuration Updates

# Set environment variables
dokku config:set myapp KEY=value

# Scale application
dokku ps:scale myapp web=2

6. Security Considerations

6.1 Docker Configuration

Edit /etc/docker/daemon.json:

{
  "iptables": false,
  "default-address-pools": [
    {
      "base": "172.17.0.0/16",
      "size": 24
    }
  ]
}

6.2 Service Configuration

Create /etc/systemd/system/docker.service.d/override.conf:

[Service]
ExecStartPost=/usr/sbin/iptables -P FORWARD ACCEPT

7. Troubleshooting Guide

7.1 Connectivity Issues

# Test container connectivity
docker run --rm alpine ping -c 4 google.com

# Check Docker networks
docker network ls
docker network inspect bridge

# Monitor connections
sudo netstat -tulpn

7.2 Common Problems and Solutions

Permission Denied
- Verify SSH key installation
- Check user permissions
Deploy Failures
- Review application logs: dokku logs myapp
- Check build logs: dokku events myapp
Network Issues
- Verify firewall rules
- Check Docker network configuration
- Inspect container networking

8. Conclusion

Dokku provides a robust platform for application deployment, combining the simplicity of Heroku-like workflows with the flexibility of self-hosted infrastructure. By following this guide's practices and understanding the various components involved, you can create a reliable and secure deployment pipeline for your applications.

Remember to:

Regularly update Dokku and its plugins
Monitor system resources and logs
Maintain proper backup procedures
Keep security configurations up to date
Document any custom configurations for your team

Table of Contents