Módulo 4: Entornos dev, staging y prod en self-hosted

2. Base reproducible: el Self-Hosted AI Starter Kit

Siguiente →

Descripción

Al terminar esta lección vas a poder explicar con tus propias palabras qué es un contenedor y qué es Docker Compose —las dos piezas sobre las que se apoya todo este módulo—, y vas a conocer el Self-Hosted AI Starter Kit, el paquete oficial de n8n que trae n8n, una base de datos, un almacén vectorial y modelos de IA locales, listo para levantar con un comando. Vas a leer su docker-compose.yml línea por línea, entender qué hace cada servicio, y saber por qué es la base reproducible y a costo cero desde la que vamos a derivar los tres entornos.

Esto importa porque todo lo que sigue —los tres entornos aislados, sus claves, sus credenciales— se construye sobre Docker Compose. Si Docker Compose es una caja negra para ti, el resto del módulo se vuelve magia que copias sin entender, y la magia que no entiendes se rompe en el peor momento. Esta lección te da los cimientos: qué corre, cómo corre, y cómo verificar que corre. Y de paso te regala algo valioso por sí solo: una instancia de n8n con modelos de IA locales y gratis, que en el Módulo 5 vas a usar para probar tus workflows con IA sin pagarle un centavo a ningún proveedor.

Conexión con el módulo: la lección 1 te dio el porqué de los entornos. Esta te da la base técnica: el paquete reproducible del que van a nacer los tres. En la lección 3 vas a tomar este stack, entenderlo, y derivar de él tres versiones aisladas —una por entorno—. Piensa en esta lección como conocer bien la receta base antes de cocinar tres platos a partir de ella. No vas a levantar todavía los tres entornos; vas a levantar uno —el kit tal cual viene— para entender de qué está hecho.

Qué es un contenedor, con manzanas

Antes de tocar nada, necesitas dos conceptos. El primero es el contenedor.

Piensa en cómo funcionaba antes instalar un programa complicado en tu computadora. Descargabas el programa, y resultaba que necesitaba una versión específica de otra cosa, que a su vez necesitaba una librería que chocaba con otra que ya tenías instalada para otro programa. Media tarde peleando con dependencias, y al final "en mi máquina funciona pero en la tuya no". Ese infierno tiene nombre, y los contenedores lo resuelven.

Un contenedor es un paquete sellado que trae el programa más todo lo que el programa necesita para correr —su versión exacta de todo, sus librerías, su configuración— empaquetado junto, aislado del resto de tu máquina. Piénsalo como una lonchera completa: no solo el sándwich, sino también el jugo, la servilleta y el tenedor, todo en un solo recipiente cerrado. No importa en qué mesa la abras —tu laptop, la de un compañero, un servidor en la nube—: adentro siempre está exactamente lo mismo, funcionando exactamente igual. Eso es lo que quiere decir que un contenedor es reproducible: se comporta igual en cualquier máquina, porque se lleva su mundo adentro.

Un par de términos que vas a ver y conviene distinguir:

  • Una imagen es la receta o el molde del contenedor: la definición de qué va adentro. Por ejemplo, n8nio/n8n:latest es la imagen oficial de n8n. La imagen es el molde; no corre por sí sola.
  • Un contenedor es una instancia viva de esa imagen: el molde ya llenado y funcionando. De una imagen puedes crear muchos contenedores, igual que de un molde de gelatina sacas muchas gelatinas idénticas. Esta idea —muchos contenedores del mismo molde— es exactamente lo que nos va a dar tres entornos iguales pero separados.
  • Docker es el programa que corre los contenedores en tu máquina. Lo instalaste como prerrequisito de la guía. Es el "horno" donde las loncheras se calientan y funcionan.

La propiedad que hace a los contenedores perfectos para entornos es el aislamiento: un contenedor no ve lo que pasa dentro de otro. Dos contenedores en la misma máquina son como dos loncheras cerradas una al lado de la otra: comparten la mesa, pero lo de adentro de una no se mezcla con lo de adentro de la otra. Cuando en la lección 3 corramos tres instancias de n8n, ese aislamiento es lo que garantiza que un cambio en una no toque a las otras.

Qué es Docker Compose, con manzanas

El segundo concepto es Docker Compose, y nace de un problema práctico.

