Capitulo 5: Primer Deploy

< Volver al Indice del Tutorial

Crear una App Node.js de Ejemplo

Vamos a crear una aplicacion Express minima para desplegar en Dokploy. Crea un repositorio nuevo en GitHub con estos archivos:

package.json

{
  "name": "dokploy-demo",
  "version": "1.0.0",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.21.0"
  }
}

server.js

const express = require("express");
const app = express();
const PORT = process.env.PORT || 3000;

app.get("/", (req, res) => {
  res.json({
    status: "ok",
    message: "App desplegada con Dokploy",
    timestamp: new Date().toISOString(),
    node_version: process.version,
  });
});

app.get("/health", (req, res) => {
  res.status(200).json({ healthy: true });
});

app.listen(PORT, "0.0.0.0", () => {
  console.log(`Servidor corriendo en puerto ${PORT}`);
});

.gitignore

node_modules/
.env

Sube estos archivos a un repositorio en GitHub (puede ser publico o privado).

Conectar Repositorio GitHub con Dokploy

Opcion 1: Repositorio publico (mas rapido)

Si tu repositorio es publico, puedes conectarlo sin autenticacion.

1. En el panel de Dokploy, ve a Projects.
2. Crea un nuevo proyecto llamado “demo”.
3. Dentro del proyecto, haz clic en Create Service > Application.
4. En el formulario:
   • Name: demo-api
   • Source: Git
5. Haz clic en Create.

En la configuracion de la aplicacion:

1. Ve a la pestana General.
2. En Repository URL, ingresa la URL HTTPS de tu repositorio:

   https://github.com/tu-usuario/dokploy-demo.git

3. En Branch, selecciona main.
4. Haz clic en Save.

Opcion 2: Repositorio privado con GitHub App

Para repositorios privados, Dokploy ofrece integracion directa con GitHub:

1. Ve a Settings > Git Providers.
2. Haz clic en Connect GitHub.
3. Se abre una ventana de autorizacion de GitHub.
4. Selecciona la cuenta u organizacion.
5. Elige los repositorios a los que Dokploy tendra acceso (o todos).
6. Confirma la autorizacion.

Una vez conectado, al crear una aplicacion puedes seleccionar el repositorio directamente desde un dropdown en lugar de escribir la URL.

Opcion 3: Repositorio privado con SSH Key

Si prefieres no usar la GitHub App:

1. Ve a Settings > SSH Keys y genera un par de claves.
2. Copia la clave publica.
3. En GitHub, ve al repositorio > Settings > Deploy Keys > Add deploy key.
4. Pega la clave publica y habilita acceso de lectura.
5. En Dokploy, usa la URL SSH del repositorio:

   [email protected]:tu-usuario/dokploy-demo.git

Configurar el Build y Deploy

Metodo de build: Nixpacks

Nixpacks es el metodo de build por defecto y el mas simple. Detecta automaticamente que tu proyecto es Node.js por la presencia de package.json.

En la pestana General de la aplicacion:

1. Build Type: Nixpacks (seleccionado por defecto).
2. Publish Directory: Dejar vacio (no es un sitio estatico).

No necesitas configurar nada mas. Nixpacks detecta:

• Runtime: Node.js (por package.json).
• Comando de instalacion: npm install.
• Comando de inicio: npm start (del script en package.json).

Variables de entorno

Ve a la pestana Environment y agrega:

PORT=3000

Dokploy inyecta estas variables en el contenedor durante el build y en tiempo de ejecucion.

Puerto de la aplicacion

En la pestana Advanced > Ports, configura:

• Container Port: 3000
• Protocol: HTTP

Este es el puerto interno donde Express escucha. Traefik enruta el trafico externo (80/443) a este puerto.

Ejecutar el Deploy

Con todo configurado:

1. Ve a la pestana Deployments.
2. Haz clic en Deploy.
3. Dokploy inicia el proceso de build.

Que sucede durante el deploy

El ciclo completo es:

1. Clone: Dokploy clona el repositorio desde GitHub.
2. Build: Nixpacks analiza el proyecto, instala dependencias y construye la imagen Docker.
3. Push: La imagen se almacena en el registry interno.
4. Deploy: Docker Swarm despliega el contenedor con la nueva imagen.
5. Health Check: Dokploy verifica que el contenedor esta saludable.
6. Route: Traefik actualiza las rutas para dirigir trafico al nuevo contenedor.

Ver los Logs del Build

Durante el deploy, la pestana Deployments muestra los logs en tiempo real:

[+] Building...
=> Detecting language: Node.js
=> Installing dependencies
npm install
added 64 packages in 3s
=> Starting application
npm start
Servidor corriendo en puerto 3000

Si el build falla, los logs muestran el error exacto. Causas comunes:

• Dependencia faltante: Error en npm install. Verifica package.json.
• Error de sintaxis: El codigo no compila. Revisa el error del build.
• Puerto incorrecto: La app inicia pero Traefik no puede conectar. Verifica la configuracion de puertos.

Historial de deployments

Cada deploy se registra con:

• Fecha y hora.
• Commit hash de Git.
• Estado: success, failed, running.
• Duracion del build.
• Logs completos.

Puedes hacer rollback a cualquier deploy anterior haciendo clic en “Redeploy” en un deployment exitoso previo.

Acceder a la Aplicacion Desplegada

Sin dominio (por IP)

Si no has configurado un dominio, puedes acceder temporalmente por el puerto expuesto. En la pestana Advanced > Ports, habilita el acceso publico al puerto.

Accede a:

http://tu-ip-del-servidor:3000

Con dominio (recomendado)

Para acceso por dominio con SSL:

1. Ve a la pestana Domains.
2. Haz clic en Add Domain.
3. Ingresa el dominio (ej: api.tudominio.com).
4. Selecciona HTTPS y habilita Generate Certificate.
5. Haz clic en Save.

Previamente debes crear un registro DNS tipo A apuntando api.tudominio.com al IP de tu servidor.

Una vez propagado el DNS (puede tomar minutos), accede a:

https://api.tudominio.com

Respuesta esperada:

{
  "status": "ok",
  "message": "App desplegada con Dokploy",
  "timestamp": "2026-02-28T15:30:00.000Z",
  "node_version": "v20.11.0"
}

Entender el Ciclo: Push, Build, Deploy

Una vez configurada la aplicacion, el flujo de trabajo continuo es:

[Git Push] → [Webhook] → [Clone] → [Build] → [Deploy] → [Route]

Deploys automaticos

Para que cada push a la rama main dispare un deploy automatico:

1. En la pestana General, habilita Autodeploy.
2. Dokploy registra un webhook en tu repositorio de GitHub.
3. Cada push a la rama configurada inicia un build y deploy automaticamente.

Deploys manuales

Si prefieres control manual:

1. Deshabilita Autodeploy.
2. Ve a Deployments y haz clic en Deploy cuando quieras desplegar.

Flujo tipico de desarrollo

# Desarrollar localmente
code server.js

# Probar localmente
node server.js

# Commit y push
git add .
git commit -m "feat: agregar endpoint /users"
git push origin main

# Si Autodeploy esta habilitado: deploy automatico
# Si no: ir al panel y hacer clic en Deploy

Verificar el deploy

Despues de cada deploy, verifica que la aplicacion responde:

curl https://api.tudominio.com/health

Respuesta esperada:

{ "healthy": true }

El health check endpoint (/health) es una buena practica. Dokploy puede usarlo para verificar automaticamente que la aplicacion esta funcionando y reiniciarla si falla.

---

Siguiente: Capitulo 6: Nixpacks —>