DEV Community: Oscar Ricardo Sánche Gutierréz

Build an AI Email Assistant with n8n and Telegram

Oscar Ricardo Sánche Gutierréz — Fri, 01 May 2026 23:16:32 +0000

Is your inbox flooded with repetitive emails? Support queries, FAQs, information requests… they all eat up time and require manual replies.

In this article you'll build an automated email assistant that:

Reads incoming emails via IMAP
Analyzes them with DeepSeek using a custom knowledge base
Replies automatically when the model has enough context
Notifies you via Telegram when it needs human review

Diagram created with https://savnet.co

What you need

A server with n8n up and running (if you don't have one, follow this installation guide)
An email account with IMAP access (ZohoMail, Gmail, Outlook, or any provider that supports it)
A DeepSeek API key (platform.deepseek.com)
A Telegram bot created via https://t.me/BotFather

Note: Telegram bots have no usage costs, making them ideal for automations with no message limits.

1. Getting your credentials

DeepSeek API

DEEPSEEK_API_KEY
Endpoint URL: https://api.deepseek.com/v1/chat/completions
Recommended model: deepseek-chat

Telegram Bot

Creating a Telegram bot is quick and requires no company registration or credit cards. Open Telegram, search for @BotFather, send /newbot and follow the steps. At the end you'll get a token like 4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc.

For more details on bot creation: Telegram Bot Creation Handbook

Getting your Chat ID

You need to know your Chat ID (your Telegram user ID) so the bot knows where to send messages.

Open Telegram and search for @userinfobot
Start the conversation with Start
The bot replies automatically with your info. Look for the line that says Id: — that number is your Chat ID

Id: 1234567890   <<< This is your Chat ID
First: YourName
Lang: en
....

Save both values (Bot Token and Chat ID) for later use in n8n.

2. Building the workflow in n8n

If you're new to n8n, the first step is creating a workflow. At each stage I'll tell you which node to add so you can find it like this:

Step by step:

Node 1 — IMAP Trigger

Add the Email Trigger (IMAP) node, which will be our workflow's trigger and will check for unread emails in our inbox.

In the Credential field, configure the following (values and setup vary by email provider):

User: your email
Password: your password or app password
Host: your IMAP server (e.g. imap.gmail.com)
Port: 993
Secure: true

In the rest of the form, fill in:

Mailbox Name: the mailbox to pull emails from, defaults to INBOX
Action: Mark as Read — this way every processed email gets marked as read.

By default, once the workflow is published the node will poll periodically (every 60 seconds by default) to detect new emails.

Node 2 — Code (Knowledge Base)

The "secret sauce" of the assistant lives here. Instead of letting DeepSeek improvise, you define a clear context with the responses you expect.

Add a Code node (Code in Javascript), switch the mode to "Run Once for All Items" (top-right of the editor) and connect it to Node 1 (IMAP).

The code must preserve the email data we care about and add the knowledgeBase field.

const knowledgeBase = `
Eres un asistente de soporte técnico de [Tu Empresa].
Responde solo si encuentras una coincidencia clara en las políticas siguientes.
Si no estás seguro, responde exactamente: NO_PUEDO_RESPONDER
POLÍTICAS:
1. Horario de atención: Lunes a viernes de 9:00 a 18:00 (GMT-5).
2. Tiempo de respuesta estimado: 24 horas hábiles.
3. Contraseñas: Nunca solicites ni compartas contraseñas por correo.
4. Reembolsos: Se procesan dentro de los primeros 30 días. El usuario debe enviar un comprobante.
5. Problemas técnicos comunes:
   - Error 403: El usuario debe limpiar caché y cookies.
   - Error 500: Reportar al equipo interno, pedir al usuario que espere 1 hora.
   - Olvido de contraseña: Enviar enlace de restablecimiento a su correo registrado.
6. Facturación: Para cambios de plan o facturación, responder que el usuario ingrese al panel de pago.
INSTRUCCIONES:
- Responde de forma amable y profesional.
- Usa el mismo idioma del correo recibido.
- Si el correo contiene más de una pregunta, responde cada punto.
- Si el correo es grosero o agresivo, responde: NO_PUEDO_RESPONDER
`;

const items = $input.all();
return items.map(item => ({
  json: {
    ...item.json,
    knowledgeBase
  }
}));

You can make this as detailed as you want. The more context, the better the responses. Using ...item.json preserves the original email data so Node 3 (content extraction) receives it without issues.

Name this node, for example, CodeKnow.

Node 3 — Code (Extract Content)

Use another Code node (Code in Javascript) to extract the relevant information from each email and generate the chatInput with the prompt we'll send to our AI. Switch the mode to "Run for Each Item":

const email = $input.item.json;
const subject = email.subject || '';
const body =
  (email.textPlain && email.textPlain.trim()) ||
  (email.textHtml && email.textHtml.trim()) ||
  '';

return {
  subject,
  body: body.substring(0, 5000),
  from: email.from,
  to: email.to,
  uid: email.uid || email.id,
  chatInput: `From: ${email.from}\nAsunto: ${subject}\nCuerpo: ${body.substring(0, 5000)}`
};

Node 4 — DeepSeek Chat Model (Configuration)

Add a DeepSeek Chat Model node. It will likely auto-generate 3 nodes: When chatmessage received, Basic LLM Chain and DeepSeek Chat Model. Keep only the LLM and DeepSeek — the extra one isn't needed. Connect the code block to the Basic LLM node like this:

In the remaining blocks, set up the following:

In DeepSeek Chat Model, just configure the credentials:

Credential: select or create a DeepSeek account credential
- API Key: your DeepSeek key
Model: deepseek-v4-flash

In Basic LLM Chain (processor):

Source for Prompt: Define below
Prompt (User Message): Analyze this email and provide a short, clear response to send via Telegram. {{ $json.chatInput }}
Chat Messages:
- Type: System → Message: {{ $json.knowledgeBase }}
Require Specific Output Format: disabled

What we've done is send a prompt with our intent and the email data defined in the CodeProcessEmail block, along with a system message containing our knowledge base — the info we defined in the CodeKnow block.

What about cost? DeepSeek v4 charges ~$0.14 per million input tokens and ~$0.28 per output. A typical email (~1,000 tokens) costs ~$0.0002. With 1,000 emails a month you'd spend ~$0.20. In the production tweaks section I'll show you how to filter to avoid unnecessary calls.

The node takes the chatInput from Node 3 (knowledge base + email) and returns the response generated by DeepSeek.

Node 5 — Code (Map Assistant Response)

The DeepSeek block only returns the AI's raw response, which means we lose the full email data we'll need later. That's why we add this Code node in "Run Once for All Items" mode to merge the AI response with the original email data and determine whether it can reply or not:

const aiItems = $input.all();
const emailItems = $('CodeProcessEmail').all();

const output = aiItems.map((item, index) => {
  const originalEmail = emailItems[index]?.json || {};

  const aiText = item.json.text || '';

  return {
    json: {
      ...originalEmail,
      aiResponse: aiText.trim(),
      canReply: !aiText.includes('NO_PUEDO_RESPONDER')
    }
  };
});

return output;

This block is key because:

It grabs the original email data (subject, from, body, etc.)
It adds aiResponse with the clean response from DeepSeek
It adds canReply (true/false) to decide whether to auto-reply

Node 6 — IF (Can it reply?)

With the AI response and email data at hand, we add an if block. This node evaluates the {{ $json.canReply }} field with the following:

Yes (true) → goes to SMTP send
No (false) → goes to Telegram notification

Node 7.1 — Email (SMTP) — Reply

Configure the Send Email node to send the automatic reply:

Credential: a window will open for you to register your SMTP credentials:
- User
- Password
- Host
- Port
- SSL
From Email: we'll tell it to reply from the same address they wrote to: {{ $json.to }}
To: the person who wrote in: {{ $json.from }}
Subject: Re: {{ $('CodeProcessEmail').item.json.subject }}
Email Format: HTML
Text: {{ $json.aiResponse }}

Node 7.2 — Telegram — Send Notification

For emails the AI can't handle, we won't send an automatic reply. Instead, you'll receive an alert via Telegram.

However, we first need to make sure we're not sending messages longer than 4,000 characters — Telegram's limit. To handle this:

Add a Code node (JavaScript) in Run Once for All Items mode with the following code:

const escapeHtml = (value) => {
  return String(value || '')
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;');
};
const items = $input.all();

let text = '';
items.forEach((item, index) => {
  const subject = escapeHtml(item.json.subject || 'Sin asunto');
  const aiResponse = escapeHtml(item.json.aiResponse || '');
  text += `${index + 1}) ${subject}: ${aiResponse}\n━━━━━━━━━━━━━━━━━━━━\n`;
});

// ---- split into chunks ----
const chunkSize = 3900;
const header = `━━━━━━━━━━━━━━━━━━━━\n<b>Recibiste los siguientes correos:</b>\n\n`;

const fullText = header + text;
const totalParts = Math.ceil(fullText.length / chunkSize) || 1;

const output = [];
for (let i = 0; i < fullText.length; i += chunkSize) {
  const part = Math.floor(i / chunkSize) + 1;
  output.push({
    json: {
      text: `[${part}/${totalParts}]\n${fullText.slice(i, i + chunkSize)}`
    }
  });
}

return output;

Add an HTTP Request node to send each of the messages we defined:
Method: POST
URL: https://api.telegram.org/bot{YourTelegramToken,format:0000:xxxxxx}/sendMessage
Authentication: none
SendBody: true
Body Content Type: JSON
Specify Body: Using Fields Below
1. chat_id: your Telegram conversation ID
2. text: {{ $json.text }}
3. parse_mode: HTML
4. disable_web_page_preview: TRUE

That's it — our workflow is done :D

3. Testing the workflow

⚠️ Before going live, run controlled tests. Don't connect this workflow directly to your personal or company inbox. Use a test email account (IMAP + SMTP) that contains no sensitive or confidential information. If something goes wrong — a bad AI interpretation, a misconfigured domain — you could end up auto-replying to real customers with incorrect information. Better safe than sorry.

With the workflow ready, do the following:

Run it manually by clicking the Execute Workflow button (top right). This triggers the workflow immediately without waiting for automatic polling.
Send yourself a test email with a question that's covered in your knowledge base.
Check that you receive the automatic reply in the test sender's inbox.
Send another email with something outside your knowledge base.
You should receive a Telegram notification with the email content.

When everything works as expected, just click Publish to enable polling and put it into production.

4. Production tweaks

Filter by sender

Add an IF node after the trigger to only process emails from specific domains or addresses:

const from = $input.item.json.from;
const allowedDomains = ['yourdomain.com', 'client.com'];
const domain = from.split('@')[1];
return allowedDomains.includes(domain);

Rate limiting

DeepSeek has rate limits per minute. If you expect a high volume of emails, add a Wait node of 1-2 seconds between processing batches, or use a queue.

Conversation history

If you want DeepSeek to remember previous conversations, you can store the history in a database (PostgreSQL, Redis) and pass it as additional context on each iteration.

Handling attachments

DeepSeek doesn't process files directly. If you receive emails with attachments, you can use a Code node to extract text from PDFs or images (via OCR) and pass it as context.

Conclusion

You now have an automated email assistant that:

Reads emails via IMAP without missing any
Analyzes them with DeepSeek against your own knowledge base
Replies automatically when it can
Notifies you via Telegram when it needs your input

This doesn't replace a support team, but it absorbs the volume of repetitive questions and frees up time for what really matters.

If you want to visually document this workflow or more complex infrastructure diagrams, Savnet helps you design them. And if you need to continuously validate this kind of automation, SavFalconEye lets you keep confidence in every change.

Ready to give it a try? Let me know how it went in the comments.

Crea un asistente de correo con IA usando n8n y Telegram

Oscar Ricardo Sánche Gutierréz — Fri, 01 May 2026 23:10:52 +0000

¿Tu bandeja de entrada está llena de correos repetitivos? Consultas de soporte, preguntas frecuentes, solicitudes de información... todo requiere tiempo y respuestas manuales.

En este artículo vas a construir un asistente automatizado de correo electrónico que:

Lee los correos entrantes vía IMAP
Los analiza con DeepSeek usando una base de conocimiento personalizada
Responde automáticamente si el modelo tiene suficiente contexto
Te notifica por Telegram si necesita revisión manual

Diagrama realizado con https://savnet.co

¿Qué necesitas?

Un servidor con n8n funcionando (si no lo tienes, sigue esta guía de instalación)
Una cuenta de correo con acceso IMAP (ZohoMail, Gmail, Outlook, o cualquier proveedor que lo soporte)
Una clave API de DeepSeek (platform.deepseek.com)
Un bot de Telegram creado con https://t.me/BotFather > Nota: Telegram no tiene costos asociados por uso de bots, ideal para automatizaciones sin límites de mensajes.

1. Obtener credenciales

DeepSeek API

Regístrate en platform.deepseek.com, ve a la sección de API Keys y crea una nueva. Vas a necesitar:

DEEPSEEK_API_KEY
URL del endpoint: https://api.deepseek.com/v1/chat/completions
Modelo recomendado: deepseek-chat

Bot de Telegram

Crear un bot en Telegram es rápido y no requiere registro de empresa ni tarjetas. Para crear el bot abre Telegram, busca @BotFather, envía /newbot y sigue los pasos. Al finalizar te dará un token como 4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc.

Para más detalle sobre la creación del bot: Telegram Bot Creation Handbook

Obtener el Chat ID

Necesitas saber el Chat ID (tu ID de usuario en Telegram) para que el bot sepa a quién enviarle los mensajes.

Abre Telegram y busca @userinfobot
Inicia la conversación con Start
El bot te responde automáticamente con tu información. Busca la línea que dice Id:, ese número es tu Chat ID

Id: 1234567890   <<< Este es tu Chat ID
First: TuNombre
Lanf: es
....

Guarda ambos valores (Bot Token y Chat ID) para usarlos en n8n.

2. Construir el flujo en n8n

Si eres nuevo en n8n lo primero es crear un flujo. En cada paso te diré el nombre del nodo a agregar para que lo puedas buscar así:

Paso a paso:

Nodo 1 - Trigger IMAP

Agrega el nodo Email Trigger (IMAP), el cual será el activador de nuestro flujo y revisará los correos sin leer en nuestro buzón.

En el campo Credential debes configurar (los valores y la forma de activación varían según el proveedor de correo):

User: tu correo
Password: tu contraseña o contraseña de aplicación
Host: tu servidor IMAP (ej: imap.gmail.com)
Port: 993
Secure: true

En el resto de formulario ingresa:

Mailbox Name: nombre del buzón donde se deben extraer los correos, por defecto INBOX (Bandeja de entrada)
Action: Mark as Read, con esto cada mensaje que procesemos será marcado como leído.

Por defecto, cuando publiquemos el workflow el nodo hará polling cada cierto tiempo (por defecto cada 60 segundos) para detectar correos nuevos.

Nodo 2 - Code (Base de conocimiento)

El "secreto" del asistente está aquí. En lugar de dejar que DeepSeek improvise, le defines un contexto claro con las respuestas que esperas.

Agrega un nodo Code (Code in Javascript), cambia el modo a "Run Once for All Items" (arriba a la derecha del editor) y conéctalo al Nodo 1 (IMAP).

El código debe preservar los datos del correo que nos interesan y agregar el campo knowledgeBase.

const knowledgeBase = `
Eres un asistente de soporte técnico de [Tu Empresa].
Responde solo si encuentras una coincidencia clara en las políticas siguientes.
Si no estás seguro, responde exactamente: NO_PUEDO_RESPONDER
POLÍTICAS:
1. Horario de atención: Lunes a viernes de 9:00 a 18:00 (GMT-5).
2. Tiempo de respuesta estimado: 24 horas hábiles.
3. Contraseñas: Nunca solicites ni compartas contraseñas por correo.
4. Reembolsos: Se procesan dentro de los primeros 30 días. El usuario debe enviar un comprobante.
5. Problemas técnicos comunes:
   - Error 403: El usuario debe limpiar caché y cookies.
   - Error 500: Reportar al equipo interno, pedir al usuario que espere 1 hora.
   - Olvido de contraseña: Enviar enlace de restablecimiento a su correo registrado.
6. Facturación: Para cambios de plan o facturación, responder que el usuario ingrese al panel de pago.
INSTRUCCIONES:
- Responde de forma amable y profesional.
- Usa el mismo idioma del correo recibido.
- Si el correo contiene más de una pregunta, responde cada punto.
- Si el correo es grosero o agresivo, responde: NO_PUEDO_RESPONDER
`;

const items = $input.all();
return items.map(item => ({
  json: {
    ...item.json,
    knowledgeBase
  }
}));

Puedes hacer esto tan detallado como quieras. Mientras más contexto, mejor responderá. Al usar ...item.json los datos del correo original se conservan y el Nodo 3 (extraer contenido) los recibe sin problema.

Este nodo se llamará, por ejemplo, CodeKnow.

Nodo 3 - Code (extraer contenido)

Usa otro nodo Code (Code in Javascript) para extraer la información necesaria de cada correo y generar el chatInput con el prompt que enviaremos a nuestra IA. Cambia el modo a "Run for Each Item" :

const email = $input.item.json;
const subject = email.subject || '';
const body =
  (email.textPlain && email.textPlain.trim()) ||
  (email.textHtml && email.textHtml.trim()) ||
  '';

return {
  subject,
  body: body.substring(0, 5000),
  from: email.from,
  to: email.to,
  uid: email.uid || email.id,
  chatInput: `From: ${email.from}\nAsunto: ${subject}\nCuerpo: ${body.substring(0, 5000)}`
};

Nodo 4 - DeepSeek Chat Model (configuración)

Agrega un nodo DeepSeek Chat Model. Es probable que esto te genere 3 nodos automáticamente: When chatmessage received, Basic LLM Chain y DeepSeek Chat Model. Quédate solo con el LLM y DeepSeek, el otro sobra. Conecta el bloque de código con el de Basic LLM, así:

En los bloques que nos quedan debemos:

En DeepSeek Chat Model, solo especificar las credenciales:

Credential: selecciona o crea una credencial DeepSeek account
- API Key: tu clave de DeepSeek
Model: deepseek-v4-flash

En Basic LLM Chain (procesador):

Source for Prompt: Define below
Prompt (User Message): Analyze this email and provide a short, clear response to send via Telegram. {{ $json.chatInput }}
Chat Messages:
- Type: System → Message: {{ $json.knowledgeBase }}
Require Specific Output Format: desactivado

Lo que hemos hecho es enviarle un prompt con nuestra intención y la data del correo que definimos en el bloque CodeProcessEmail junto con un mensaje de sistema con nuestra base de conocimiento, información que definimos en el bloque CodeKnow.

¿Y el costo? DeepSeek v4 cobra ~$0.14 por millón de tokens de entrada y ~$0.28 por salida. Un correo típico (~1,000 tokens) cuesta ~$0.0002. Con 1,000 correos al mes gastarías ~$0.20. En ajustes para producción te muestro cómo filtrar para evitar llamadas innecesarias.

El nodo toma el chatInput del Nodo 3 (base de conocimiento + correo) y devuelve la respuesta generada por DeepSeek.

Nodo 5 - Code (mapear respuesta del asistente)

El bloque de DeepSeek solo nos retorna la respuesta de la IA con lo cual perdemos la información completa del correo que necesitamos más adelante. Por eso agregamos este nodo Code en modo "Run Once for All Items" que combina la respuesta de la IA con los datos del correo original y determina si puede responder o no:

const aiItems = $input.all();
const emailItems = $('CodeProcessEmail').all();

const output = aiItems.map((item, index) => {
  const originalEmail = emailItems[index]?.json || {};

  const aiText = item.json.text || '';

  return {
    json: {
      ...originalEmail,
      aiResponse: aiText.trim(),
      canReply: !aiText.includes('NO_PUEDO_RESPONDER')
    }
  };
});

return output;

Este bloque es clave porque:

Toma los datos originales del correo (subject, from, body, etc.)
Agrega aiResponse con la respuesta limpia de DeepSeek
Agrega canReply (true/false) para decidir si se responde automáticamente

Nodo 6 - IF (¿Puede responder?)

Teniendo a la mano la respuesta de la IA y la información del correo, agregamos un bloque if. Este bloque evalúa el campo {{ $json.canReply }} con la condición:

Sí (true) → va a envío SMTP
No (false) → va a notificación Telegram

Nodo 7.1 - Email (SMTP) - Responder

Configura el nodo Send Email para enviar la respuesta automática:

Credential: te abrirá una ventana para registrar tus credenciales SMTP:
- User
- Password
- Host
- Port
- SSL
From Email: le diremos que responda desde el mismo correo al que escribieron: {{ $json.to}}
To: la persona que escribió {{ $json.from }}
Subject: Re: {{ $('CodeProcessEmail').item.json.subject }}
Email Format: HTML
Text: {{ $json.aiResponse }}

Nodo 7.2 - Telegram - Enviar notificación

Para los correos que la IA no puede responder, no enviaremos una respuesta automática. En su lugar, recibirás una alerta por Telegram.

Sin embargo, antes debemos verificar que no vamos a enviar mensajes de más de 4.000 caracteres —el límite de Telegram—. Para ello:

Agregamos un nodo Code (JavaScript) en modo Run Once for All Items con el código:

const escapeHtml = (value) => {
  return String(value || '')
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;');
};
const items = $input.all();

let text = '';
items.forEach((item, index) => {
  const subject = escapeHtml(item.json.subject || 'Sin asunto');
  const aiResponse = escapeHtml(item.json.aiResponse || '');
  text += `${index + 1}) ${subject}: ${aiResponse}\n━━━━━━━━━━━━━━━━━━━━\n`;
});

// ---- dividir en partes ----
const chunkSize = 3900;
const header = `━━━━━━━━━━━━━━━━━━━━\n<b>Recibiste los siguientes correos:</b>\n\n`;

const fullText = header + text;
const totalParts = Math.ceil(fullText.length / chunkSize) || 1;

const output = [];
for (let i = 0; i < fullText.length; i += chunkSize) {
  const part = Math.floor(i / chunkSize) + 1;
  output.push({
    json: {
      text: `[${part}/${totalParts}]\n${fullText.slice(i, i + chunkSize)}`
    }
  });
}

return output;

Agregamos un nodo de tipo HTTP Request para enviar cada uno de los mensajes que definimos
Method: POST
URL: https://api.telegram.org/bot{TuTokenTelegram,formato:0000:xxxxxx}/sendMessage
Authentication: none
SendBody: true
Body Content Type: JSON
Specify Body: Using Fields Below
1. chat_id: tu ID de conversación en Telegram
2. text: {{ $json.text }}
3. parse_mode: HTML
4. disable_web_page_preview: TRUE

Listo, con esto hemos terminado nuestro flujo :D

3. Probar el flujo

⚠️ Antes de lanzarte a producción, haz pruebas controladas. No conectes este flujo directamente a tu buzón personal o corporativo. Usa una cuenta de correo de pruebas (IMAP + SMTP) que no contenga información sensible ni confidencial. Si algo sale mal — una mala interpretación de la IA, un dominio mal configurado — podrías terminar respondiendo automáticamente a clientes reales con información incorrecta. Mejor prevenir.

Con el flujo listo, haz lo siguiente:

Ejecuta manualmente haciendo clic en el botón Execute Workflow (arriba a la derecha). Esto dispara el flujo de inmediato sin esperar el polling automático.
Envíate un correo de prueba con una pregunta que esté en tu base de conocimiento.
Revisa que recibas la respuesta automática en la bandeja del remitente de prueba.
Envíate otro correo con algo fuera de tu base de conocimiento.
Deberías recibir la notificación en Telegram con el contenido del correo.

Cuando todo funcione como esperas, solo da clic en Publish para activar el polling y dejarlo en producción.

4. Ajustes para producción

Filtrar por remitente

Agrega un nodo IF después del trigger para procesar solo correos de dominios o direcciones específicas:

const from = $input.item.json.from;
const allowedDomains = ['tudominio.com', 'cliente.com'];
const domain = from.split('@')[1];
return allowedDomains.includes(domain);

Rate limiting

DeepSeek tiene límites de peticiones por minuto. Si esperas muchos correos, agrega un nodo Wait de 1-2 segundos entre procesamiento y procesamiento, o usa una cola.

Historial de conversación

Si quieres que DeepSeek recuerde conversaciones anteriores, puedes almacenar el historial en una base de datos (PostgreSQL, Redis) y pasarlo como contexto adicional en cada iteración.

Manejo de adjuntos

DeepSeek no procesa archivos directamente. Si recibes correos con adjuntos, puedes usar un nodo Code para extraer el texto de PDFs o imágenes (con OCR) y pasarlo como contexto.

Conclusión

Tienes un asistente de correo automatizado que:

Lee correos vía IMAP sin perder ninguno
Los analiza con DeepSeek contra tu propia base de conocimiento
Responde automáticamente cuando puede
Te notifica por Telegram cuando necesita tu intervención

Esto no reemplaza un equipo de soporte, pero sí absorbe el volumen de preguntas repetitivas y libera tiempo para lo que realmente importa.

Si quieres documentar visualmente este flujo o diagramas de infraestructura más complejos, Savnet te ayuda a diseñarlos. Y si necesitas validar este tipo de automatizaciones de forma continua, SavFalconEye te permite mantener la confianza en cada cambio.

¿Te animas a probarlo? Cuéntame en los comentarios cómo te fue.

How to Install n8n on an Ubuntu Server (Production-Ready)

Oscar Ricardo Sánche Gutierréz — Wed, 29 Apr 2026 19:41:34 +0000

n8n is an open-source workflow automation platform. It lets you connect services, APIs, and databases through a visual editor without writing hundreds of lines of code — though you can still use JavaScript or Python when custom logic is needed.

In this guide, you'll deploy n8n on an Ubuntu server using Docker Compose, with PostgreSQL as the database, Redis as the queue manager, dedicated workers for background execution, Caddy as a reverse proxy with automatic SSL, and best practices for a production environment.

Diagram made with https://savnet.co

Prerequisites

A server running Ubuntu 22.04 or 24.04 (1 vCPU, 2 GB RAM minimum; 2 vCPU, 4 GB RAM recommended)
Root access for initial setup
A domain or subdomain pointing (A record) to your server's IP
Ports 80 and 443 open in the firewall
Basic command-line knowledge

Don't have a server yet?

If you're looking for affordability and good performance, DigitalOcean is a solid choice. You can get started with this referral link:

https://m.do.co/c/2c579acd7121

1. Initial Connection and System Update

SSH in as root and update the system packages:

ssh root@your-server
apt update && apt upgrade -y

2. Create a Dedicated Admin User

We'll create an n8n user with sudo privileges. From this point on, all work will be done with this user, not root.

# Create the user
adduser --gecos "" n8n

# Add to sudo group
usermod -aG sudo n8n

# Verify
id n8n

Before logging out, copy your public key from root to the new user so you can connect directly as n8n:

# Copy authorized SSH key from root to n8n
mkdir -p /home/n8n/.ssh
cp ~/.ssh/authorized_keys /home/n8n/.ssh/authorized_keys
chown -R n8n:n8n /home/n8n/.ssh
chmod 700 /home/n8n/.ssh
chmod 600 /home/n8n/.ssh/authorized_keys

Now log out and reconnect as n8n:

exit
ssh n8n@your-server

Why a dedicated user?

Running services directly as root is a bad security practice. If someone compromises the n8n process, they'd have full access to the server. A dedicated user limits the potential damage.

3. Install Docker and Docker Compose

# Required packages
sudo apt install -y ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine and Compose plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (to avoid using sudo with every command)
sudo usermod -aG docker $USER

# Verify
docker --version
docker compose version

# Reboot to apply group changes
sudo init 6
ssh n8n@your-server

4. Create Directory Structure

sudo mkdir -p /opt/n8n/{data/postgres,data/redis,data/n8n,data/caddy,backups}
sudo chown -R $USER:$USER /opt/n8n/data/{postgres,redis,data/caddy,backups}

# The data/n8n directory must belong to UID 1000 (the 'node' user inside the container)
sudo chown -R 1000:1000 /opt/n8n/data/n8n
cd /opt/n8n

5. Configure Environment Variables

Create a .env file to store sensitive configuration:

Tips before you start:

Make sure your domain points to the server. Before proceeding, go to your DNS provider and add an A record pointing to your server's IP. Caddy needs to resolve the domain to obtain the SSL certificate.
Generate a secure PostgreSQL password and an encryption key for n8n with these commands:

  openssl rand -base64 24   # For POSTGRES_PASSWORD
  openssl rand -hex 20      # For N8N_ENCRYPTION_KEY

Save the values for the .env file.

nano /opt/n8n/.env

Contents:

# Domain
N8N_DOMAIN=n8n.yourdomain.com

# PostgreSQL
POSTGRES_USER=n8n
POSTGRES_PASSWORD=your_secure_postgres_password
POSTGRES_DB=n8n

# n8n
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=your_secure_postgres_password
N8N_ENCRYPTION_KEY=your_encryption_key
N8N_HOST=${N8N_DOMAIN}
N8N_PROTOCOL=https
WEBHOOK_URL=https://${N8N_DOMAIN}/
N8N_PORT=5678

# Queue mode (Redis)
EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379

Protect the file:

chmod 600 /opt/n8n/.env

6. Create the docker-compose.yml File

nano /opt/n8n/docker-compose.yml

services:
  postgres:
    image: postgres:16-alpine
    container_name: n8n-postgres
    restart: unless-stopped
    env_file: .env
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - n8n-network

  redis:
    image: redis:7-alpine
    container_name: n8n-redis
    restart: unless-stopped
    volumes:
      - ./data/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - n8n-network

  n8n:
    image: n8nio/n8n:latest
    container_name: n8n-app
    restart: unless-stopped
    env_file: .env
    environment:
      - DB_TYPE=${DB_TYPE}
      - DB_POSTGRESDB_HOST=${DB_POSTGRESDB_HOST}
      - DB_POSTGRESDB_PORT=${DB_POSTGRESDB_PORT}
      - DB_POSTGRESDB_DATABASE=${DB_POSTGRESDB_DATABASE}
      - DB_POSTGRESDB_USER=${DB_POSTGRESDB_USER}
      - DB_POSTGRESDB_PASSWORD=${DB_POSTGRESDB_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_HOST=${N8N_HOST}
      - N8N_PROTOCOL=${N8N_PROTOCOL}
      - WEBHOOK_URL=${WEBHOOK_URL}
      - N8N_PORT=${N8N_PORT}
      - N8N_METRICS=true
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=168
      - EXECUTIONS_MODE=${EXECUTIONS_MODE}
      - QUEUE_BULL_REDIS_HOST=${QUEUE_BULL_REDIS_HOST}
      - QUEUE_BULL_REDIS_PORT=${QUEUE_BULL_REDIS_PORT}
    volumes:
      - ./data/n8n:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - n8n-network

  n8n-worker:
    image: n8nio/n8n:latest
    container_name: n8n-worker
    restart: unless-stopped
    env_file: .env
    environment:
      - EXECUTIONS_MODE=${EXECUTIONS_MODE}
      - QUEUE_BULL_REDIS_HOST=${QUEUE_BULL_REDIS_HOST}
      - QUEUE_BULL_REDIS_PORT=${QUEUE_BULL_REDIS_PORT}
      - DB_TYPE=${DB_TYPE}
      - DB_POSTGRESDB_HOST=${DB_POSTGRESDB_HOST}
      - DB_POSTGRESDB_PORT=${DB_POSTGRESDB_PORT}
      - DB_POSTGRESDB_DATABASE=${DB_POSTGRESDB_DATABASE}
      - DB_POSTGRESDB_USER=${DB_POSTGRESDB_USER}
      - DB_POSTGRESDB_PASSWORD=${DB_POSTGRESDB_PASSWORD}
    command: worker
    depends_on:
      - postgres
      - redis
    networks:
      - n8n-network

  caddy:
    image: caddy:2-alpine
    container_name: n8n-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./data/caddy:/data
      - ./data/caddy:/config
    depends_on:
      - n8n
    networks:
      - n8n-network

networks:
  n8n-network:
    driver: bridge

Why use queue mode from the start?

n8n can run workflows in two ways:

Direct mode (default): the main container handles everything. If a workflow takes too long, it blocks subsequent executions.
Queue mode: jobs are queued in Redis and processed by independent workers. You can have multiple workers, scale horizontally, and heavy executions won't affect the main container.

With the docker-compose.yml above, queue mode is active from the first docker compose up.

7. Create the Caddyfile

nano /opt/n8n/Caddyfile

n8n.yourdomain.com {
    reverse_proxy n8n:5678
}

Caddy will automatically obtain an SSL certificate from Let's Encrypt and renew it without manual intervention.

8. Configure the Firewall (UFW)

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
sudo ufw status verbose

9. Start the Stack

cd /opt/n8n
docker compose up -d

Verify all services are running:

docker compose ps

You should see something like:

Check the worker logs to confirm it's picking up jobs:

docker compose logs -f n8n-worker

10. Access n8n and Initial Setup

Open your browser at https://n8n.yourdomain.com. You'll see the registration screen. Create your admin account:

Email: your email
Full name: your name
Password: a strong password

You're ready to start creating workflows. All workflows will run through the worker.

11. Scale Workers

If your workflows grow, scaling is as simple as adding more replicas of the n8n-worker service:

docker compose up -d --scale n8n-worker=3

Each additional worker picks up jobs from the same Redis queue. No other changes needed.

13. Production Best Practices

Use a fixed tag: Instead of n8nio/n8n:latest, use a specific version like n8nio/n8n:1.80.3 to avoid surprises from updates.
Monitoring: n8n exposes Prometheus metrics at /metrics. You can integrate them with a monitoring stack.
Regular backups: Schedule a cron job to back up the data/postgres, data/redis, data/n8n, and data/caddy directories. Since they're bind mounts, you can copy them directly with rsync or tar.
Security: Don't expose port 5678 directly. Caddy handles the proxy. If you need local access, use a VPN or SSH tunnels.
Execution pruning: The EXECUTIONS_DATA_PRUNE=true and EXECUTIONS_DATA_MAX_AGE=168 variables automatically delete old executions after 7 days.

Conclusion

You now have n8n running in production on Ubuntu with PostgreSQL as a persistent database, Redis as the queue manager, dedicated workers, automatic SSL with Caddy, and a structure ready to scale. All running under a dedicated system user — not root.

This queue-mode setup is the same one we use in real-world environments to automate client processes that require high availability and predictable performance, from notifications and CRMs to complex integrations with external APIs.

If you work with networks or visual infrastructure documentation, you can use Savnet to design diagrams for your deployed workflows. And if you need to continuously validate or test automations, SavFalconEye helps maintain confidence in every deployment.

Any questions? Drop them in the comments.

Cómo instalar n8n en un servidor Ubuntu (listo para produción)

Oscar Ricardo Sánche Gutierréz — Wed, 29 Apr 2026 19:37:49 +0000

n8n es una plataforma de automatización de flujos de trabajo de código abierto. Permite conectar servicios, APIs y bases de datos mediante un editor visual sin necesidad de escribir cientos de líneas de código, aunque sí permite ejecutar JavaScript o Python cuando se necesita lógica personalizada.

En esta guía vas a desplegar n8n en un servidor Ubuntu usando Docker Compose, con PostgreSQL como base de datos, Redis como gestor de colas, workers dedicados para ejecución en segundo plano, Caddy como proxy inverso con SSL automático, y buenas prácticas para un entorno de producción.

Diagrama realizado con https://savnet.co

Prerrequisitos

Un servidor con Ubuntu 22.04 o 24.04 (1 vCPU, 2 GB RAM mínimo; 2 vCPU, 4 GB RAM recomendado)
Acceso root para la configuración inicial
Un dominio o subdominio apuntando (registro A) a la IP del servidor
Puertos 80 y 443 abiertos en el firewall
Conocimientos básicos de línea de comandos

¿Aún no tienes servidor?

Si buscas economía y buen rendimiento, DigitalOcean es una opción sólida. Puedes empezar con este enlace de referido:

https://m.do.co/c/2c579acd7121

1. Conexión inicial y actualización del sistema

Conéctate vía SSH como root y actualiza los paquetes:

ssh root@tu-servidor
apt update && apt upgrade -y

2. Crear usuario administrador dedicado

Vamos a crear un usuario n8n con permisos sudo. A partir de este punto, todo el trabajo se hará con este usuario, no con root.

# Crear el usuario
adduser --gecos "" n8n

# Agregarlo al grupo sudo
usermod -aG sudo n8n

# Verificar
id n8n

Antes de cerrar la sesión, copia tu clave pública de root al nuevo usuario para poder conectarte directamente como n8n:

# Copiar la llave autorizada para conexión SSH de root a n8n
mkdir -p /home/n8n/.ssh
cp ~/.ssh/authorized_keys /home/n8n/.ssh/authorized_keys
chown -R n8n:n8n /home/n8n/.ssh
chmod 700 /home/n8n/.ssh
chmod 600 /home/n8n/.ssh/authorized_keys

Ahora cierra sesión y reconéctate como n8n:

exit
ssh n8n@tu-servidor

¿Por qué un usuario dedicado?

Porque ejecutar servicios directamente con root es una mala práctica de seguridad. Si alguien compromete el proceso de n8n, tendría acceso total al servidor. Con un usuario dedicado, el daño queda acotado.

3. Instalar Docker y Docker Compose

# Paquetes necesarios
sudo apt install -y ca-certificates curl gnupg

# Agregar clave GPG oficial de Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Agregar repositorio
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalar Docker Engine y Compose plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Agregar tu usuario al grupo docker (para no usar sudo con cada comando)
sudo usermod -aG docker $USER

# Verificar
docker --version
docker compose version

# Reingresar para hacer efectivos los cambios de grupo
sudo init 6
ssh n8n@tu-servidor

4. Crear estructura de directorios

sudo mkdir -p /opt/n8n/{data/postgres,data/redis,data/n8n,data/caddy,backups}
sudo chown -R $USER:$USER /opt/n8n/data/{postgres,redis,data/caddy,backups}

# El directorio data/n8n debe pertenecer al UID 1000 (usuario 'node' dentro del contenedor)
sudo chown -R 1000:1000 /opt/n8n/data/n8n
cd /opt/n8n

5. Configurar variables de entorno

Crea un archivo .env para almacenar la configuración sensible:

Tips antes de empezar:

Asegúrate de que tu dominio apunte al servidor. Antes de continuar, ve a tu proveedor de DNS y agrega un registro A con la IP de tu servidor. Caddy necesita resolver el dominio para obtener el certificado SSL.
Genera una contraseña segura para PostgreSQL y una encryption key para n8n con estos comandos:

  openssl rand -base64 24   # Para POSTGRES_PASSWORD
  openssl rand -hex 20      # Para N8N_ENCRYPTION_KEY

Guarda los valores para el .env.

nano /opt/n8n/.env

Contenido:

# Dominio
N8N_DOMAIN=n8n.tudominio.com

# PostgreSQL
POSTGRES_USER=n8n
POSTGRES_PASSWORD=password_seguro_postgres
POSTGRES_DB=n8n

# n8n
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=password_seguro_postgres
N8N_ENCRYPTION_KEY=encryption_key_seguro
N8N_HOST=${N8N_DOMAIN}
N8N_PROTOCOL=https
WEBHOOK_URL=https://${N8N_DOMAIN}/
N8N_PORT=5678

# Queue mode (Redis)
EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379

Protege el archivo:

chmod 600 /opt/n8n/.env

6. Crear el archivo docker-compose.yml

nano /opt/n8n/docker-compose.yml

services:
  postgres:
    image: postgres:16-alpine
    container_name: n8n-postgres
    restart: unless-stopped
    env_file: .env
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - n8n-network

  redis:
    image: redis:7-alpine
    container_name: n8n-redis
    restart: unless-stopped
    volumes:
      - ./data/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - n8n-network

  n8n:
    image: n8nio/n8n:latest
    container_name: n8n-app
    restart: unless-stopped
    env_file: .env
    environment:
      - DB_TYPE=${DB_TYPE}
      - DB_POSTGRESDB_HOST=${DB_POSTGRESDB_HOST}
      - DB_POSTGRESDB_PORT=${DB_POSTGRESDB_PORT}
      - DB_POSTGRESDB_DATABASE=${DB_POSTGRESDB_DATABASE}
      - DB_POSTGRESDB_USER=${DB_POSTGRESDB_USER}
      - DB_POSTGRESDB_PASSWORD=${DB_POSTGRESDB_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_HOST=${N8N_HOST}
      - N8N_PROTOCOL=${N8N_PROTOCOL}
      - WEBHOOK_URL=${WEBHOOK_URL}
      - N8N_PORT=${N8N_PORT}
      - N8N_METRICS=true
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=168
      - EXECUTIONS_MODE=${EXECUTIONS_MODE}
      - QUEUE_BULL_REDIS_HOST=${QUEUE_BULL_REDIS_HOST}
      - QUEUE_BULL_REDIS_PORT=${QUEUE_BULL_REDIS_PORT}
    volumes:
      - ./data/n8n:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - n8n-network

  n8n-worker:
    image: n8nio/n8n:latest
    container_name: n8n-worker
    restart: unless-stopped
    env_file: .env
    environment:
      - EXECUTIONS_MODE=${EXECUTIONS_MODE}
      - QUEUE_BULL_REDIS_HOST=${QUEUE_BULL_REDIS_HOST}
      - QUEUE_BULL_REDIS_PORT=${QUEUE_BULL_REDIS_PORT}
      - DB_TYPE=${DB_TYPE}
      - DB_POSTGRESDB_HOST=${DB_POSTGRESDB_HOST}
      - DB_POSTGRESDB_PORT=${DB_POSTGRESDB_PORT}
      - DB_POSTGRESDB_DATABASE=${DB_POSTGRESDB_DATABASE}
      - DB_POSTGRESDB_USER=${DB_POSTGRESDB_USER}
      - DB_POSTGRESDB_PASSWORD=${DB_POSTGRESDB_PASSWORD}
    command: worker
    depends_on:
      - postgres
      - redis
    networks:
      - n8n-network

  caddy:
    image: caddy:2-alpine
    container_name: n8n-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./data/caddy:/data
      - ./data/caddy:/config
    depends_on:
      - n8n
    networks:
      - n8n-network

networks:
  n8n-network:
    driver: bridge

¿Por qué usar queue mode desde el inicio?

n8n puede ejecutar workflows de dos formas:

Modo directo (default): el contenedor principal ejecuta todo. Si un workflow tarda mucho, bloquea las ejecuciones siguientes.
Modo queue: los trabajos se encolan en Redis y los procesan workers independientes. Puedes tener varios workers, escalarlos horizontalmente y las ejecuciones pesadas no afectan al contenedor principal.

Con el docker-compose.yml de arriba, ya tienes el modo queue activo desde el primer docker compose up.

7. Crear el Caddyfile

nano /opt/n8n/Caddyfile

n8n.tudominio.com {
    reverse_proxy n8n:5678
}

Caddy obtendrá automáticamente un certificado SSL de Let's Encrypt y lo renovará sin intervención manual.

8. Configurar el firewall (UFW)

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
sudo ufw status verbose

9. Iniciar el stack

cd /opt/n8n
docker compose up -d

Verifica que todos los servicios estén funcionando:

docker compose ps

Deberías ver algo como:

Revisa los logs del worker para confirmar que está recibiendo trabajos:

docker compose logs -f n8n-worker

10. Acceder a n8n y configuración inicial

Abre tu navegador en https://n8n.tudominio.com. Verás la pantalla de registro. Crea tu cuenta de administrador:

Email: tu correo
Nombre: tu nombre
Contraseña: una contraseña segura

Ya puedes empezar a crear flujos de trabajo. Todos los workflows se ejecutarán a través del worker.

11. Escalar workers

Si tus workflows crecen, escalar es tan simple como agregar más réplicas del servicio n8n-worker:

docker compose up -d --scale n8n-worker=3

Cada worker adicional toma trabajos de la misma cola en Redis. No necesitas cambiar nada más.

13. Buenas prácticas en producción

Usa etiqueta fija: En lugar de n8nio/n8n:latest, usa una versión específica como n8nio/n8n:1.80.3 para evitar sorpresas con actualizaciones.
Monitoreo: n8n expone métricas Prometheus en /metrics. Puedes integrarlas con un stack de monitoreo.
Backups periódicos: Programa un cron para respaldar los directorios data/postgres, data/redis, data/n8n y data/caddy. Al estar en bind mounts, puedes copiarlos directamente con rsync o tar.
Seguridad: No expongas el puerto 5678 directamente. Caddy ya se encarga del proxy. Si necesitas acceso local, usa una VPN o túneles SSH.
Limpieza de ejecuciones: Las variables EXECUTIONS_DATA_PRUNE=true y EXECUTIONS_DATA_MAX_AGE=168 eliminan automáticamente ejecuciones antiguas después de 7 días.

Conclusión

Tienes n8n corriendo en producción sobre Ubuntu con PostgreSQL como base de datos persistente, Redis como gestor de colas, workers dedicados, SSL automático con Caddy y una estructura lista para escalar. Y todo ejecutándose bajo un usuario del sistema dedicado, no como root.

Este setup con modo queue es el mismo que usamos en entornos reales para automatizar procesos de clientes que requieren alta disponibilidad y rendimiento predecible, desde notificaciones y CRMs hasta integraciones complejas con APIs externas.

Si trabajas con redes o documentación visual de infraestructura, puedes usar Savnet para diseñar los diagramas de tus flujos desplegados. Y si necesitas validar o testear automatizaciones de forma continua, SavFalconEye te ayuda a mantener la confianza en cada despliegue.

¿Te quedó alguna duda? Déjala en los comentarios.

How to Secure a System with mTLS Certificates (Mutual TLS)

Oscar Ricardo Sánche Gutierréz — Thu, 23 Apr 2026 19:12:06 +0000

In the world of modern application security, mTLS (Mutual TLS) has become a fundamental standard for protecting communications between services. Unlike traditional TLS where only the server authenticates, mTLS requires both parties (client and server) to present valid certificates, creating a much more robust security layer.

In this article, I'll show you how to implement mTLS step by step, from certificate generation to configuration in real-world applications.

Diagram created with https://savnet.co

What is mTLS and Why Does It Matter?

mTLS (Mutual TLS) is an extension of the standard TLS protocol that adds mutual authentication. While in traditional TLS only the server presents a certificate, in mTLS both the client and the server must authenticate each other.

Key Benefits:

Strong authentication: Both ends of the communication are verified
MITM attack prevention: Makes man-in-the-middle attacks significantly harder
Zero Trust: Aligns perfectly with Zero Trust architectures
Microservices security: Ideal for service-to-service communications

Common Use Cases:

Internal APIs between microservices
Service-to-service communication in Kubernetes
Payment system connections
Secure B2B communications
Sensitive API access

Step 1: Set Up the Environment

For this tutorial, we'll work on an Ubuntu server that will act as our certificate generator and Certificate Authority (CA). We only need a small server with 512MB RAM and 1 CPU, enough to generate and manage certificates.

We'll need some basic tools:

# Update system
sudo apt update && sudo apt upgrade -y

# Install OpenSSL (if not already installed)
sudo apt install -y openssl curl wget

# Verify OpenSSL version
openssl version

For other operating systems, make sure OpenSSL is installed.

Step 2: Create the Certificate Authority (CA)

The CA is the entity that will issue and sign all our certificates. Let's create a private CA.

2.1 Create working directory

mkdir -p ~/mtls-ca
cd ~/mtls-ca
mkdir -p ca/private ca/certs ca/newcerts
mkdir -p server/private server/certs
mkdir -p client/private client/certs

# Set secure permissions
chmod 700 ca/private server/private client/private

2.2 Generate CA private key and certificate

# Generate CA private key (password-protected)
openssl genrsa -aes256 -out ca/private/ca.key 4096

# Generate self-signed CA certificate
openssl req -new -x509 -days 7300 -sha256 \
  -key ca/private/ca.key \
  -out ca/certs/ca.crt \
  -subj "/C=US/ST=California/L=San Francisco/O=MyCompany/OU=IT/CN=MyCA-Root/emailAddress=admin@mycompany.com"

Explanation of the -subj parameter:

/C=US: Country code (2 letters)
/ST=California: State or province
/L=San Francisco: Locality or city
/O=MyCompany: Your organization name
/OU=IT: Organizational unit
/CN=MyCA-Root: Common name of the CA
/emailAddress=admin@mycompany.com: Contact email

Customize these values with your actual information.

During the process you'll be prompted for:

A password for the private key (store it in a safe place)

2.3 Verify the CA certificate

openssl x509 -in ca/certs/ca.crt -text -noout

You should see detailed information about your CA, including:

Issuer: Your own CA
Validity: 20 years (7300 days)
Key usage: Certifying other keys

Step 3: Generate Server Certificates

Now let's create certificates for our server.

3.1 Create server private key and CSR

cd ~/mtls-ca

# Generate server private key
openssl genrsa -out server/private/server.key 2048

# Create Certificate Signing Request (CSR)
openssl req -new -sha256 \
  -key server/private/server.key \
  -out server/server.csr \
  -subj "/C=US/ST=California/L=San Francisco/O=MyCompany/OU=Web/CN={YOUR DOMAIN OR IP WHERE YOUR WEB APP RUNS}"

Customize the -subj parameter:

/C=US: Your country code
/ST=California: Your state or province
/L=San Francisco: Your locality or city
/O=MyCompany: Your organization
/OU=Web: Organizational unit (e.g., Web, API, etc.)
/CN=api.mydomain.com: IMPORTANT: Your server's domain or IP

3.2 Sign the server certificate with the CA

# Sign the server certificate
openssl x509 -req -days 365 -sha256 \
  -in server/server.csr \
  -CA ca/certs/ca.crt \
  -CAkey ca/private/ca.key \
  -CAcreateserial \
  -out server/certs/server.crt \
  -extfile <(echo -e "basicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth")

# Verify the signed certificate
openssl x509 -in server/certs/server.crt -text -noout

3.3 Create certificate chain file

# Create certificate chain for the server
cat server/certs/server.crt ca/certs/ca.crt > server/certs/server-chain.crt

Step 4: Generate Client Certificates

Let's repeat the process for the client.

4.1 Create client private key and CSR

# Generate client private key
openssl genrsa -out client/private/client.key 2048

# Create CSR for the client
openssl req -new -sha256 \
  -key client/private/client.key \
  -out client/client.csr \
  -subj "/C=US/ST=California/L=San Francisco/O=MyCompany/OU=Clients/CN=app-client-01"

Customize the -subj parameter:

/C=US: Your country code
/ST=California: Your state or province
/L=San Francisco: Your locality or city
/O=MyCompany: Your organization
/OU=Clients: Organizational unit (e.g., Clients, Apps, etc.)
/CN=app-client-01: IMPORTANT: Unique client identifier

4.2 Sign the client certificate

# Sign the client certificate
openssl x509 -req -days 365 -sha256 \
  -in client/client.csr \
  -CA ca/certs/ca.crt \
  -CAkey ca/private/ca.key \
  -CAcreateserial \
  -out client/certs/client.crt \
  -extfile <(echo -e "basicConstraints=CA:FALSE\nkeyUsage=digitalSignature\nextendedKeyUsage=clientAuth")

# Verify the client certificate
openssl x509 -in client/certs/client.crt -text -noout

4.3 Create PKCS#12 file for the client

# Create PKCS#12 (p12/pfx) file for easy import
openssl pkcs12 -export \
  -inkey client/private/client.key \
  -in client/certs/client.crt \
  -certfile ca/certs/ca.crt \
  -out client/certs/client.p12

Step 5: Deploy a "Hello World" with Docker Compose and mTLS

Let's create a simple example using Docker Compose with an Nginx server that responds "Hello World" and is protected with mTLS. Remember, this web app must be deployed using the same domain or IP used when generating the server keys in step 3.1.

5.1 Project structure

Create the following directory structure on your server:

mkdir -p ~/mtls-demo/nginx
cd ~/mtls-demo

5.2 Copy the generated certificates

Copy the certificates we generated in the previous steps:

# Create certificate directory in the project
mkdir -p ~/mtls-demo/certs

# Copy server certificates (in our case they're on the same server)
cp ~/mtls-ca/server/certs/server-chain.crt ~/mtls-demo/certs/
cp ~/mtls-ca/server/private/server.key ~/mtls-demo/certs/

# Copy CA (for client verification)
cp ~/mtls-ca/ca/certs/ca.crt ~/mtls-demo/certs/

5.3 Create the HTML page

Create the file ~/mtls-demo/nginx/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>mTLS - Hello World</title>
    <style>
        body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            height: 100vh;
            margin: 0;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
        }
        .container {
            text-align: center;
            background: rgba(255, 255, 255, 0.1);
            padding: 3rem;
            border-radius: 20px;
            backdrop-filter: blur(10px);
            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
        }
        h1 { font-size: 3rem; margin-bottom: 0.5rem; }
        .cert-info {
            background: rgba(255, 255, 255, 0.15);
            padding: 1rem;
            border-radius: 10px;
            margin-top: 1.5rem;
            font-size: 0.9rem;
        }
        .badge {
            display: inline-block;
            background: #4CAF50;
            color: white;
            padding: 0.3rem 1rem;
            border-radius: 20px;
            font-size: 0.8rem;
            margin-top: 1rem;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>🔒 Hello World!</h1>
        <p>Secure connection established via <strong>mTLS</strong></p>
        <div class="cert-info">
            <p><strong>Authenticated client:</strong> <span id="client-cn">---</span></p>
            <p><strong>Protocol:</strong> TLS 1.3</p>
        </div>
        <div class="badge">✅ mTLS Enabled</div>
    </div>
</body>
</html>

5.4 Configure Nginx with mTLS

Create the file ~/mtls-demo/nginx/default.conf:

server {
    listen 8443 ssl;
    server_name localhost;

    # Server certificates
    ssl_certificate /etc/nginx/certs/server-chain.crt;
    ssl_certificate_key /etc/nginx/certs/server.key;

    # Modern SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # mTLS: verify client
    ssl_client_certificate /etc/nginx/certs/ca.crt;
    ssl_verify_client on;
    ssl_verify_depth 2;

    # Document root
    root /usr/share/nginx/html;
    index index.html;

    location / {
        # Reject if client certificate is not valid
        if ($ssl_client_verify != SUCCESS) {
            return 403 "Access denied: client certificate required\n";
        }

        # Pass client information to the app
        add_header X-Client-CN $ssl_client_s_dn always;
        add_header X-Client-Verify $ssl_client_verify always;

        try_files $uri $uri/ =404;
    }

}

5.5 Create the Docker Compose file

Create the file ~/mtls-demo/docker-compose.yml:

version: '3.8'

services:
  mtls-server:
    image: nginx:alpine
    container_name: mtls-nginx
    ports:
      - "8443:8443"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      - ./nginx/index.html:/usr/share/nginx/html/index.html:ro
      - ./certs/server-chain.crt:/etc/nginx/certs/server-chain.crt:ro
      - ./certs/server.key:/etc/nginx/certs/server.key:ro
      - ./certs/ca.crt:/etc/nginx/certs/ca.crt:ro
    restart: unless-stopped

5.6 Deploy the service

cd ~/mtls-demo

# Start the container
docker compose up -d

# Verify it's running
docker compose ps

# View logs
docker compose logs -f

# Stop the container
docker compose down

5.7 Verify the deployment

Go to your browser and navigate to https://YOUR_WEB_IP_OR_DOMAIN:8443. You should see a 400 error since we haven't configured the browser to send the client certificate yet.

If we test with curl, we'll get a similar result:

Step 6: Successful Tests

6.1 CURL with client certificate

curl -v \
  --cacert ca.crt \
  --cert client.crt \
  --key client.key \
  https://YOUR_WEB_IP_OR_DOMAIN:8443/

You need to save these files in the path where you'll run the curl command. You can get them from the following server paths:

ca.crt => ~/mtls-ca/ca/certs/ca.crt
client.crt => ~/mtls-ca/client/certs/client.crt
client.key => ~/mtls-ca/client/private/client.key

6.2 Chrome with client certificate

Chrome and other browsers can use client certificates for mTLS authentication. To test this, you first need to import the .p12 certificate at the operating system level, since Chrome no longer allows importing them directly from its settings.

Download the certificate from the server:

scp root@server_ip:/root/mtls-ca/client/certs/client.p12 ./client.p12

Import according to your operating system:

On macOS (Keychain Access):

open client.p12

Keychain Access will open. Enter the password you set when creating the PKCS#12 file, and the certificate will be available for Chrome.

On Windows (Certificate Manager):

certmgr.msc

Go to "Personal" → "Certificates"
Right-click → "All Tasks" → "Import..."
Select client.p12 and enter the password

On Linux:

# Convert .p12 to .pem
openssl pkcs12 -in client.p12 -out client.pem -nodes

# Start Chrome with system certificate support
google-chrome --enable-features=PlatformCertificateProvider

You might get an error initially, so it's best to test in an incognito tab or restart the browser so it picks up the newly installed certificate.

Conclusion

Implementing mTLS is one of the best security investments you can make to protect communications between services. With this practical Docker Compose example, you've seen how to:

Create a private CA and generate certificates
Configure Nginx with mTLS in a Docker container
Test with curl with and without a certificate
Test with Chrome by importing the client certificate

This same pattern applies to production environments, Kubernetes microservices, internal APIs, and any communication requiring mutual authentication.

Additional Resources

Did you enjoy this tutorial? Share your experiences implementing mTLS or ask questions in the comments. What other security topics would you like to see in future articles?

Need a server for testing? You can create a Droplet on DigitalOcean using this link and get additional credit: https://m.do.co/c/2c579acd7121

Cómo asegurar un sistema a través de certificados mTLS (Mutual TLS)

Oscar Ricardo Sánche Gutierréz — Thu, 23 Apr 2026 19:08:24 +0000

En el mundo de la seguridad de aplicaciones modernas, mTLS (Mutual TLS) se ha convertido en un estándar fundamental para proteger comunicaciones entre servicios. A diferencia del TLS tradicional donde solo el servidor se autentica, mTLS requiere que ambas partes (cliente y servidor) presenten certificados válidos, creando una capa de seguridad mucho más robusta.

En este artículo te mostraré cómo implementar mTLS paso a paso, desde la generación de certificados hasta la configuración en aplicaciones reales.

Diagrama realizado con https://savnet.co

¿Qué es mTLS y por qué es importante?

mTLS (Mutual TLS) es una extensión del protocolo TLS estándar que añade autenticación mutua. Mientras que en TLS tradicional solo el servidor presenta un certificado, en mTLS tanto el cliente como el servidor deben autenticarse mutuamente.

Beneficios clave:

Autenticación fuerte: Ambos extremos de la comunicación se verifican
Prevención de ataques MITM: Dificulta los ataques de intermediario
Zero Trust: Se alinea perfectamente con arquitecturas Zero Trust
Seguridad en microservicios: Ideal para comunicaciones entre servicios

Casos de uso comunes:

APIs internas entre microservicios
Comunicaciones entre servicios en Kubernetes
Conexiones entre sistemas de pago
Comunicaciones B2B seguras
Acceso a APIs sensibles

Paso 1: Configurar el entorno

Para este tutorial, trabajaremos sobre un servidor Ubuntu que funcionará como nuestro generador de certificados y Autoridad Certificadora (CA). Solo necesitamos un pequeño servidor con 512MB de RAM y 1 CPU, suficiente para generar y gestionar certificados.

Necesitaremos algunas herramientas básicas:

# Actualizar sistema
sudo apt update && sudo apt upgrade -y

# Instalar OpenSSL (si no está instalado)
sudo apt install -y openssl curl wget

# Verificar versión de OpenSSL
openssl version

Para otros sistemas operativos, asegúrate de tener OpenSSL instalado.

Paso 2: Crear la Autoridad Certificadora (CA)

La CA es la entidad que emitirá y firmará todos nuestros certificados. Vamos a crear una CA privada.

2.1 Crear directorio de trabajo

mkdir -p ~/mtls-ca
cd ~/mtls-ca
mkdir -p ca/private ca/certs ca/newcerts
mkdir -p server/private server/certs
mkdir -p client/private client/certs

# Configurar permisos seguros
chmod 700 ca/private server/private client/private

2.2 Generar clave privada y certificado de la CA

# Generar clave privada de la CA (protegida con contraseña)
openssl genrsa -aes256 -out ca/private/ca.key 4096

# Generar certificado autofirmado de la CA
openssl req -new -x509 -days 7300 -sha256 \
  -key ca/private/ca.key \
  -out ca/certs/ca.crt \
  -subj "/C=ES/ST=Madrid/L=Madrid/O=MiEmpresa/OU=IT/CN=MiCA-Root/emailAddress=admin@miempresa.com"

Explicación del parámetro -subj:

/C=ES: Código de país (2 letras)
/ST=Madrid: Estado o provincia
/L=Madrid: Localidad o ciudad
/O=MiEmpresa: Nombre de tu organización
/OU=IT: Unidad organizativa
/CN=MiCA-Root: Nombre común de la CA
/emailAddress=admin@miempresa.com: Email de contacto

Personaliza estos valores con tu información real.

Durante el proceso se te pedirá:

Contraseña para la clave privada (guárdala en un lugar seguro)

2.3 Verificar el certificado de la CA

openssl x509 -in ca/certs/ca.crt -text -noout

Deberías ver información detallada sobre tu CA, incluyendo:

Emisor: Tu propia CA
Validez: 20 años (7300 días)
Uso clave: Certificar otras claves

Paso 3: Generar certificados para el servidor

Ahora crearemos certificados para nuestro servidor.

3.1 Crear clave privada y CSR del servidor

cd ~/mtls-ca

# Generar clave privada del servidor
openssl genrsa -out server/private/server.key 2048

# Crear solicitud de firma de certificado (CSR)
openssl req -new -sha256 \
  -key server/private/server.key \
  -out server/server.csr \
  -subj "/C=ES/ST=Madrid/L=Madrid/O=MiEmpresa/OU=Web/CN={ACA DOMINIO O IP DONDE ESTA TU APP WEB}"

Personaliza el parámetro -subj:

/C=ES: Tu código de país
/ST=Madrid: Tu estado o provincia
/L=Madrid: Tu localidad o ciudad
/O=MiEmpresa: Tu organización
/OU=Web: Unidad organizativa (ej: Web, API, etc.)
/CN=api.midominio.com: IMPORTANTE: El dominio o IP de tu servidor

3.2 Firmar el certificado del servidor con la CA

# Firmar el certificado del servidor
openssl x509 -req -days 365 -sha256 \
  -in server/server.csr \
  -CA ca/certs/ca.crt \
  -CAkey ca/private/ca.key \
  -CAcreateserial \
  -out server/certs/server.crt \
  -extfile <(echo -e "basicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth")

# Verificar el certificado firmado
openssl x509 -in server/certs/server.crt -text -noout

3.3 Crear archivo de cadena de certificados

# Crear cadena de certificados para el servidor
cat server/certs/server.crt ca/certs/ca.crt > server/certs/server-chain.crt

Paso 4: Generar certificados para el cliente

Repetimos el proceso para el cliente.

4.1 Crear clave privada y CSR del cliente

# Generar clave privada del cliente
openssl genrsa -out client/private/client.key 2048

# Crear CSR para el cliente
openssl req -new -sha256 \
  -key client/private/client.key \
  -out client/client.csr \
  -subj "/C=ES/ST=Madrid/L=Madrid/O=MiEmpresa/OU=Clientes/CN=app-client-01"

Personaliza el parámetro -subj:

/C=ES: Tu código de país
/ST=Madrid: Tu estado o provincia
/L=Madrid: Tu localidad o ciudad
/O=MiEmpresa: Tu organización
/OU=Clientes: Unidad organizativa (ej: Clientes, Apps, etc.)
/CN=app-client-01: IMPORTANTE: Identificador único del cliente

4.2 Firmar el certificado del cliente

# Firmar el certificado del cliente
openssl x509 -req -days 365 -sha256 \
  -in client/client.csr \
  -CA ca/certs/ca.crt \
  -CAkey ca/private/ca.key \
  -CAcreateserial \
  -out client/certs/client.crt \
  -extfile <(echo -e "basicConstraints=CA:FALSE\nkeyUsage=digitalSignature\nextendedKeyUsage=clientAuth")

# Verificar el certificado del cliente
openssl x509 -in client/certs/client.crt -text -noout

4.3 Crear archivo PKCS#12 para el cliente

# Crear archivo PKCS#12 (p12/pfx) para fácil importación
openssl pkcs12 -export \
  -inkey client/private/client.key \
  -in client/certs/client.crt \
  -certfile ca/certs/ca.crt \
  -out client/certs/client.p12

Paso 5: Desplegar un "Hola mundo" con Docker Compose y mTLS

Vamos a crear un ejemplo simple de una web usando Docker Compose con un servidor Nginx que responde "Hola mundo" y está protegido con mTLS. Recuerda, esta web debe ser desplegada con el mismo dominio o ip que se uso al generar las llaves del server en el punto 3.1.

5.1 Estructura del proyecto

Crea la siguiente estructura de directorios en tu servidor:

mkdir -p ~/mtls-demo/nginx
cd ~/mtls-demo

5.2 Copiar los certificados generados

Copia los certificados que generamos en los pasos anteriores:

# Crear directorio para certificados en el proyecto
mkdir -p ~/mtls-demo/certs

# Copiar certificados del servidor, en nuestro caso están en el mismo servidor
cp ~/mtls-ca/server/certs/server-chain.crt ~/mtls-demo/certs/
cp ~/mtls-ca/server/private/server.key ~/mtls-demo/certs/

# Copiar CA (para verificar clientes)
cp ~/mtls-ca/ca/certs/ca.crt ~/mtls-demo/certs/

5.3 Crear la página HTML

Crea el archivo ~/mtls-demo/nginx/index.html:

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>mTLS - Hola Mundo</title>
    <style>
        body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            height: 100vh;
            margin: 0;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
        }
        .container {
            text-align: center;
            background: rgba(255, 255, 255, 0.1);
            padding: 3rem;
            border-radius: 20px;
            backdrop-filter: blur(10px);
            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
        }
        h1 { font-size: 3rem; margin-bottom: 0.5rem; }
        .cert-info {
            background: rgba(255, 255, 255, 0.15);
            padding: 1rem;
            border-radius: 10px;
            margin-top: 1.5rem;
            font-size: 0.9rem;
        }
        .badge {
            display: inline-block;
            background: #4CAF50;
            color: white;
            padding: 0.3rem 1rem;
            border-radius: 20px;
            font-size: 0.8rem;
            margin-top: 1rem;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>🔒 ¡Hola Mundo!</h1>
        <p>Conexión segura establecida mediante <strong>mTLS</strong></p>
        <div class="cert-info">
            <p><strong>Cliente autenticado:</strong> <span id="client-cn">---</span></p>
            <p><strong>Protocolo:</strong> TLS 1.3</p>
        </div>
        <div class="badge">✅ mTLS Activado</div>
    </div>
</body>
</html>

5.4 Configurar Nginx con mTLS

Crea el archivo ~/mtls-demo/nginx/default.conf:

server {
    listen 8443 ssl;
    server_name localhost;

    # Certificados del servidor
    ssl_certificate /etc/nginx/certs/server-chain.crt;
    ssl_certificate_key /etc/nginx/certs/server.key;

    # Configuración SSL moderna
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # mTLS: verificar cliente
    ssl_client_certificate /etc/nginx/certs/ca.crt;
    ssl_verify_client on;
    ssl_verify_depth 2;

    # Raíz de documentos
    root /usr/share/nginx/html;
    index index.html;

    location / {
        # Rechazar si el certificado del cliente no es válido
        if ($ssl_client_verify != SUCCESS) {
            return 403 "Acceso denegado: certificado de cliente requerido\n";
        }

        # Pasar información del cliente a la app
        add_header X-Client-CN $ssl_client_s_dn always;
        add_header X-Client-Verify $ssl_client_verify always;

        try_files $uri $uri/ =404;
    }

}

5.5 Crear el Docker Compose

Crea el archivo ~/mtls-demo/docker-compose.yml:

version: '3.8'

services:
  mtls-server:
    image: nginx:alpine
    container_name: mtls-nginx
    ports:
      - "8443:8443"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
      - ./nginx/index.html:/usr/share/nginx/html/index.html:ro
      - ./certs/server-chain.crt:/etc/nginx/certs/server-chain.crt:ro
      - ./certs/server.key:/etc/nginx/certs/server.key:ro
      - ./certs/ca.crt:/etc/nginx/certs/ca.crt:ro
    restart: unless-stopped

5.6 Desplegar el servicio

cd ~/mtls-demo

# Iniciar el contenedor
docker compose up -d

# Verificar que está corriendo
docker compose ps

# Ver logs
docker compose logs -f

# Bajar contenedor
docker compose down

5.7 Verificar el despliegue

Ve al navegador e ingresa a https://IP_O_DOMOINIO_DE_TU_WEB:8443 , deberás ver un error 400 ya que aún no hemos configurado el navegador para enviar el certificado de cliente.

Si probamos con curl nos pasará algo parecido

Paso 6: Pruebas exitosas

6.1 CURL Con certificado de cliente

curl -v \
  --cacert ca.crt \
  --cert client.crt \
  --key client.key \
  https://IP_O_DOMOINIO_DE_TU_WEB:8443/

Los archivos debes guardarlos en la ruta donde ejecutarás el comando curl y los obtienes de las siguientes rutas del servidor:

ca.crt=> ~/mtls-ca/ca/certs/ca.crt
client.crt=> ~/mtls-ca/client/certs/client.crt
client.key=> ~/mtls-ca/client/private/client.key

6.2 Chrome Con certificado de cliente

Chrome y otros navegadores pueden usar certificados de cliente para autenticación mTLS. Para probarlo, primero debes importar el certificado .p12 a nivel del sistema operativo, ya que Chrome ya no permite importarlos directamente desde su configuración.

Descargar el certificado desde el servidor:

scp root@ip_servidor:/root/mtls-ca/client/certs/client.p12 ./client.p12

Importar según tu sistema operativo:

En macOS (Keychain Access):

open client.p12

Se abrirá Keychain Access. Introduce la contraseña que pusiste al crear el PKCS#12 y el certificado quedará disponible para Chrome.

En Windows (Administrador de certificados):

certmgr.msc

Ve a "Personal" → "Certificados"
Haz clic derecho → "Todas las tareas" → "Importar..."
Selecciona client.p12 e introduce la contraseña

En Linux:

# Convertir .p12 a .pem
openssl pkcs12 -in client.p12 -out client.pem -nodes

# Iniciar Chrome con soporte de certificados del sistema
google-chrome --enable-features=PlatformCertificateProvider

Es probable que te genere error al inicio así que lo mejor es probarlo en una pestaña incógnita o reiniciar el navegador para que tome el nuevo certificado instalado.

Conclusión

Implementar mTLS es una de las mejores inversiones en seguridad que puedes hacer para proteger las comunicaciones entre servicios. Con este ejemplo práctico de Docker Compose has visto cómo:

Crear una CA privada y generar certificados
Configurar Nginx con mTLS en un contenedor Docker
Probar desde curl con y sin certificado
Probar desde Chrome importando el certificado de cliente

Este mismo patrón se aplica a entornos de producción, microservicios en Kubernetes, APIs internas y cualquier comunicación que requiera autenticación mutua.

Recursos adicionales

¿Te gustó este tutorial? Comparte tus experiencias implementando mTLS o haz preguntas en los comentarios. ¿Qué otros temas de seguridad te gustaría ver en futuros artículos?

¿Necesitas un servidor para tus pruebas? Puedes crear un Droplet en DigitalOcean usando este enlace y obtener crédito adicional: https://m.do.co/c/2c579acd7121

RustDesk: How to Create a Secure Private Remote Access Network

Oscar Ricardo Sánche Gutierréz — Tue, 31 Mar 2026 00:47:18 +0000

RustDesk is the perfect solution for secure remote access, open-source and under your complete control. In this article I'll show you how to deploy your own server, configure it as a closed network, and secure it for corporate use.

Diagram created with https://savnet.co

RustDesk is an open-source alternative to tools like TeamViewer or AnyDesk, but with a key advantage: you can self-host it. This means:

Complete control over your data
No connection limits
Zero licensing costs (only server costs)

Step 1: Prepare the Server

You'll need a Linux server with Ubuntu 22.04 or 24.04 LTS with:

1 vCPU, 2 GB RAM (enough for dozens of connections)
Ubuntu 22.04 LTS or higher
Fixed public IP

Step 2: Initial Server Configuration

Connect via SSH and update the system:

ssh root@your_server_ip
apt update && apt upgrade -y
timedatectl set-timezone America/New_York  # Adjust to your timezone
reboot

Step 3: Install Docker and Docker Compose

Follow the official Docker installation:

# Install dependencies
apt install -y ca-certificates curl gnupg

# Add official Docker repository
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verify installation
docker --version
docker compose version

Step 4: Prepare RustDesk Structure

mkdir -p /opt/rustdesk-server/data
cd /opt/rustdesk-server

Step 5: Create the docker-compose.yml File

Create nano /opt/rustdesk-server/compose.yml:

services:
  hbbr:
    container_name: hbbr
    image: rustdesk/rustdesk-server:latest
    command: hbbr
    volumes:
      - ./data:/root
    network_mode: "host"
    restart: unless-stopped

  hbbs:
    container_name: hbbs
    image: rustdesk/rustdesk-server:latest
    command: hbbs
    volumes:
      - ./data:/root
    network_mode: "host"
    depends_on:
      - hbbr
    restart: unless-stopped

Important: We use network_mode: "host" because RustDesk needs to see the real host IP to function correctly.

Step 6: Start the Services

# Start services
docker compose up -d

# Verify they're running
docker ps

# View logs
docker compose logs

Step 7: Get the Server Public Key

This key is crucial for clients to trust your server:

cat /opt/rustdesk-server/data/id_ed25519.pub && echo ""

Save the result. It will look something like:

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=

Step 8: Configure the Firewall

Ports needed for RustDesk OSS:

TCP 21115 - Main service
TCP 21116 - ID service
UDP 21116 - For better performance
TCP 21117 - Relay service

Configure UFW on the server:

# Install firewall ufw
apt install -y ufw

# Allow SSH from YOUR public IP
ufw allow from your_admin_ip to any port 22
# IF YOU DON'T HAVE a public IP, allow any origin with
ufw allow 22

# Allow RustDesk ports
ufw allow 21115/tcp
ufw allow 21116/tcp
ufw allow 21116/udp
ufw allow 21117/tcp

# Enable firewall
ufw enable
ufw status verbose

Configure cloud provider firewall:

In your cloud provider panel, create Inbound rules that allow only from your corporate IPs:

Step 9: Configure Computer/Client

On each computer:

Open RustDesk
Go to Settings → Network
Click Unlock Network Settings
Go to Server ID/Relay
Configure:
- ID Server: YourRustServerIP
- Relay Server: YourRustServerIP
- Key: Paste the public key obtained in step 7
- API Server: Leave empty (only for RustDesk Pro)

If you want to quickly use your configuration, click the copy icon in the top right corner, and the paste icon to import:

Ways to Improve Your RustDesk Client Security

RustDesk offers multiple authentication methods to securely control remote access. Here I explain each option:

1. One-time password

Automatically generated for each session and the user must provide it to the remote technician to connect
Length options: 6, 8, or 10 digits
The key changes with each session
Ideal use: Temporary technical support or occasional access

2. Permanent password

Key you specify manually that doesn't change between sessions
Allows continuous access without needing to share new keys
Ideal use: Frequent remote access to your own computer

3. Both passwords

Flexibility to use temporary OR permanent password
Ideal use: Mixed scenarios (personal use + occasional support)

4. Two-Factor Authentication (2FA)

Additional security layer
Options: codes from authenticator app or Telegram bot integration
Ideal use: Computers accessible from public internet

5. Trusted devices

Only applies when using 2FA
Mark specific devices as trusted
Avoids requesting 2FA on each connection from those devices
Improves convenience while maintaining security

6. Additional Security Settings

Password length: Configurable based on security needs
Expiration time: For temporary passwords
Audit logging: Access monitoring

Practical Recommendations:

For frequent personal use: Permanent password + optional 2FA

For technical support: One-time password

For corporate environments: Mandatory 2FA + trusted devices

For maximum security: Combination of methods + audit logging

These methods allow you to balance security and convenience according to your specific needs.

How to Make This a Truly Closed Network

1. Block Access from Public Internet on the RustDesk Server

Don't allow access from any IP in the firewall ufw rules or cloud provider rules. Only allow:

Your office IPs
Your corporate VPN IP
Specific authorized ranges

2. Implement VPN for Remote Access

The most secure way: remote users first connect to the corporate VPN, then access RustDesk.

3. Create Administrative User Without Root:

adduser adminops
usermod -aG sudo adminops

mkdir -p /home/adminops/.ssh
cp /root/.ssh/authorized_keys /home/adminops/.ssh/authorized_keys
chown -R adminops:adminops /home/adminops/.ssh
chmod 700 /home/adminops/.ssh
chmod 600 /home/adminops/.ssh/authorized_keys

# Disable root SSH
if grep -q '^PermitRootLogin' /etc/ssh/sshd_config; then
  sed -i 's/^PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config
else
  echo 'PermitRootLogin no' >> /etc/ssh/sshd_config
fi

sshd -t && systemctl restart ssh

RustDesk Pro: For Advanced Enterprise Needs

The RustDesk version we've configured is excellent for basic remote access, but if you need advanced enterprise features, RustDesk offers a Pro version with additional capabilities:

Centralized user and group management
Granular access control (role-based permissions)
LDAP/Active Directory authentication
Detailed auditing and logs
Priority technical support
Mass management functions

For these organizations, you can check the Pro plans at https://rustdesk.com/pricing/.

Need a cloud server? You can get an Ubuntu Droplet on DigitalOcean using our referral link and receive initial credits to try this tutorial.

Have you implemented RustDesk in your organization? Share your experience in the comments!

RustDesk: Cómo crear una red de acceso remoto segura y privada

Oscar Ricardo Sánche Gutierréz — Tue, 31 Mar 2026 00:35:54 +0000

RustDesk es la solución perfecta para acceso remoto seguro, de código abierto y bajo tu control completo. En este artículo te mostraré cómo desplegar tu propio servidor, configurarlo como una red cerrada y asegurarlo para uso corporativo.

Diagrama realizado con https://savnet.co

RustDesk es una alternativa de código abierto a herramientas como TeamViewer o AnyDesk, pero con una ventaja clave: puedes autoalojarlo. Esto significa:

Control total sobre tus datos
Sin límites de conexión
Costo cero en licencias (solo el servidor)

Paso 1: Preparar el servidor

Necesitarás un servidor Linux con Ubuntu 22.04 o 24.04 LTS con:

1 vCPU, 2 GB RAM (suficiente para decenas de conexiones)
Ubuntu 22.04 LTS o superior
IP pública fija

Paso 2: Configuración inicial del servidor

Conéctate por SSH y actualiza el sistema:

ssh root@tu_ip_servidor
apt update && apt upgrade -y
timedatectl set-timezone America/Bogota  # Ajusta a tu zona horaria
reboot

Paso 3: Instalar Docker y Docker Compose

Sigue la instalación oficial de Docker:

# Instalar dependencias
apt install -y ca-certificates curl gnupg

# Agregar repositorio oficial de Docker
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instalar Docker
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verificar instalación
docker --version
docker compose version

Paso 4: Preparar la estructura de RustDesk

mkdir -p /opt/rustdesk-server/data
cd /opt/rustdesk-server

Paso 5: Crear el archivo docker-compose.yml

Crea nano /opt/rustdesk-server/compose.yml:

services:
  hbbr:
    container_name: hbbr
    image: rustdesk/rustdesk-server:latest
    command: hbbr
    volumes:
      - ./data:/root
    network_mode: "host"
    restart: unless-stopped

  hbbs:
    container_name: hbbs
    image: rustdesk/rustdesk-server:latest
    command: hbbs
    volumes:
      - ./data:/root
    network_mode: "host"
    depends_on:
      - hbbr
    restart: unless-stopped

Importante: Usamos network_mode: "host" porque RustDesk necesita ver la IP real del host para funcionar correctamente.

Paso 6: Levantar los servicios

# Levantar servicios
docker compose up -d

# Verificar que estén corriendo
docker ps

# Ver logs
docker compose logs

Paso 7: Obtener la clave pública del servidor

Esta clave es crucial para que los clientes confíen en tu servidor:

cat /opt/rustdesk-server/data/id_ed25519.pub && echo ""

Guarda el resultado. Se verá algo como:

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=

Paso 8: Configurar el firewall

Puertos necesarios para RustDesk OSS:

TCP 21115 - Servicio principal
TCP 21116 - Servicio de ID
UDP 21116 - Para mejor rendimiento
TCP 21117 - Servicio de relay

Configurar UFW en el servidor:

# Instalar firewall ufw
apt install -y ufw

# Permitir SSH desde TU IP pública
ufw allow from tu_ip_admin to any port 22
# SI NO TIENES IP pública, permite cualquier origen con
ufw allow 22

# Permitir puertos de RustDesk
ufw allow 21115/tcp
ufw allow 21116/tcp
ufw allow 21116/udp
ufw allow 21117/tcp

# Activar firewall
ufw enable
ufw status verbose

Configurar firewall del proveedor cloud:

En el panel de tu proveedor cloud, crea reglas Inbound que permitan solo desde tus IPs corporativas:

Paso 9: Configurar computador/cliente

En cada equipo:

Abre RustDesk
Ve a Settings → Network
Haz click en Unlock Network Settings
Ve a Servidor ID/Relay
Configura:
- ID Server: IpServidorRust
- Relay Server: IpServidorRust
- Key: Pega la clave pública obtenida en el paso 7
- API Server: Déjalo vacío (solo para RustDesk Pro)

Si quieres usar rápidamente tu configuración da click en el icono de copiar en la parte superior derecha, y el icono de pegar para importar:

Formas de mejorar la seguridad de tu computador/cliente RustDesk

RustDesk ofrece múltiples métodos de autenticación para controlar el acceso remoto de forma segura. Aquí te explico cada opción:

1. Contraseña de un solo uso (One-time password)

Se genera automáticamente en cada sesión y el usuario debe suministrarla al técnico remoto para que pueda conectarse.
Opciones de longitud: 6, 8 o 10 dígitos
La clave cambia en cada sesión.
Uso ideal: Soporte técnico puntual o accesos temporales

2. Contraseña permanente (Permanent password)

Clave que especificas manualmente y no cambia entre sesiones
Permite acceso continuo sin necesidad de compartir nuevas claves
Uso ideal: Acceso remoto frecuente a tu propio equipo

3. Combinación de ambos métodos (Both passwords)

Flexibilidad para usar contraseña temporal O permanente
Uso ideal: Escenarios mixtos (uso personal + soporte ocasional)

4. Autenticación en dos factores (2FA)

Capa adicional de seguridad
Opciones: códigos desde app autenticadora o integración con bot de Telegram
Uso ideal: Equipos accesibles desde internet público

5. Dispositivos de confianza (Trusted devices)

Solo aplica cuando usas 2FA
Marcar dispositivos específicos como confiables
Evita solicitar 2FA en cada conexión desde esos dispositivos
Mejora la comodidad manteniendo seguridad

6. Configuraciones de seguridad adicionales

Longitud de contraseña: Configurable según necesidades de seguridad
Tiempo de expiración: Para contraseñas temporales
Registro de auditoría: Monitoreo de accesos

Recomendaciones prácticas:

Para uso personal frecuente: Contraseña permanente + 2FA opcional

Para soporte técnico: Contraseña de un solo uso

Para entornos corporativos: 2FA obligatorio + dispositivos de confianza

Para máxima seguridad: Combinación de métodos + registro de auditoría

Estos métodos te permiten balancear seguridad y conveniencia según tus necesidades específicas.

Cómo convertir esto en una red realmente cerrada

1. Bloquear acceso desde Internet público del servidor RustDesk

No permitas acceso a cualquier ip en las reglas del firewall ufw o del operador cloud. Solo permite:

IPs de tus oficinas
IP de tu VPN corporativa
Rangos específicos autorizados

2. Implementar VPN para acceso remoto

La forma más segura: usuarios remotos primero se conectan a la VPN corporativa, luego acceden a RustDesk.

3. Crear usuario administrativo sin root:

adduser adminops
usermod -aG sudo adminops

mkdir -p /home/adminops/.ssh
cp /root/.ssh/authorized_keys /home/adminops/.ssh/authorized_keys
chown -R adminops:adminops /home/adminops/.ssh
chmod 700 /home/adminops/.ssh
chmod 600 /home/adminops/.ssh/authorized_keys

# Deshabilitar root por SSH
if grep -q '^PermitRootLogin' /etc/ssh/sshd_config; then
  sed -i 's/^PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config
else
  echo 'PermitRootLogin no' >> /etc/ssh/sshd_config
fi

sshd -t && systemctl restart ssh

RustDesk Pro: Para necesidades empresariales avanzadas

La versión RustDesk que hemos configurado es excelente para acceso remoto básico, pero si necesitas funcionalidades empresariales avanzadas, RustDesk ofrece una versión Pro con características adicionales:

Gestión centralizada de usuarios y grupos
Control de acceso granular (permisos por rol)
Autenticación LDAP/Active Directory
Auditoría y logs detallados
Soporte técnico prioritario
Funciones de administración masiva

Para estas organizaciones puedes consultar los planes Pro en https://rustdesk.com/pricing/.

¿Necesitas un servidor en la nube? Puedes obtener un Droplet Ubuntu en DigitalOcean usando nuestro enlace de referido y recibir créditos iniciales para probar este tutorial.

¿Has implementado RustDesk en tu organización? ¡Comparte tu experiencia en los comentarios!

How to Deploy Dokploy on an Ubuntu Server and Create Your First "Hello World" in Node.js

Oscar Ricardo Sánche Gutierréz — Fri, 27 Mar 2026 22:41:28 +0000

Introduction

Dokploy is a self-hosted deployment platform that simplifies containerized application management using Docker Swarm. In this comprehensive tutorial, I'll show you how to install Dokploy on an Ubuntu server, configure security with firewalls, deploy your first Node.js application, and follow production best practices.

Diagram created with https://savnet.co

What You'll Need

Before starting, make sure you have:

An Ubuntu 24.04 LTS server (minimum 2 GB RAM for testing)
SSH access with configured keys
A domain or subdomain (optional but recommended for HTTPS)
Basic terminal and Docker knowledge

Step 1: Prepare Your Ubuntu Server

If you already have an Ubuntu 24.04 LTS server with SSH access, you can skip this step. If you need to create one, follow these recommendations:

Choose a cloud or VPS provider that offers Ubuntu 24.04 LTS
Select a plan with at least 2 GB of RAM for testing
Configure SSH key access instead of password (more secure)
Consider enabling backups and monitoring for production
Note the public IP of your server

If your provider has an integrated firewall (like DigitalOcean Cloud Firewall, AWS Security Groups, etc.), configure the necessary rules from the control panel.

Step 2: Initial Server Configuration

Connect to the server via SSH:

ssh root@YOUR_PUBLIC_IP

Update system and install utilities

apt update && apt upgrade -y
apt install -y curl wget git ufw ca-certificates gnupg lsb-release

Create administrator user (recommended)

adduser deploy
usermod -aG sudo deploy
rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy

Now you can connect with the new user:

ssh deploy@YOUR_PUBLIC_IP

Step 3: Configure Firewall with UFW

Dokploy needs specific ports open. Configure UFW properly:

# Allow SSH first to avoid locking ourselves out
sudo ufw allow OpenSSH

# Open ports needed for Dokploy and applications
sudo ufw allow 80/tcp     # HTTP for Traefik
sudo ufw allow 443/tcp    # HTTPS for Traefik
sudo ufw allow 443/udp    # HTTPS UDP for Traefik
sudo ufw allow 3000/tcp   # Dokploy panel (temporary only)

# Enable firewall
sudo ufw enable
sudo ufw status numbered

Important: Docker can bypass UFW rules because it manipulates iptables directly. If your cloud provider offers an integrated firewall (like DigitalOcean Cloud Firewall, AWS Security Groups, etc.), we recommend configuring it as an additional security layer.

Configure the same firewall rules in your provider's panel:

22/TCP from your IP or trusted range (SSH)
80/TCP from Anywhere (HTTP)
443/TCP from Anywhere (HTTPS)
443/UDP from Anywhere (HTTPS UDP)
3000/TCP temporarily from your IP only (for initial setup)

assets/dropplet-firewall.png

Step 4: Install Dokploy

The official Dokploy installation is straightforward with their script:

curl -sSL https://dokploy.com/install.sh | sudo sh

This script automatically:

Installs Docker if not present
Initializes Docker Swarm
Creates the overlay network dokploy-network
Deploys Postgres, Redis, and Dokploy services
Launches Traefik as reverse proxy
Publishes the panel on port 3000

Step 5: Verify the Installation

Check that everything is working:

# View Docker Swarm services
docker service ls

# View running containers
docker ps

# Verify ports are listening
ss -lntup | grep -E '(:80|:443|:3000)'

Now open your browser and access the Dokploy panel:

http://YOUR_PUBLIC_IP:3000

Complete the initial setup wizard by creating your administrator account.

Step 6: Configure Domain and HTTPS (optional but recommended)

To access your applications with your own domain and HTTPS:

In your DNS provider's panel (Cloudflare, DigitalOcean, AWS Route53, etc.), add your domain if you haven't already.
Create DNS records:
- A record for @ pointing to your server IP
- A record for www pointing to your server IP
- Or a subdomain like dokploy.yourdomain.com

Wait for DNS propagation (may take a few minutes).

Restrict access to port 3000

For security, once Dokploy is configured, restrict access to port 3000:

In your cloud provider's firewall, limit it to your IP only if you need administrative access

Step 7: Deploy Your First "Hello World" Application in Node.js

Let's create a simple Node.js application and deploy it to Dokploy.

7.1 Create the project locally

Create a folder for your project with the following files:

package.json:

{
  "name": "hello-world-dokploy",
  "version": "1.0.0",
  "description": "Hello World application for Dokploy",
  "main": "app.js",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

app.js:

const express = require('express');
const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
  res.json({
    message: 'Hello World from Dokploy!',
    timestamp: new Date().toISOString(),
    environment: process.env.NODE_ENV
  });
});

app.get('/health', (req, res) => {
  res.status(200).send('OK');
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
COPY . .
EXPOSE 3000
USER node
CMD ["node", "app.js"]

docker-compose.yml (for reference):

version: '3.8'
services:
  app:
    build: .
    environment:
      - NODE_ENV=staging
    restart: unless-stopped

7.2 Deploy to Dokploy

Deploy part 1

Deploy part 2

In the Dokploy panel, click Create Project
Give your project a name (e.g., "Tests")
In the project panel, click Create Service and select Application
Name your application: Hello World
Then access your application and in the bottom section Build Type select Dockerfile and then Save.
In the top section you have Provider. For this test we'll select the Drop type, however for real cases the best option is through git repository.
Once Drop is selected, drag to the Zip file area the zip with the code we specified in point 7.1.
Click the Deploy button
Once deployment is complete, it will show the Deployments tab where you should see a green dot and Done indicating the process was successful. You can click View to verify the process.
Now, to deploy our Hello World, go to the Domains tab.
For this test we'll use a free Traefik domain by clicking on the dice icon, specify that the Container Port is 3000 and enable HTTPS with Let's Encrypt provider.
Then click the Create button
When finished, it will give us a URL where we can enter and see our web. Important: since we're using a test domain it will give security warnings. For production environments use your own domain.

7.3 Verify the deployment

Once deployment is complete, access your application:

https://tests-hello-world-puloud-d13d9c-167-172-as2dsaccc234-151.traefik.me/

You should see the JSON "Hello World" message.

Step 8: Production Best Practices

1. Don't build on production server

Dokploy recommends building Docker images in CI/CD (GitHub Actions, GitLab CI) and then deploying the pre-built image. This saves resources and reduces downtime risk.

2. Use health checks

Configure health checks in your applications (like the /health endpoint in our example) so Docker Swarm can monitor status.

3. Configure backups

Configure regular server backups (if your provider offers this feature)
Configure regular database backups
Use docker volume for persistent data

4. Monitoring and logs

# View Dokploy logs
docker service logs dokploy --tail 100 -f

# View application logs
docker service logs hello-world_app --tail 100 -f

# View service status
docker service ps hello-world_app

Conclusion

Dokploy offers a robust, self-hosted solution for deploying applications on Docker Swarm. By implementing it on an Ubuntu server, you get a scalable, secure, and professional infrastructure at an accessible cost.

Need a cloud server? You can get an Ubuntu Droplet on DigitalOcean using our referral link and receive initial credits to try this tutorial.

Additional Resources

Enjoyed this tutorial? Share your experiences deploying applications with Dokploy in the comments or suggest topics for future articles.

Cómo desplegar Dokploy en un servidor Ubuntu y crear tu primer "Hola Mundo" en Node.js

Oscar Ricardo Sánche Gutierréz — Fri, 27 Mar 2026 22:38:03 +0000

Introducción

Dokploy es una plataforma de despliegue auto-hospedada que simplifica la gestión de aplicaciones en contenedores Docker usando Docker Swarm. En este tutorial completo, te mostraré cómo instalar Dokploy en un servidor Ubuntu, configurar seguridad con firewall, desplegar tu primera aplicación Node.js y seguir las mejores prácticas para producción.

Diagrama realizado con https://savnet.co

¿Qué necesitas?

Antes de comenzar, asegúrate de tener:

Un servidor con Ubuntu 24.04 LTS (2 GB de RAM mínimo para pruebas)
Acceso por SSH con claves configuradas
Un dominio o subdominio (opcional, pero recomendado para HTTPS)
Conocimientos básicos de terminal y Docker

Paso 1: Preparar tu servidor Ubuntu

Si ya tienes un servidor Ubuntu 24.04 LTS con acceso SSH, puedes saltar este paso. Si necesitas crear uno, sigue estas recomendaciones:

Elige un proveedor de cloud o VPS que ofrezca Ubuntu 24.04 LTS
Selecciona un plan con al menos 2 GB de RAM para pruebas
Configura acceso SSH con claves en lugar de contraseña (más seguro)
Considera activar backups y monitoreo si es para producción
Anota la IP pública de tu servidor

Si usas un proveedor con firewall integrado (como Cloud Firewall de DigitalOcean, Security Groups de AWS, etc.), configura las reglas necesarias desde el panel de control.

Paso 2: Configuración inicial del servidor

Conéctate al servidor por SSH:

ssh root@TU_IP_PUBLICA

Actualizar sistema e instalar utilidades

apt update && apt upgrade -y
apt install -y curl wget git ufw ca-certificates gnupg lsb-release

Crear usuario administrador (recomendado)

adduser deploy
usermod -aG sudo deploy
rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy

Ahora puedes conectarte con el nuevo usuario:

ssh deploy@TU_IP_PUBLICA

Paso 3: Configurar firewall con UFW

Dokploy necesita puertos específicos abiertos. Configura UFW correctamente:

# Permitir SSH primero para no bloquearnos
sudo ufw allow OpenSSH

# Abrir puertos necesarios para Dokploy y aplicaciones
sudo ufw allow 80/tcp     # HTTP para Traefik
sudo ufw allow 443/tcp    # HTTPS para Traefik
sudo ufw allow 443/udp    # HTTPS UDP para Traefik
sudo ufw allow 3000/tcp   # Panel de Dokploy (solo temporal)

# Activar firewall
sudo ufw enable
sudo ufw status numbered

Importante: Docker puede saltarse reglas de UFW porque manipula iptables directamente. Si tu proveedor de cloud ofrece firewall integrado (como Cloud Firewall de DigitalOcean, Security Groups de AWS, etc.), te recomendamos configurarlo también como capa adicional de seguridad.

Configura las mismas reglas de firewall en el panel de tu proveedor:

22/TCP desde tu IP o rango de confianza (SSH)
80/TCP desde Anywhere (HTTP)
443/TCP desde Anywhere (HTTPS)
443/UDP desde Anywhere (HTTPS UDP)
3000/TCP temporalmente desde tu IP (solo para configuración inicial)

Paso 4: Instalar Dokploy

La instalación oficial de Dokploy es sencilla con su script:

curl -sSL https://dokploy.com/install.sh | sudo sh

Este script automáticamente:

Instala Docker si no está presente
Inicializa Docker Swarm
Crea la red overlay dokploy-network
Despliega servicios de Postgres, Redis y Dokploy
Levanta Traefik como reverse proxy
Publica el panel en el puerto 3000

Paso 5: Verificar la instalación

Comprueba que todo esté funcionando:

# Ver servicios de Docker Swarm
docker service ls

# Ver contenedores en ejecución
docker ps

# Verificar que los puertos estén escuchando
ss -lntup | grep -E '(:80|:443|:3000)'

Ahora abre tu navegador y accede al panel de Dokploy:

http://TU_IP_PUBLICA:3000

Completa el asistente inicial creando tu cuenta de administrador.

Paso 6: Configurar dominio y HTTPS (opcional pero recomendado)

Para acceder a tus aplicaciones con dominio propio y HTTPS:

En el panel de DNS de tu proveedor (Cloudflare, DigitalOcean, AWS Route53, etc.), añade tu dominio si no lo tienes ya.
Crea registros DNS:
- A record para @ apuntando a la IP de tu servidor
- A record para www apuntando a la IP de tu servidor
- O un subdominio como dokploy.tudominio.com

Espera la propagación DNS (puede tomar unos minutos).

Restringir acceso al puerto 3000

Por seguridad, una vez configurado Dokploy, restringe el acceso al puerto 3000:

En el firewall de tu proveedor de cloud, limítala solo a tu IP si necesitas acceso administrativo.

Paso 7: Desplegar tu primera aplicación "Hola Mundo" en Node.js

Vamos a crear una aplicación Node.js simple y desplegarla en Dokploy.

7.1 Crear el proyecto localmente

Crea una carpeta para tu proyecto y los siguientes archivos:

package.json:

{
  "name": "hola-mundo-dokploy",
  "version": "1.0.0",
  "description": "Aplicación Hola Mundo para Dokploy",
  "main": "app.js",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

app.js:

const express = require('express');
const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
  res.json({
    message: '¡Hola Mundo desde Dokploy!',
    timestamp: new Date().toISOString(),
    environment: process.env.NODE_ENV
  });
});

app.get('/health', (req, res) => {
  res.status(200).send('OK');
});

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

Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
COPY . .
EXPOSE 3000
USER node
CMD ["node", "app.js"]

docker-compose.yml (para referencia):

version: '3.8'
services:
  app:
    build: .
    environment:
      - NODE_ENV=staging
    restart: unless-stopped

7.2 Desplegar en Dokploy

Despliegue parte 1

Despliegue parte 2

En el panel de Dokploy, haz clic en Create Project
Dale un nombre a tu proyecto (ej: "Tests")
En el panel de proyecto, haz click en Create Service y selecciona Application
Dale un nombre a tu aplicación: Hello World
Luego accede a tu aplicación y en la sección inferior Build Type selecciona Dockerfile y luego Save.
En la parte superior cuentas con la sección Provider. Para esta prueba seleccionaremos el tipo Drop, sin embargo para casos reales la mejor opción es a través de repositorio git.
Una vez seleccionado Drop, arrastra al área Zip file el zip con el código que especificamos en el punto 7.1.
Haz clic en el botón Deploy
Una vez terminado el despliegue, te mostrará la pestaña Deployments en la cual deberás ver un punto verde y Done que indica que el proceso fue exitoso. Puedes hacer clic en View para verificar el proceso.
Ahora, para desplegar nuestro Hola Mundo, ve a la pestaña Domains.
Para esta prueba usaremos un dominio gratuito de Traefik haciendo click en el icono de un par de dados, especificamos que el Container Port es 3000 y habilitamos el HTTPS con proveedor Let's Encrypt.
Luego haz clic en el botón Create
Al terminar nos dará una URL a la cual podremos ingresar y ver nuestra web. Importante: como estamos usando un dominio de prueba nos dará advertencia de seguridad. Para entornos de producción usa un dominio propio.

7.3 Verificar el despliegue

Una vez completado el despliegue, accede a tu aplicación:

https://tests-hello-world-puloud-d13d9c-167-172-as2dsaccc234-151.traefik.me/

Deberías ver el mensaje JSON de "Hola Mundo".

Paso 8: Buenas prácticas para producción

1. No compilar en el servidor de producción

Dokploy recomienda construir las imágenes Docker en CI/CD (GitHub Actions, GitLab CI) y luego desplegar la imagen ya construida. Esto ahorra recursos y reduce riesgo de downtime.

2. Usar health checks

Configura health checks en tus aplicaciones (como el endpoint /health en nuestro ejemplo) para que Docker Swarm pueda monitorear el estado.

3. Configurar backups

Configura backups regulares de tu servidor (si tu proveedor ofrece esta funcionalidad)
Configura backups de bases de datos regularmente
Usa docker volume para datos persistentes

4. Monitoreo y logs

# Ver logs de Dokploy
docker service logs dokploy --tail 100 -f

# Ver logs de tu aplicación
docker service logs hola-mundo_app --tail 100 -f

# Ver estado de los servicios
docker service ps hola-mundo_app

Conclusión

Dokploy ofrece una solución robusta y auto-hospedada para el despliegue de aplicaciones en Docker Swarm. Al implementarlo en un servidor Ubuntu, obtienes una infraestructura escalable, segura y profesional a un costo accesible.

¿Necesitas un servidor en la nube? Puedes obtener un Droplet Ubuntu en DigitalOcean usando nuestro enlace de referido y recibir créditos iniciales para probar este tutorial.

Recursos adicionales

¿Te gustó este tutorial? Comparte tus experiencias desplegando aplicaciones con Dokploy en los comentarios o sugiere temas para futuros artículos.

Basic Load Balancing for a Web System on DigitalOcean

Oscar Ricardo Sánche Gutierréz — Fri, 06 Mar 2026 20:43:27 +0000

In this article we’ll build a simple and inexpensive load-balanced web setup on DigitalOcean.

The architecture is intentionally minimal:

1 DigitalOcean Load Balancer
2 small droplets
A lightweight web app running with Docker + PHP + Nginx

The goal is to show how quickly you can build a basic scalable web entry point without complex infrastructure.

Architecture diagram created with savnet.co:

Creating the first server

Go to your DigitalOcean account and create a small droplet.

Configuration used in this guide:

Image: Docker latest on Ubuntu 22.04
Region: choose the closest to your users
Authentication: SSH recommended (Password also works)
Hostname: WebServer-1

Once the droplet is ready, connect to the server.

Preparing the server

1. Create a user

adduser web_app
usermod -aG sudo web_app
sudo usermod -aG docker web_app
su - web_app

This user will run the application and manage Docker.

2. Create the application folder

mkdir -p ~/app
cd ~/app

3. Create the application files

`index.php`

A very small script that prints the server IP responding to the request.

<?php

echo 'Hi. From ip '.$_SERVER['SERVER_ADDR'];

`nginx.conf`

Basic Nginx configuration to serve PHP via PHP-FPM.

server {
    listen 80;
    server_name localhost;
    root /var/www/html;
    index index.php;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

`docker-compose.yml`

This setup runs Nginx + PHP-FPM using Docker.

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    container_name: nginx-web
    network_mode: host
    volumes:
      - ./:/var/www/html
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - php-fpm

  php-fpm:
    image: php:8.2-fpm
    container_name: php-app
    network_mode: host
    volumes:
      - ./:/var/www/html

4. Start the application

Run:

docker compose up

If everything is correct you should see the containers starting.

Open the server IP in your browser.

You should see something like:

Hi. From ip 10.x.x.x

Creating the Load Balancer

Now we create the DigitalOcean Load Balancer.

Configure:

HTTP forwarding
Attach WebServer-1

Once created, open the load balancer IP.

You’ll see something similar to this:

Notice that the response shows an internal server IP, because traffic between the load balancer and droplets happens inside DigitalOcean’s network.

Creating the second server faster

Instead of repeating the setup manually, we can create a snapshot of the first droplet.

Then create a new droplet from that snapshot in the same region.

Adding the new node to the Load Balancer

Go back to the Load Balancer configuration and attach the second server.

After about a minute, DigitalOcean will mark the droplet as healthy.

Now refresh the Load Balancer IP multiple times.

You should see responses coming from different internal IPs, meaning traffic is being distributed.

Security recommendations

This example focuses on the basic load balancing setup, but in a real environment you should also:

Add a DigitalOcean firewall
Restrict droplets so they are only reachable from the load balancer
Enable HTTPS
Configure health checks

These small changes significantly improve the security of the system.

Tools used

OBS – screen recording
Kdenlive – video editing
savnet.co – architecture diagrams used in this article