n8n rara vez corre solo. Para funcionar de verdad necesita una base de datos donde guardar los workflows y las credenciales. Si además quieres IA local, necesitas un servidor de modelos. Si quieres RAG, un almacén vectorial. De golpe no tienes un contenedor, tienes cuatro, y todos tienen que arrancar en el orden correcto, conocerse entre sí y hablarse. Levantar cuatro contenedores a mano, uno por uno, con los comandos exactos y en el orden correcto, cada vez, es tedioso y propenso a errores.

Docker Compose resuelve eso. Es una herramienta que lee un solo archivo —llamado docker-compose.yml— donde declaras todos los contenedores que forman tu sistema, cómo se configura cada uno y cómo se conectan entre sí. Después, con un solo comando, Compose levanta todo el conjunto de una vez, en el orden correcto.

Piénsalo como el director de una orquesta. Cada músico —cada contenedor— sabe tocar su instrumento. Pero para que suene una sinfonía y no un ruido, alguien tiene que decir quién entra cuándo y cómo se coordinan. El docker-compose.yml es la partitura; el comando docker compose up es el director levantando la batuta. Tú no le hablas a cada músico por separado: le hablas al director, una vez, y él coordina a todos.

Vale la pena conocer el vocabulario del archivo, porque lo vas a leer mucho:

  • Un servicio (service) es cada contenedor declarado en el archivo. n8n es un servicio, postgres es otro. Un servicio dice qué imagen usar y cómo configurarla.
  • Un volumen (volume) es un espacio de disco persistente que Docker le da a un contenedor para guardar datos que deben sobrevivir aunque el contenedor se apague. Esto es crucial: por defecto, cuando un contenedor se destruye, todo lo de adentro se pierde —la lonchera se tira—. Un volumen es como un cajón externo conectado a la lonchera: aunque tires la lonchera y traigas una nueva, el cajón —con tus workflows y tu base de datos— sigue ahí. Sin volúmenes, cada vez que reiniciaras n8n perderías todo.
  • Una red (network) es el canal privado por el que los contenedores de un mismo Compose se hablan entre sí. Compose crea una automáticamente, y dentro de ella cada servicio es alcanzable por su nombre: n8n encuentra a la base de datos escribiendo simplemente postgres, sin IP ni configuración de red manual.
  • Un puerto (port) es la ventanilla por la que tu máquina alcanza a un contenedor. Un contenedor está aislado, así que para llegar a él desde tu navegador hay que abrir una ventanilla: 5678:5678 significa "conecta el puerto 5678 de mi máquina con el 5678 de adentro del contenedor". Los puertos van a ser clave en la lección 3, porque tres entornos en la misma máquina no pueden usar todos la misma ventanilla.

Con esos dos conceptos —contenedor y Compose— ya puedes leer el Starter Kit. Vamos a él.

Qué es el Self-Hosted AI Starter Kit

El Self-Hosted AI Starter Kit es un proyecto oficial de n8n: un docker-compose.yml ya armado que levanta, de un tirón, todo lo que necesitas para trabajar con n8n y con IA local, gratis y en tu máquina. Es la manera más rápida y reproducible de tener un n8n "de verdad" corriendo, y por eso lo usamos como base.

Trae cuatro piezas, cada una en su contenedor:

ServicioQué esPara qué sirve en la guía
n8nLa plataforma de automatizaciónCorre order-triage y el resto de los workflows
PostgreSQLUna base de datos robustaGuarda los workflows y las credenciales (mejor que la base de datos por defecto de n8n)
QdrantUn almacén vectorial (vector store)Guarda embeddings para casos de RAG; aquí solo lo conocemos, no lo usamos a fondo
OllamaUn servidor de modelos de IA localesCorre modelos de lenguaje en tu propia máquina, gratis, sin API externa

Dos aclaraciones honestas antes de seguir. La primera: de estas cuatro piezas, las dos que de verdad usa este módulo son n8n y PostgreSQL. Qdrant (el almacén vectorial) y Ollama (los modelos locales) vienen en el kit y son valiosísimos —Ollama es lo que en el Módulo 5 te va a dejar probar workflows con IA a costo cero—, pero para el objetivo de este módulo (aislar entornos) el par n8n + base de datos es lo esencial. En la lección 3 vas a ver que, para no gastar memoria de más, cada entorno va a correr una versión más ligera del stack. Por ahora conoce el kit completo, porque es la base de la que todo deriva.

