Cómo instalar Dokku en un VPS

Requisitos previos

• VPS con Ubuntu 22.04 o 24.04 y dirección IP pública
• Al menos 1 GB de RAM (agrega 1 GB de swap para VMs más pequeñas)
• Acceso SSH como root al VPS
• Un dominio con un registro wildcard A que apunte al VPS (ej. *.apps.example.com)
• Git y un par de claves SSH en tu máquina local

Dokku no es un contenedor Docker. Es una PaaS gestionada por apt que instala Docker Engine como dependencia. Empieza con un servidor limpio. No instales Docker, nginx ni ninguna herramienta de contenedores por adelantado. Dokku lo gestiona todo.

Paso 1: Conectarse al servidor

Entra por SSH y actualiza los paquetes del sistema:

ssh root@SERVER_IP
apt update && apt upgrade -y
hostnamectl set-hostname dokku.example.com

Verifica que el hostname resuelve correctamente y que los puertos 80 y 443 están libres:

ss -ltnp

Reinicia si el kernel se actualizó. Tras el reinicio, vuelve a conectarte y continúa.

Paso 2: Instalar Dokku con el script de bootstrap

Descarga el script oficial de bootstrap para una versión específica y ejecútalo. No instales Docker manualmente. El script lo hace por ti.

wget -NP . https://dokku.com/install/v0.38.25/bootstrap.sh
sudo DOKKU_TAG=v0.38.25 bash bootstrap.sh

Durante la instalación, el script muestra una pantalla azul de configuración debconf. Pide dos cosas:

1. Dominio global — escribe apps.example.com (o el dominio que configuraste)
2. Clave SSH — déjalo vacío. La registrarás en el siguiente paso.

Usa la tecla Tab para moverte entre campos y Enter para confirmar. Si te saltas la pantalla, ejecuta sudo dpkg-reconfigure dokku después.

Cuando termine, verifica que todo funciona:

dokku version
docker version
sudo systemctl status dokku

Dokku incluye su propia instancia de nginx. Los puertos 80 y 443 ahora están gestionados por Dokku.

Paso 3: Registrar la clave SSH y configurar el dominio

Este es el paso más importante. Sin una clave SSH registrada, Dokku rechaza todos los intentos de git push.

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

Este comando registra la clave pública del usuario root (la misma que usaste para conectarte por SSH). Reemplaza admin con la etiqueta que prefieras.

Establece el dominio global para que cada app reciba un hostname automáticamente:

sudo dokku domains:set-global apps.example.com

Confirma que la clave y el dominio están registrados:

dokku ssh-keys:list
dokku domains:report --global

Paso 4: Desplegar la primera aplicación

Crea una aplicación en el servidor:

dokku apps:create hello

Desde tu máquina local, agrega el remote de Dokku y haz push:

git remote add dokku [email protected]:hello
git push dokku main

Dokku detecta el tipo de proyecto (Dockerfile o buildpack), lo construye, ejecuta el contenedor y configura nginx automáticamente. La aplicación es accesible en http://hello.apps.example.com.

Revisa el estado de la aplicación:

dokku ps:report hello
dokku logs hello -t

Paso 5: SSL con Let's Encrypt

Dokku no incluye HTTPS de fábrica. Instala el plugin oficial de Let's Encrypt:

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

Configura el plugin con tu correo electrónico (para avisos de renovación):

dokku config:set --global [email protected]

Activa el certificado para tu aplicación:

dokku letsencrypt:enable hello

Desde este momento, https://hello.apps.example.com sirve HTTPS. Dokku gestiona la renovación automática mediante un cron job instalado por el plugin.

Verifica que la renovación automática está programada:

dokku letsencrypt:cron-job --add

Mantenimiento

Actualiza Dokku y todos los plugins a través de apt. No actualices solo dokku sin actualizar también Docker, que comparte la misma fuente apt:

sudo apt update && sudo apt upgrade -y

Haz backup de los datos persistentes de los plugins (bases de datos, etc.) en una ubicación separada antes de cualquier actualización importante. Vigila el uso del disco: las imágenes antiguas y las capas de Docker se acumulan con el tiempo. Limpia los recursos no utilizados periódicamente:

docker system prune -af

Reinicia el servidor tras una actualización del kernel y confirma que Dokku inicia el proxy y todas las aplicaciones:

dokku proxy:report
dokku ps:rebuildall

Cuando falle un despliegue, revisa los logs y el informe del proceso antes de eliminar volúmenes. Revierta con dokku ps:rebuild sobre una versión anterior.