Instalación de Dokku Mini PaaS

Dokku es un PaaS minimalista de código abierto que replica la experiencia de Heroku en tu propio servidor, permitiendo desplegar aplicaciones con un simple git push y gestionando automáticamente buildpacks, contenedores Docker, dominios y certificados SSL. Con apenas 100 MB de memoria base y soporte para decenas de plugins de la comunidad, Dokku es la opción ideal para servidores con recursos limitados. Esta guía cubre la instalación, configuración y uso de Dokku en Linux.

Requisitos Previos

  • Ubuntu 20.04/22.04 o Debian 11/12
  • Mínimo 512 MB RAM (recomendado 1 GB+)
  • 10 GB de espacio en disco
  • Acceso root
  • Dominio con registro A apuntando al servidor
  • SSH configurado (clave pública disponible)

Instalación de Dokku

# Descargar e instalar Dokku (versión estable más reciente)
wget -NP . https://dokku.com/install/v0.34.4/bootstrap.sh
sudo DOKKU_TAG=v0.34.4 bash bootstrap.sh

# El instalador:
# 1. Instala Docker
# 2. Instala Nginx como proxy inverso
# 3. Instala Dokku y sus dependencias
# 4. Configura el usuario 'dokku'

# Verificar la instalación
dokku version

Instalación silenciosa para automatización

# Variables de configuración antes de instalar
export DOKKU_TAG=v0.34.4
export DOKKU_HOSTNAME=apps.tudominio.com

# Instalar sin interfaz web
wget -NP . https://dokku.com/install/v0.34.4/bootstrap.sh
sudo bash bootstrap.sh

# Configurar dominio y clave SSH de administrador
dokku domains:set-global apps.tudominio.com
cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin

Configuración Inicial

Si tienes acceso web al servidor, accede a http://IP_SERVIDOR después de la instalación para el asistente de configuración. También puedes configurarlo directamente por SSH:

# Establecer el hostname global de Dokku
dokku domains:set-global apps.tudominio.com

# Agregar tu clave SSH pública (necesaria para git push)
# En tu máquina local:
cat ~/.ssh/id_ed25519.pub

# En el servidor (como root):
echo "TU_CLAVE_PUBLICA_AQUI" | dokku ssh-keys:add mi-usuario

# Verificar que la clave se agregó
dokku ssh-keys:list

# Probar la conexión desde tu máquina local
ssh -t [email protected]
# Debe mostrar: !     Welcome to Dokku

Configuración de red y firewall

# Asegurarse de que los puertos necesarios están abiertos
ufw allow 22/tcp   # SSH
ufw allow 80/tcp   # HTTP
ufw allow 443/tcp  # HTTPS
ufw enable

Despliegue con Git Push

Dokku replica el flujo de Heroku: creas una aplicación en el servidor y haces push desde tu repositorio local.

Crear y desplegar una aplicación

# En el servidor: crear la aplicación
dokku apps:create mi-aplicacion

# En tu máquina local: agregar el remote de Dokku
git remote add dokku [email protected]:mi-aplicacion

# Desplegar con git push
git push dokku main

# Si tu rama local tiene otro nombre:
git push dokku tu-rama:main

Configurar variables de entorno

# Establecer variables de entorno en el servidor
dokku config:set mi-aplicacion NODE_ENV=production
dokku config:set mi-aplicacion DATABASE_URL=postgresql://usuario:pass@localhost/midb
dokku config:set mi-aplicacion SECRET_KEY=mi-clave-secreta

# Establecer múltiples variables a la vez
dokku config:set mi-aplicacion \
    REDIS_URL=redis://localhost:6379 \
    SMTP_HOST=smtp.ejemplo.com \
    SMTP_PORT=587

# Ver todas las variables de entorno de una aplicación
dokku config:show mi-aplicacion

# Eliminar una variable
dokku config:unset mi-aplicacion VARIABLE_TEMPORAL

Gestión básica de aplicaciones

# Listar todas las aplicaciones
dokku apps:list

# Ver información de una aplicación
dokku apps:report mi-aplicacion

# Reiniciar una aplicación
dokku ps:restart mi-aplicacion

# Detener una aplicación
dokku ps:stop mi-aplicacion

# Ver los logs en tiempo real
dokku logs mi-aplicacion -t

# Ver los últimos 100 líneas de logs
dokku logs mi-aplicacion --num 100

# Ejecutar un comando en el contenedor de la aplicación
dokku run mi-aplicacion bash
dokku run mi-aplicacion npm run migrate

Escalar procesos

# Escalar el proceso web a 2 instancias
dokku ps:scale mi-aplicacion web=2

# Escalar múltiples tipos de proceso (según Procfile)
dokku ps:scale mi-aplicacion web=2 worker=1

# Ver el estado de los procesos
dokku ps:report mi-aplicacion

Buildpacks y Dockerfile

Buildpacks automáticos

Dokku detecta automáticamente el tipo de aplicación y usa el buildpack apropiado:

  • Node.js: detecta package.json
  • Python: detecta requirements.txt o Pipfile
  • Ruby: detecta Gemfile
  • Go: detecta go.mod
  • PHP: detecta composer.json
  • Java: detecta pom.xml
# Ver el buildpack detectado o configurado
dokku buildpacks:report mi-aplicacion