La segunda: Qdrant es el almacén vectorial que trae el kit oficial. Existen otros —Milvus, por ejemplo— que podrías intercambiar, pero el kit ship con Qdrant. Y los modelos de Ollama: el kit descarga un modelo de la familia Llama la primera vez que corres su workflow de demostración. La versión exacta del modelo cambia con la versión del kit, así que ese dato conviene verificarlo en el repositorio oficial cuando lo uses; puedes descargar otros modelos, como Mistral, con ollama pull mistral. No memorices la versión del modelo: memoriza que es local y gratis.

El docker-compose.yml del kit, por dentro

Vamos a mirar el corazón del kit. No lo vas a escribir tú —lo clonas del repositorio oficial—, pero leerlo con entendimiento es lo que te separa de copiar sin saber. Este es, en forma simplificada y comentada, el esqueleto del docker-compose.yml del Starter Kit. Los valores concretos (imágenes, puertos, volúmenes) son los del kit oficial; lee los comentarios, que son el mapa.

# docker-compose.yml — Self-Hosted AI Starter Kit (esqueleto comentado)

volumes:                 # Los cajones persistentes: sobreviven aunque el contenedor se recree
  n8n_storage:           # Aquí vive la carpeta ~/.n8n: la clave de cifrado y la config
  postgres_storage:      # Aquí viven los datos de la base de datos
  ollama_storage:        # Aquí viven los modelos de IA descargados (pesan varios GB)
  qdrant_storage:        # Aquí viven los embeddings del almacén vectorial

services:

  postgres:                          # La base de datos
    image: postgres:16-alpine        # Imagen oficial de PostgreSQL, versión 16, ligera
    container_name: postgres
    environment:                     # Se llena desde el .env (ver más abajo)
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - postgres_storage:/var/lib/postgresql/data   # Los datos van al cajón persistente
    healthcheck:                     # Docker vigila que la base de datos esté sana
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER}']

  n8n:                               # La plataforma de automatización
    image: n8nio/n8n:latest          # Imagen oficial de n8n, última versión
    container_name: n8n
    ports:
      - 5678:5678                    # La ventanilla: llegas por http://localhost:5678
    environment:
      - DB_TYPE=postgresdb           # n8n usa PostgreSQL, no su base de datos por defecto
      - DB_POSTGRESDB_HOST=postgres  # Encuentra la base de datos por su nombre de servicio
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}   # La llave maestra (Módulo 3)
      - N8N_DIAGNOSTICS_ENABLED=false
      - N8N_PERSONALIZATION_ENABLED=false
    volumes:
      - n8n_storage:/home/node/.n8n  # La carpeta ~/.n8n va al cajón persistente
    depends_on:                      # n8n no arranca hasta que la base de datos esté sana
      postgres:
        condition: service_healthy

  qdrant:                            # El almacén vectorial
    image: qdrant/qdrant
    container_name: qdrant
    ports:
      - 6333:6333
    volumes:
      - qdrant_storage:/qdrant/storage

  ollama-cpu:                        # El servidor de modelos de IA locales (versión CPU)
    profiles: ["cpu"]                # Solo arranca si pides el perfil "cpu" (ver comando)
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - 11434:11434
    volumes:
      - ollama_storage:/root/.ollama

Vamos a las piezas que más importa entender:

volumes (arriba de todo). Los cuatro cajones persistentes. El más importante para nosotros es n8n_storage, montado en /home/node/.n8n dentro del contenedor de n8n: ahí vive la carpeta ~/.n8n, y con ella la clave de cifrado que genera n8n. Recuerda del Módulo 3: esa carpeta guarda secretos, y por eso el .gitignore la ignora. Con Docker, esa carpeta ya no vive suelta en tu disco; vive en un volumen de Docker, todavía más aislado.

postgres. La base de datos. Usa la imagen oficial postgres:16-alpine (la etiqueta alpine quiere decir una variante ligera de Linux, para que el contenedor pese menos). Fíjate que no expone ningún puerto a tu máquina: solo los otros contenedores la alcanzan, por la red privada de Compose. Es deliberado: la base de datos no tiene por qué ser accesible desde tu navegador. El healthcheck es una prueba que Docker corre cada tanto para saber si la base está viva; n8n la usa para no arrancar antes de tiempo.

