Nomenclatura de aplicaciones

🎯 Objetivo: Definir nombres consistentes para las aplicaciones.

Formato obligatorio

[cliente]-[app]-[ambiente]

Reglas

• Todo en minúsculas.
• Solo letras, números y guión medio (-).
• Sin espacios, tildes, ñ, guión bajo (_) ni caracteres especiales.
• cliente y app deben ser cortos y claros.
• ambiente debe ser uno de: prod, staging, dev, test.
• No repetir palabras entre cliente y app.

Ejemplos válidos

• trantor-form990-prod
• agrosuper-intranet-staging
• tallerdigital-crm-prod
• luksic-portal-dev

Ejemplos inválidos

• Trantor-Form990-Prod (mayúsculas)
• trantor_form990_prod (guión bajo)
• trantor-form 990-prod (espacio)
• trantor-form990-production (ambiente no estándar)
• trantor--form990-prod (doble guión)

Creación y configuración de aplicación

🎯 Objetivo: crear y configurar una nueva aplicación en un servidor Dokku existente.

Verificación de Dokku

Si el servidor fue configurado previamente, debería poseer Dokku instalado y activo. Usar el siguiente comando para verificar:

dokku version

Creación de aplicación

Utilizar el nombre definido en el paso anterior “Definir nombre de aplicación”.

# Crear aplicación
dokku apps:create <app_name>

# Verificar creación
dokku apps:list

Creación de base de datos

Elegir una opción según el stack de la aplicación.

Opción A: PostgreSQL

Para el nombre, usar <app_name>-postgres.

# Crear base de datos
dokku postgres:create <app_name>-postgres

# Verificar creación de base de datos
dokku postgres:list

# Vincular base de datos a la aplicación
dokku postgres:link <app_name>-postgres <app_name>

Al vincular PostgreSQL se crea automáticamente la variable DATABASE_URL.

# Ver variable
dokku config:get <app_name> DATABASE_URL

Opción B: MongoDB

Para el nombre, usar <app_name>-mongo.

# Crear base de datos
dokku mongo:create <app_name>-mongo

# Verificar creación
dokku mongo:list

# Vincular base de datos a la aplicación
dokku mongo:link <app_name>-mongo <app_name>

Al vincular MongoDB se crea automáticamente la variable MONGO_URL.

# Ver variable
dokku config:get <app_name> MONGO_URL

Creación de Redis (opcional)

Solo si la aplicación requiere Redis, para caché, Celery u otros. Para el nombre, utilizar el mismo de la aplicación y agregar -redis al final.

# Crear Redis
dokku redis:create <app_name>-redis

# Verificar creación de Redis
dokku redis:list

# Vincular Redis a la aplicación
dokku redis:link <app_name>-redis <app_name>

Al igual que la base de datos, se cargará automáticamente una variable de entorno llamada REDIS_URL con la información de conexión de Redis. Esta variable servirá más tarde para configurar en la aplicación y se puede obtener usando dokku config:get <app_name> REDIS_URL.

Configuración de dominio y SSL

Agregar un dominio que permitirá acceder a la aplicación, configurar DNS y obtener certificados SSL.

Para asignar un dominio a la app, usar el comando:

# Agregar dominio
dokku domains:add <app_name> <dominio>

# Verificar dominio
dokku domains:report <app_name>

Luego de configurar el dominio, será necesario apuntar al servidor Dokku desde el dominio, para esto crear un registro DNS tipo A con la dirección IP del servidor Dokku.

# En Cloudflare o proveedor DNS.
# Crear registro:
Tipo: A
Nombre: <dominio> (o @ para raíz)
Contenido: <ip_servidor_dokku>
Proxy: OFF (nube gris, apagado)

# Verificar propagación, desde una terminal:
# Si el registro se ha propagado correctamente, debería mostrar la dirección IP del servidor Dokku.
dig <dominio> +short

Una vez confirmado el DNS, obtener un nuevo certificado SSL usando Let’s Encrypt.

# Configurar email
dokku letsencrypt:set <app_name> email soporte@tallerdigital.cl

# Obtener certificado
dokku letsencrypt:enable <app_name>

# Activar renovación automática
dokku letsencrypt:cron-job --add

Configuración de variables de entorno

El formato estándar para crear variables de entorno es el siguiente:

# Configurar variable de entorno
dokku config:set <app_name> <variable> <valor>

Preparar aplicación Node.js para Dokku

Objetivo: dejar el proyecto listo para desplegar en Dokku sin fallas de runtime.

Estructura mínima requerida

proyecto/
├── Procfile
├── package.json
├── package-lock.json
└── src/

Crear Procfile

Usar un Procfile en la raíz del repositorio (sin extensión).

# app simple
web: node src/index.js

# con build/release
web: npm run start:prod
release: npm run build

Configurar package.json

Definir versión de runtime y scripts de arranque.

{
  "engines": {
    "node": "20.x",
    "npm": "10.x"
  },
  "scripts": {
    "start": "node src/index.js",
    "start:prod": "node dist/index.js",
    "build": "tsc"
  }
}

Usar siempre process.env.PORT

La app debe escuchar el puerto que entrega Dokku.

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0");

Configurar variables de entorno en Dokku

Objetivo: establecer variables obligatorias de producción y secretos de la app.

Variables base

dokku config:set <app_name> NODE_ENV=production
dokku config:set <app_name> APP_NAME='Nombre Proyecto'
dokku config:set <app_name> APP_URL='https://app.dominio.com'

Variables sensibles típicas

dokku config:set <app_name> JWT_SECRET='<secret_64_chars>'
dokku config:set <app_name> SMTP_HOST='smtp.sendgrid.net'
dokku config:set <app_name> SMTP_PORT=587

Verificación

dokku config:show <app_name>

Confirmar que existan al menos:

• NODE_ENV
• DATABASE_URL o MONGO_URL (si aplica)
• REDIS_URL (si aplica)

Configurar storage persistente

🎯 Objetivo: configurar un storage persistente de Dokku en una app Node.js.

Como Dokku carga las aplicaciones en contenedores, es necesario configurar un storage persistente para almacenar archivos que deban sobrevivir a nuevos despliegues. En Node.js, el caso más común es persistir una carpeta de uploads.

Storage para uploads

Para configurar storage persistente, usar los siguientes comandos:

# crear directorio storage en servidor
mkdir -p /var/lib/dokku/data/storage/<app_name>

# mount storage a la app
dokku storage:mount <app_name> /var/lib/dokku/data/storage/<app_name>:/app/uploads

# configurar permisos
chown -R 32767:32767 /var/lib/dokku/data/storage/<app_name>

# confirmar mounts activos
dokku storage:list <app_name>

# en la app Node, usar ruta persistente:
# /app/uploads

Primer despliegue en Dokku

Objetivo: conectar el repositorio local con la app en Dokku, desplegar y validar estado inicial.

Configurar remote Git por ambiente

Usar el nombre del ambiente como remote (dev, stg, prd o qa).

git remote add <ambiente> dokku@<host>:<app_name>
git remote -v

Ejecutar primer despliegue

# para ramas main/master (según repositorio)
git push <ambiente> main:master

En despliegues posteriores, usar:

git push <ambiente>

Verificar estado de la aplicación

dokku ps:report <app_name>
dokku urls <app_name>
dokku logs <app_name> -t

Configurar healthcheck en Dokku

Objetivo: validar automáticamente que la app responda correctamente después de cada deploy.

Exponer endpoint de health en la app

Agregar una ruta simple que retorne estado 200.

// Express
app.get("/health", (_req, res) => {
  res.status(200).json({ status: "ok" });
});

Configurar checks en Dokku

dokku checks:set <app_name> web /health

Validar configuración

dokku checks:report <app_name>

Esperado: endpoint /health configurado para proceso web.

Probar endpoint públicamente

curl -I https://<dominio>/health

Esperado: HTTP 200.

Validación final de instalación Node.js

Objetivo: confirmar que la app quedó operativa y estable en producción.

Test 1: Sitio accesible

curl -I https://<dominio>

Esperado: HTTP 200.

Test 2: SSL válido

openssl s_client -connect <dominio>:443 -servername <dominio> < /dev/null 2>/dev/null | grep "Verify return code"

Esperado: Verify return code: 0 (ok).

Test 3: Proceso activo

dokku ps:report <app_name>

Esperado: proceso web en estado running.

Test 4: Logs sin errores críticos

dokku logs <app_name> -n 150 | grep -i error

Esperado: sin errores críticos persistentes.