Instalar desde código fuente

Objetivos

• Reunir los requisitos para ejecutar Nod desde su repositorio.
• Entender qué arranca pnpm start.
• Saber dónde queda la clave de Vault en macOS y en Linux.
• Abrir Nod con el enlace de acceso y manejarlo día a día.

Esta forma de instalación sirve para ejecutar Nod en Linux o para modificar su código. En Mac o Windows, la documentación recomienda la app de escritorio. Para un VPS, una máquina virtual o un Mac mini accesible desde otros dispositivos, corresponde el servidor propio.

---

Requisitos

Requisito	Versión o detalle
Node.js	24.21.0 o posterior
pnpm	10.34.5, activado mediante Corepack
Docker	Con Compose v2 y en ejecución. En Mac, por ejemplo, Docker Desktop
Git	Cualquier versión reciente
Conexión de modelo	Credenciales de un servicio soportado, un plan de ChatGPT con inicio de sesión o un servidor de modelos local

Comprueba las versiones antes de empezar:

node --version
docker compose version
git --version

docker compose version debe informar una versión 2.

---

Qué ejecuta pnpm start

El comando instala las dependencias si cambiaron, compila la app web y arranca tres contenedores Docker. Después inicia el servidor de Nod, que sirve la app web en 127.0.0.1.

flowchart LR
    Nav["Tu navegador"] --> Srv["Servidor de Nod<br/>127.0.0.1:4310"]
    Srv --> PG[("PostgreSQL")]
    Srv --> WS["Workspace"]
    Srv --> BR["Navegador de Nod"]
    Srv -. "peticiones de modelo" .-> Prov["Proveedor de modelos"]

• El workspace es donde Nod ejecuta comandos y guarda archivos.
• El navegador es donde visita sitios web.
• Ninguno de los dos recibe las claves de tus proveedores.

---

Instalación paso a paso

1. Obtener el código

git clone https://github.com/n8n-io/nod.git
cd nod

2. La clave de Vault

Nod cifra las claves, los inicios de sesión y las tarjetas que guardas con una clave de Vault. En una instalación nueva no hay que hacer nada:

Sistema	Dónde queda la clave
macOS	En el llavero, en el elemento dev.nod.vault
Linux	En NOD_DATA_ROOT/vault/master-key, que por defecto es .local/vault/master-key

También puedes definir tú mismo NOD_VAULT_KEY en .env. Una clave gestionada de forma explícita se genera así:

openssl rand -base64 32

Guarda la clave con tu respaldo. Sin ella no se pueden leer las credenciales guardadas. Si ya existen datos cifrados, hay que restaurar la clave original; generar una nueva no los recupera. Nod nunca genera una clave nueva cuando ya hay datos cifrados.

3. Activar pnpm e iniciar Nod

corepack enable
pnpm start

pnpm start crea el archivo .env a partir de .env.example, con permisos de lectura solo para tu usuario. Git lo ignora. La primera ejecución descarga dependencias e imágenes.

4. Abrir el enlace de acceso

Cuando el servidor está listo imprime un enlace de este tipo:

http://localhost:4310/#access=…

Ábrelo una vez. El navegador guarda la cookie de acceso y, desde entonces, basta con abrir http://localhost:4310.

5. Completar el onboarding

Conecta un modelo y prueba una primera tarea. El capítulo 5 describe cada pantalla.

sequenceDiagram
    actor Tu as Tú
    participant T as Terminal
    participant D as Docker
    participant N as Servidor de Nod
    Tu->>T: git clone y pnpm start
    T->>D: Arranca PostgreSQL, workspace y navegador
    T->>N: Compila la web e inicia el servidor
    N-->>T: Imprime el enlace con access
    Tu->>N: Abre el enlace una vez
    N-->>Tu: Cookie de acceso y onboarding

---

Acceso desde otros dispositivos

Esta instalación escucha solo en la interfaz loopback del equipo. Para acceder por red hay que configurar un token de servidor y HTTPS, como describe el capítulo 4. Una dirección de escucha distinta de loopback exige NOD_AUTH_TOKEN.

---

Uso diario

Para	Haz esto
Detener Nod	Pulsa Ctrl-C y luego ejecuta docker compose stop para detener los contenedores
Actualizar Nod	Detenlo, ejecuta git pull y después pnpm start
Obtener un enlace nuevo	Borra access-key en la carpeta de datos (.local/ por defecto) y reinicia. Si no la borras, la clave se conserva entre reinicios
Encontrar tus datos	En .local/ (o NOD_DATA_ROOT) y en los volúmenes de Docker
Hacer una copia	Detén Nod y copia la carpeta de datos, los volúmenes de Docker y la clave de Vault

Sin restauración probada. La documentación advierte que para esta forma de instalación todavía no existe un procedimiento de restauración probado. El servidor propio sí tiene comandos de respaldo y restauración (capítulo 14).

Los ajustes van en .env. Nod los lee al arrancar, así que después de cambiarlos hay que detener y volver a iniciar el proceso. En una instalación directa, una variable definida en la shell gana sobre la misma variable de .env. El capítulo 7 lista todas las variables.

Un ejemplo mínimo para elegir el modelo inicial desde .env:

LLM_PROVIDER=google
GEMINI_API_KEY=<your-key>

---

Problemas frecuentes

Mensaje o síntoma	Qué hacer
Use Node.js 24.21.0 or newer.	Instala una versión más reciente de Node.js y vuelve a ejecutar pnpm start
Errores de Docker al arrancar	Comprueba que Docker está en ejecución y que docker compose version informa v2
Clave de Vault ausente o ilegible	Restaura la clave original y revisa sus permisos. No generes una nueva para datos ya cifrados
El puerto está en uso	Define otro PORT en .env. El valor por defecto es 4310

---

Actividad

1. Comprueba las versiones de Node.js, Docker Compose y Git.
2. Clona el repositorio y ejecuta pnpm start.
3. Abre el enlace de acceso y confirma que después funciona http://localhost:4310 sin el fragmento #access.
4. Localiza la clave de Vault de tu sistema y anota dónde la vas a respaldar.

---

Autoevaluación

1. ¿Qué tres contenedores arranca pnpm start?

PostgreSQL, el workspace y el navegador.

2. ¿Dónde queda la clave de Vault en Linux si no defines NOD_VAULT_KEY?

En NOD_DATA_ROOT/vault/master-key, que por defecto es .local/vault/master-key.

3. ¿Cómo se consigue un enlace de acceso nuevo?

Borrando el archivo access-key de la carpeta de datos y reiniciando Nod.

4. ¿Por qué no se puede abrir esta instalación desde otro equipo de la red?

Porque el servidor escucha solo en loopback. El acceso por red requiere un token de servidor y HTTPS.

5. ¿Qué gana cuando una variable está en la shell y también en .env?

En una instalación directa desde código, la variable de la shell.

---

Lista de control

• Tengo Node.js 24.21.0 o posterior, Docker con Compose v2 y Git.
• Ejecuté corepack enable y pnpm start.
• Abrí el enlace de acceso una vez.
• Sé dónde está la clave de Vault y la incluí en mi copia.
• Sé detener Nod con Ctrl-C y docker compose stop.

---

Anterior: Instalar la app de escritorio · Siguiente: Servidor propio con Docker