n8n. El protagonista. Tres detalles clave. Primero, ports: 5678:5678 es la ventanilla: por eso llegas al editor en http://localhost:5678. Segundo, las variables DB_* le dicen que use PostgreSQL en vez de su base de datos por defecto, y que encuentre la base escribiendo simplemente postgres —el nombre del servicio—, sin IP: eso lo resuelve la red de Compose. Tercero, N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY} toma la clave de cifrado del archivo .env. Guarda ese detalle: es exactamente la pieza que en la lección 4 vas a hacer distinta por entorno.

depends_on con condition: service_healthy. Le dice a Compose "no arranques n8n hasta que la base de datos esté sana". Es el director coordinando el orden: primero la base, luego n8n. Sin esto, n8n arrancaría, no encontraría la base lista, y fallaría.

ollama-cpu y su profiles. El servidor de modelos locales. La línea profiles: ["cpu"] es un interruptor: este servicio solo arranca si pides expresamente el perfil cpu al levantar el stack. El kit trae varios perfiles —cpu, gpu-nvidia, gpu-amd— para adaptarse a tu hardware, y así no fuerza a todos a arrancar Ollama si no lo quieren. Lo vas a ver en el comando de abajo.

Ejemplo trabajado: levantar el kit por primera vez

Vamos a levantar el kit tal cual viene, para verlo funcionar y entender de qué está hecho. Recuerda: tú corres estos comandos en tu máquina; esta guía no los ejecuta por ti. Voy a decirte comando por comando qué hace y qué vas a ver.

Paso 1 — Clona el repositorio oficial.

git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit

git clone descarga una copia completa del repositorio a tu máquina; cd te mete a la carpeta que se creó. Qué esperar: una carpeta nueva llamada self-hosted-ai-starter-kit con el docker-compose.yml adentro, y tu terminal ahora "parada" dentro de ella.

Paso 2 — Crea tu archivo .env a partir del ejemplo.

cp .env.example .env

cp copia un archivo; aquí copia la plantilla .env.example a un archivo nuevo .env. Este .env es donde viven los valores concretos —contraseñas, la clave de cifrado— que el docker-compose.yml lee con la sintaxis ${...}. Qué esperar: un archivo .env nuevo, con contenido parecido a este:

POSTGRES_USER=root
POSTGRES_PASSWORD=password
POSTGRES_DB=n8n

N8N_ENCRYPTION_KEY=super-secret-key
N8N_USER_MANAGEMENT_JWT_SECRET=even-more-secret

⚠️ Alto aquí, esto es importante. Esos valores —password, super-secret-key, even-more-secret— son marcadores de ejemplo, no secretos de verdad. Están puestos para que el kit arranque a la primera y puedas probarlo. Para cualquier uso serio tienes que reemplazarlos por valores propios y aleatorios, y ese .env con los valores reales nunca se commitea —igual que aprendiste en el Módulo 3—. La lección 4 le dedica toda su atención a generar claves de verdad y a mantenerlas fuera del repositorio. Por ahora, para esta primera prueba de "que arranque", los valores de ejemplo sirven; solo ten clarísimo que no son para producción.

Paso 3 — Levanta el stack.

docker compose --profile cpu up

docker compose up es el director levantando la batuta: lee el docker-compose.yml, descarga las imágenes que falten, crea los volúmenes y las redes, y arranca los contenedores en orden. El --profile cpu enciende el servicio de Ollama en su versión para CPU (si tienes una GPU compatible, usarías --profile gpu-nvidia o --profile gpu-amd; en una Mac con Apple Silicon, el patrón es distinto y conviene mirar el README del kit).

Qué esperar: la primera vez, esto tarda. Docker descarga varios gigabytes de imágenes y modelos —vas a ver muchas líneas de progreso de descarga; está bien, es normal, no está roto—. Cuando termina, la terminal se queda "ocupada" mostrando los logs de los contenedores corriendo. Entre esas líneas vas a ver un mensaje de n8n indicando que el editor está disponible. Si abres tu navegador en http://localhost:5678, te recibe la pantalla de configuración inicial de n8n. Esa pantalla es la señal de éxito: significa que n8n arrancó, encontró su base de datos y está listo.

Paso 4 — Apagar el stack cuando termines. En la terminal donde corre, presiona Ctrl+C, y luego:

docker compose --profile cpu down

down apaga y elimina los contenedores y la red, pero —y esto es lo tranquilizador— conserva los volúmenes. Tus workflows, tu base de datos y tus modelos siguen en sus cajones persistentes. La próxima vez que levantes el stack, todo está donde lo dejaste. Apagar el contenedor no borra tus datos: para eso están los volúmenes.

