Dokku es un PaaS ligero de código abierto que reproduce el flujo de trabajo de Heroku en tu propio servidor: haces git push, Dokku detecta el lenguaje, construye una imagen Docker y la publica detrás de Nginx. En este tutorial instalarás Dokku en Ubuntu 24.04, desplegarás una aplicación Node.js de ejemplo, le conectarás una base de datos PostgreSQL y la servirás por HTTPS con Let's Encrypt.

Requisitos previos

Para seguir esta guía necesitas:

  • Un servidor con Ubuntu 24.04 LTS recién instalado, por ejemplo un VPS de CubePath, con al menos 1 GB de RAM y 20 GB de disco. Las compilaciones con buildpacks consumen memoria; con menos RAM añade swap.
  • Un usuario no root con privilegios sudo al que te conectas por SSH con una clave pública (esa clave se usará también para git push).
  • Un dominio en el que puedas crear registros DNS. En esta guía se usa dokku.tudominio.com; sustituye tudominio.com por tu dominio e IP_DEL_SERVIDOR por la IP pública del servidor.
  • Git instalado en tu equipo local.

Paso 1: Crear los registros DNS

Dokku publica cada aplicación como un subdominio del dominio global, por ejemplo mi-app.dokku.tudominio.com. Crea dos registros en tu proveedor DNS:

TipoNombreValor
Adokku.tudominio.comIP_DEL_SERVIDOR
A*.dokku.tudominio.comIP_DEL_SERVIDOR

Comprueba que un subdominio cualquiera resuelve al servidor:

dig +short prueba.dokku.tudominio.com

203.0.113.10

Paso 2: Configurar el firewall

Dokku solo necesita SSH (también para recibir los git push) y los puertos web:

sudo ufw allow OpenSSH
sudo ufw allow 80,443/tcp
sudo ufw enable

Comprueba el resultado:

sudo ufw status

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80,443/tcp                 ALLOW       Anywhere
...

Paso 3: Instalar Dokku

Dokku se instala con un script de arranque que añade los repositorios de Docker y Dokku, e instala Docker, Nginx y Dokku. Obtén el número de la última versión estable desde GitHub:

DOKKU_TAG=$(curl -fsSL https://api.github.com/repos/dokku/dokku/releases/latest | grep -oP '"tag_name":\s*"\K[^"]+')
echo "$DOKKU_TAG"

v0.36.7

Tu versión puede ser más reciente. Descarga el script de esa versión y revísalo antes de ejecutarlo:

wget -NP . "https://dokku.com/install/${DOKKU_TAG}/bootstrap.sh"
less bootstrap.sh

Ejecuta la instalación, que tarda unos minutos:

sudo DOKKU_TAG="$DOKKU_TAG" bash bootstrap.sh

Verifica que Dokku está instalado:

sudo dokku version

dokku version 0.36.7

Paso 4: Configurar claves SSH y dominio global

Para poder hacer git push, Dokku necesita tu clave pública. Como ya te conectas al servidor con ella, puedes añadir las claves autorizadas de tu usuario:

cat ~/.ssh/authorized_keys | sudo dokku ssh-keys:add admin

Comprueba que la clave se ha registrado. La salida muestra la huella SHA256 de cada clave junto al nombre admin:

sudo dokku ssh-keys:list

Define el dominio global. Cada aplicación nueva recibirá un subdominio de este dominio:

sudo dokku domains:set-global dokku.tudominio.com

Por defecto, Dokku solo despliega lo que se envía a la rama master. Si trabajas con main, cámbialo para todas las aplicaciones:

sudo dokku git:set --global deploy-branch main

Desde tu equipo local, comprueba que puedes hablar con Dokku por SSH:

ssh [email protected] version

dokku version 0.36.7

Paso 5: Desplegar una aplicación con git push

Crea la aplicación en el servidor:

sudo dokku apps:create hola-node

En tu equipo local, clona la aplicación de ejemplo de Node.js de Heroku y añade Dokku como remoto de Git:

git clone https://github.com/heroku/node-js-getting-started.git
cd node-js-getting-started
git remote add dokku [email protected]:hola-node

Despliega con git push:

git push dokku main

Dokku detecta el package.json, usa el buildpack de Node.js, construye la imagen y arranca el contenedor. Al final verás la URL de la aplicación:

=====> Application deployed:
       http://hola-node.dokku.tudominio.com

Compruébalo:

curl -sI http://hola-node.dokku.tudominio.com | head -n 1

HTTP/1.1 200 OK

Si tu repositorio incluye un Dockerfile en la raíz, Dokku lo usa en lugar de un buildpack. Los tipos de proceso (web, worker, etc.) se leen del Procfile si existe.

Paso 6: Gestionar la aplicación

Las variables de entorno se definen con config:set. Dokku reinicia la aplicación para aplicar el cambio:

sudo dokku config:set hola-node NODE_ENV=production
sudo dokku config:show hola-node

Consulta los logs en tiempo real con -t (sal con Ctrl+C):

sudo dokku logs hola-node -t

Para escalar, indica el número de contenedores por tipo de proceso definido en el Procfile:

sudo dokku ps:scale hola-node web=2
sudo dokku ps:report hola-node

Puedes ejecutar las mismas órdenes desde tu equipo sin entrar en el servidor, por ejemplo ssh [email protected] logs hola-node.

Paso 7: Añadir una base de datos PostgreSQL

Las bases de datos se añaden con plugins oficiales. Instala el de PostgreSQL:

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

Crea un servicio de base de datos y enlázalo a la aplicación:

sudo dokku postgres:create hola-db
sudo dokku postgres:link hola-db hola-node

El enlace define la variable DATABASE_URL en la aplicación y la reinicia. Compruébalo:

sudo dokku config:get hola-node DATABASE_URL

postgres://postgres:7b1f...@dokku-postgres-hola-db:5432/hola_db

Tu aplicación solo tiene que leer DATABASE_URL para conectarse. Para hacer una copia de seguridad de la base de datos, exporta un volcado:

sudo dokku postgres:export hola-db > hola-db.dump

Hay plugins equivalentes para Redis (dokku-redis), MySQL (dokku-mysql) y MongoDB (dokku-mongo) con las mismas órdenes create y link.

Paso 8: Activar HTTPS con Let's Encrypt

Instala el plugin de Let's Encrypt y define el correo para los avisos de caducidad:

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
sudo dokku letsencrypt:set --global email [email protected]

Solicita el certificado para la aplicación. El dominio debe resolver al servidor y el puerto 80 debe ser accesible desde Internet:

sudo dokku letsencrypt:enable hola-node

Añade la tarea de renovación automática:

sudo dokku letsencrypt:cron-job --add

Comprueba que la aplicación responde por HTTPS:

curl -sI https://hola-node.dokku.tudominio.com | head -n 1

HTTP/2 200

Para servir la aplicación en un dominio propio, crea un registro A que apunte al servidor, añade el dominio y vuelve a solicitar el certificado para que lo incluya:

sudo dokku domains:add hola-node www.tuempresa.com
sudo dokku letsencrypt:enable hola-node

Solución de problemas

git push devuelve Permission denied (publickey). La clave que usa tu equipo no está registrada en Dokku. Revisa sudo dokku ssh-keys:list y añade la clave pública correcta con echo "ssh-ed25519 AAAA... tu@equipo" | sudo dokku ssh-keys:add portatil.

El push termina sin desplegar. Estás enviando una rama distinta de la de despliegue. Consulta la configuración con sudo dokku git:report hola-node y envía la rama correcta, por ejemplo git push dokku mi-rama:main.

La aplicación devuelve 502 Bad Gateway. El proceso no arrancó o escucha en otro puerto. Revisa sudo dokku logs hola-node y el mapeo de puertos con sudo dokku ports:report hola-node. Si la aplicación escucha, por ejemplo, en el 3000, fija el mapeo:

sudo dokku ports:set hola-node http:80:3000

Conclusión

Tienes Dokku funcionando en Ubuntu 24.04 con despliegues por git push, una base de datos PostgreSQL enlazada y HTTPS automático. Como siguientes pasos, puedes definir comprobaciones de arranque en un archivo app.json para evitar desplegar versiones rotas, programar la exportación de las bases de datos con cron y fijar límites de memoria por aplicación con dokku resource:limit.