# Especificar un buildpack manualmente
dokku buildpacks:set mi-aplicacion https://github.com/heroku/heroku-buildpack-nodejs

# Agregar múltiples buildpacks (en orden)
dokku buildpacks:add mi-aplicacion https://github.com/heroku/heroku-buildpack-nodejs
dokku buildpacks:add mi-aplicacion https://github.com/heroku/heroku-buildpack-python

# Usar la versión específica de Node.js (en package.json)

// package.json - especificar versión de Node.js para el buildpack
{
  "name": "mi-aplicacion",
  "engines": {
    "node": "20.x",
    "npm": "10.x"
  }
}

Despliegue con Dockerfile

Si el repositorio tiene un Dockerfile, Dokku lo usa automáticamente:

# Dockerfile de ejemplo para aplicación Python/Flask
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:app"]

# Dokku detecta Dockerfile automáticamente
# Si quieres forzar el uso de Dockerfile sobre buildpacks:
dokku config:set mi-aplicacion DOKKU_DOCKERFILE_PORT=5000

Procfile

# Procfile - define los procesos de la aplicación
web: gunicorn app:app --workers 2
worker: celery -A tasks worker --loglevel=info
scheduler: celery -A tasks beat --loglevel=info

Sistema de Plugins

Dokku tiene un sistema de plugins rico para agregar funcionalidades:

Plugin de bases de datos

# Instalar el plugin de PostgreSQL
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres

# Crear una base de datos
dokku postgres:create mi-base-de-datos

# Enlazar la BD a la aplicación (configura DATABASE_URL automáticamente)
dokku postgres:link mi-base-de-datos mi-aplicacion

# Ver la URL de conexión
dokku postgres:info mi-base-de-datos

# Conectarse a la BD interactivamente
dokku postgres:connect mi-base-de-datos

# Exportar un backup
dokku postgres:export mi-base-de-datos > backup.dump

# Importar datos
dokku postgres:import mi-base-de-datos < backup.dump

# Plugin de Redis
sudo dokku plugin:install https://github.com/dokku/dokku-redis.git redis
dokku redis:create mi-cache
dokku redis:link mi-cache mi-aplicacion

# Plugin de MySQL
sudo dokku plugin:install https://github.com/dokku/dokku-mysql.git mysql
dokku mysql:create mi-mysql
dokku mysql:link mi-mysql mi-aplicacion

# Plugin de MongoDB
sudo dokku plugin:install https://github.com/dokku/dokku-mongo.git mongo
dokku mongo:create mi-mongo
dokku mongo:link mi-mongo mi-aplicacion

Plugin de Let's Encrypt (SSL)

# Instalar el plugin de Let's Encrypt
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

# Configurar el email para notificaciones de certificados
dokku letsencrypt:set --global email [email protected]

# Habilitar SSL para una aplicación
dokku letsencrypt:enable mi-aplicacion

# Renovación automática (agregar al crontab del servidor)
dokku letsencrypt:cron-job --add

# Habilitar SSL para todas las aplicaciones a la vez
dokku letsencrypt:enable --all

Gestión de Dominios y SSL

# Agregar un dominio personalizado a una aplicación
dokku domains:add mi-aplicacion app.tuempresa.com

# Ver los dominios configurados
dokku domains:report mi-aplicacion

# Eliminar un dominio
dokku domains:remove mi-aplicacion subdominio.tudominio.com

# Habilitar SSL con Let's Encrypt
dokku letsencrypt:enable mi-aplicacion

# Ver estado del certificado
dokku letsencrypt:ls

# Renovar certificado manualmente
dokku letsencrypt:auto-renew mi-aplicacion

Solución de Problemas

Git push rechazado

# Verificar que la clave SSH está configurada
dokku ssh-keys:list

# Verificar conectividad SSH
ssh -v [email protected]

# Verificar que la aplicación existe
dokku apps:list | grep mi-aplicacion

La aplicación no arranca

# Ver logs del último despliegue
dokku logs mi-aplicacion --tail=50

# Ver el estado del proceso
dokku ps:report mi-aplicacion

# Ver eventos del contenedor Docker
docker events --filter container=mi-aplicacion

Puerto de la aplicación incorrecto

# Dokku detecta el puerto automáticamente, pero puedes especificarlo
dokku ports:add mi-aplicacion http:80:3000  # Mapear puerto 80 al 3000 interno
dokku ports:report mi-aplicacion

Base de datos no conecta

# Verificar el enlace entre app y base de datos
dokku postgres:info mi-base-de-datos
dokku config:show mi-aplicacion | grep DATABASE

# Re-enlazar la base de datos
dokku postgres:unlink mi-base-de-datos mi-aplicacion
dokku postgres:link mi-base-de-datos mi-aplicacion

Conclusión

Dokku ofrece la experiencia de despliegue más similar a Heroku que puedes tener en tu propio servidor, con la ventaja de ser extremadamente ligero y extensible. Su ecosistema de plugins cubre las necesidades más comunes (bases de datos, SSL, monitorización, almacenamiento) y el flujo de git push hace que el despliegue sea intuitivo para cualquier desarrollador acostumbrado a trabajar con Git. Es la opción perfecta para hospedar múltiples aplicaciones pequeñas o medianas en un único VPS.