Los modelos locales: el as bajo la manga

Vale la pena detenerse en Ollama, porque aunque no sea el foco de este módulo, es la pieza que hace posible una de las promesas más grandes de toda la guía, y conviene entenderla desde ya.

Ollama es un servidor que corre modelos de lenguaje en tu propia máquina. En vez de que el nodo AI Agent de order-triage llame a un proveedor de modelos por internet —y te cobre por cada llamada—, puede llamar a un modelo que vive en el contenedor ollama, en tu laptop, gratis. La primera vez que un workflow usa un modelo, Ollama lo descarga (varios gigabytes, que quedan en el volumen ollama_storage); de ahí en adelante, las llamadas son locales e instantáneas, sin costo ni límite de uso.

¿Por qué es esto un as bajo la manga? Porque probar workflows con IA cuesta dinero cuando cada prueba llama a un proveedor de pago. Si quieres correr order-triage cien veces para probar que clasifica bien, cien llamadas a un proveedor externo suman. Con un modelo local, esas cien pruebas cuestan cero. En el Módulo 5, cuando aprendas a probar workflows con nodos AI Agent a fondo, los modelos locales de Ollama son lo que hace que ese "a costo cero" sea literal. Este módulo solo te presenta la herramienta; el Módulo 5 la explota.

Cómo alcanzas el modelo desde n8n: dentro de la red de Compose, el servicio ollama es alcanzable por su nombre, en el puerto 11434. En el nodo AI Agent configurarías el modelo de Ollama apuntando a http://ollama:11434 (el nombre del servicio, no localhost, porque n8n le habla desde dentro de la red de contenedores). Para descargar un modelo a mano, entras al contenedor de Ollama y usas ollama pull:

docker exec -it ollama ollama pull mistral

docker exec -it ollama entra al contenedor llamado ollama; ollama pull mistral descarga el modelo Mistral. Qué esperar: una barra de progreso de descarga y, al terminar, el modelo disponible para tus workflows. (Qué modelos existen y cuál conviene depende del momento y de tu máquina; consúltalo en el sitio de Ollama.)

Una nota honesta de recursos: los modelos de IA locales piden memoria. Un modelo pequeño corre bien en una laptop moderna; los grandes piden mucha RAM y, para ir rápido, una GPU. Por eso el kit trae los perfiles cpu/gpu-nvidia/gpu-amd. Si tu máquina va justa, usa modelos pequeños en dev para probar la lógica del workflow —que clasifique, que decida—, aunque la calidad del modelo local no iguale a la de un proveedor de producción. Para probar la lógica, un modelo modesto basta; la calidad fina se valida en staging/prod con el modelo de verdad. La imposibilidad de gastar dinero probando vale más que la última gota de calidad en el entorno de juegos.

Por qué esta base es "reproducible" y a costo cero

Vale la pena cerrar con las dos propiedades que hacen a este kit la base ideal para el módulo.

Reproducible. Todo lo que hace falta para correr n8n está declarado en el docker-compose.yml y el .env. No hay pasos manuales escondidos, ni "y además instalé esto a mano y se me olvidó anotarlo". Cualquier persona que clone el repositorio y corra el mismo comando obtiene exactamente el mismo stack. Esa reproducibilidad es la razón por la que Docker Compose es la base correcta para entornos: si dev y prod nacen del mismo archivo, sabes que son iguales por construcción, y las diferencias entre ellos son solo las que declaraste a propósito en su .env. No hay diferencias fantasma.

A costo cero. El kit es software de código abierto: n8n Community, PostgreSQL, Qdrant y Ollama son todos gratis. Los modelos de IA corren en tu propia máquina con Ollama, así que ni siquiera pagas por llamadas a una API de un proveedor de modelos. Todo el camino de esta guía —incluido probar workflows con IA en el Módulo 5— se hace sin sacar la tarjeta. El único costo es el de tu propia máquina corriendo los contenedores.

Con esta base entendida, ya tienes lo que necesitas para el paso grande: convertir un stack en tres stacks aislados, uno por entorno. Eso es la lección 3.

Errores comunes

Commitear el .env con la clave de cifrado (práctico, y el más grave). Qué pasa: alguien clona el kit, copia .env.example a .env, y en un git add . distraído sube el .env —con la clave de cifrado y las contraseñas— al repositorio. Por qué pasa: el .env está justo en la carpeta del proyecto, y git add . atrapa todo lo que ve. Cómo detectarlo: corre git status y busca .env en la lista; si aparece sin estar ignorado, estás a un commit del accidente. Cómo corregirlo: el reflejo del Módulo 3 —.env en el .gitignore desde antes del primer commit, .env.example sí se versiona (sin valores reales)—. Y si los valores del .env son todavía los de ejemplo, no hay secreto que perder aún; el peligro llega en cuanto los reemplazas por reales, así que pon el .gitignore bien antes de ese momento.

Dejar los valores de ejemplo y creer que ya está seguro (conceptual). Qué pasa: alguien levanta el kit con POSTGRES_PASSWORD=password y N8N_ENCRYPTION_KEY=super-secret-key y sigue adelante como si eso fuera una configuración real. Por qué pasa: el kit arranca perfecto con esos valores, así que "funciona" se confunde con "está bien". Cómo detectarlo: si tu clave de cifrado dice literalmente super-secret-key, no es secreta —está en el repositorio público del kit, la conoce todo el mundo—. Cómo corregirlo: reemplaza los valores de ejemplo por valores aleatorios propios antes de cualquier uso que importe. La lección 4 te enseña a generarlos bien.

Confundir apagar el contenedor con borrar los datos (conceptual). Qué pasa: alguien corre docker compose down, ve desaparecer los contenedores, y entra en pánico creyendo que perdió sus workflows. O al revés: quiere empezar de cero y cree que con down ya borró todo, cuando los datos siguen en los volúmenes. Por qué pasa: no se distingue entre el contenedor (efímero) y el volumen (persistente). Cómo detectarlo: corre docker volume ls; si tus volúmenes (..._n8n_storage, ..._postgres_storage) siguen listados, tus datos siguen ahí. Cómo corregirlo: recuerda la regla —el contenedor es la lonchera desechable, el volumen es el cajón que sobrevive—. Para borrar de verdad los datos hace falta docker compose down -v (la -v elimina los volúmenes), y ese comando se usa con plena conciencia de que sí borra.

Ejercicios

Ejercicio 1 — Traduce el docker-compose.yml. Mira el esqueleto del docker-compose.yml del kit de esta lección y responde, sin volver a leer la explicación: (a) ¿por qué el servicio postgres no tiene una sección ports, si n8n necesita hablarle? (b) ¿Qué pasaría con tus workflows si borraras el volumen n8n_storage? (c) ¿Qué hace la línea depends_on: postgres: condition: service_healthy?

Ver solución

(a) Porque postgres solo necesita ser alcanzable por otros contenedores, no por tu navegador. Los contenedores del mismo Compose se hablan por una red privada interna, donde se encuentran por nombre (postgres), sin puertos expuestos. Exponer un puerto es abrir una ventanilla hacia tu máquina, y la base de datos no la necesita: sería incluso menos seguro.

(b) Perderías todo lo que vive en ~/.n8n: la clave de cifrado que n8n generó y la configuración. Como la clave de cifrado se iría, aunque conservaras la base de datos, las credenciales cifradas con esa clave ya no se podrían descifrar. Por eso el volumen es sagrado.

(c) Le dice a Compose que no arranque n8n hasta que la base de datos pase su prueba de salud (healthcheck). Es el director imponiendo el orden: primero la base viva, luego n8n. Evita que n8n arranque, no encuentre la base lista, y falle.

Por qué funciona: si respondiste las tres, ya lees un docker-compose.yml con entendimiento, no como un conjuro. Esa capacidad es la que hace que la lección 3 —tres stacks derivados de este— se sienta natural en vez de mágica.

Ejercicio 2 — Predice el puerto ocupado. Imagina que ya tienes el kit corriendo con n8n en el puerto 5678. Sin apagarlo, intentas levantar un segundo stack idéntico, con otro n8n que también pide el puerto 5678. ¿Qué crees que pasa, y por qué? ¿Qué tendrías que cambiar en el segundo stack para que los dos convivan?

Ver solución

El segundo stack falla al arrancar con un error de puerto ya en uso (algo como "port is already allocated"). La razón: un puerto de tu máquina es una ventanilla única; solo un contenedor puede quedarse con el 5678 a la vez. Dos contenedores no pueden compartir la misma ventanilla.

Para que los dos convivan, el segundo n8n tiene que usar otra ventanilla: por ejemplo, mapear 5679:5678 en vez de 5678:5678. Así el segundo n8n sigue escuchando en su 5678 interno, pero tú lo alcanzas desde http://localhost:5679, sin chocar con el primero.

Por qué funciona: acabas de descubrir tú solo el problema central de correr varios entornos en una máquina —los puertos chocan— y su solución —una ventanilla distinta por entorno—. Es exactamente lo que la lección 3 formaliza con 5678/5679/5680 para dev/staging/prod.

Ejercicio 3 — Distingue imagen, contenedor y volumen. Explica en una frase cada uno, con una analogía propia (distinta a la lonchera y el molde de gelatina), y luego di cuál de los tres es el que no debes perder nunca si guardas la configuración de n8n, y por qué.

Ver solución

No hay una única respuesta; lo importante es que las tres analogías distingan bien: la imagen es la definición o receta (no corre sola), el contenedor es una instancia viva de esa receta (efímera), y el volumen es el almacenamiento persistente conectado al contenedor (sobrevive a su destrucción).

El que no debes perder nunca es el volumen, concretamente n8n_storage. La imagen la puedes volver a descargar cuando quieras (está en internet), y el contenedor lo puedes recrear con un comando. Pero el volumen contiene tu clave de cifrado y tus datos: si se pierde, no hay de dónde recuperarlos. La imagen y el contenedor son reemplazables; el volumen es único.

Por qué funciona: esta distinción es la que evita dos pánicos opuestos —creer que apagar un contenedor borra los datos, y creer que están a salvo cuando en realidad borraste el volumen—. Tener claro cuál de los tres es irreemplazable te da tranquilidad y cuidado en la dosis correcta.

Resumen y siguiente paso

En esta lección conociste las dos piezas sobre las que se apoya todo el módulo. Un contenedor es un paquete sellado con el programa más todo lo que necesita, reproducible y aislado —la lonchera completa—; una imagen es su molde y un volumen es el cajón persistente que sobrevive aunque el contenedor se destruya. Docker Compose es el director de orquesta que lee un solo docker-compose.yml y levanta todos los contenedores coordinados con un comando. Conociste el Self-Hosted AI Starter Kit —n8n + PostgreSQL + Qdrant + Ollama—, leíste su docker-compose.yml por dentro (servicios, volúmenes, puertos, depends_on, perfiles), y lo levantaste con git clone, cp .env.example .env y docker compose --profile cpu up, verificando el éxito en http://localhost:5678. Y grabaste la advertencia de seguridad: los valores del .env de ejemplo no son secretos reales, y el .env con valores propios nunca se commitea.

Antes de avanzar deberías poder: explicar con una analogía qué es un contenedor y qué es Docker Compose; nombrar los cuatro servicios del kit y para qué sirve cada uno; y decir por qué el volumen n8n_storage es el que no se debe perder.

La lección 3 da el salto grande del módulo: tomar este único stack y convertirlo en tres stacks aislados, uno por entorno. Vas a ver cómo Docker aísla dev, staging y prod para que no se toquen entre sí —contenedores, volúmenes, redes y bases de datos separados—, qué mecanismo hace ese aislamiento (el nombre del proyecto de Compose), qué no se comparte jamás entre entornos, y las convenciones de nombres y puertos que evitan confundir un entorno con otro.

Recursos

  • Self-hosted AI Starter Kit — GitHub — el repositorio oficial: el docker-compose.yml real, el .env.example y las instrucciones por tipo de hardware. Confirma aquí la versión exacta del modelo de Ollama y los servicios, porque cambian con el tiempo.
  • Docker Compose overview — Docker Docs — qué es Docker Compose y cómo se estructura un docker-compose.yml; la referencia base para todo el módulo.
  • Docker volumes — Docker Docs — qué es un volumen, por qué sobrevive a la destrucción del contenedor y cómo se gestiona.
  • Docker configuration — n8n Docs — cómo correr n8n en Docker, las variables de la base de datos y de la clave de cifrado que viste en el compose.
  • Ollama — sitio oficial — el servidor de modelos locales del kit; aquí ves qué modelos puedes descargar con ollama pull, útil para el Módulo 5.
← Anterior1. Introducción: qué es un entorno de verdadSiguiente →3. Un Docker Compose por entorno