Ejecutar el proyecto del curso de Deployment en tu computadora

Usa esta página para ejecutar el proyecto Dream Catcher extraído en tu computadora y obtener una interpretación de sueños con tu propia clave de OpenAI. Tu copia guarda los sueños en una de dos bases de datos: un archivo SQLite que viene dentro de la carpeta, o una base de datos PostgreSQL a la que te conectas. La mayoría de la configuración es igual para ambas; la versión PostgreSQL necesita algunas líneas más, marcadas abajo.

Qué necesitas primero

Instala una versión LTS soportada de Node.js. Se recomienda Node 24 e incluye npm.

Verifica que ambos comandos funcionen. Tus números de versión pueden ser diferentes:

$ node --version
v24.18.0
$ npm --version
11.18.0

También necesitas una clave de API de OpenAI, porque el servidor le pide a OpenAI una interpretación por cada sueño. La clave permanece en el servidor, en un archivo de tu computadora, y nunca llega al navegador.

Luego averigua qué versión tienes. Abre una terminal en la carpeta de Dream Catcher extraída, la que contiene package.json y server.js, y lista sus archivos:

$ cd path-to-your-dream-catcher-folder
$ ls
README.md          package.json
config             public
dreams.db          routes
hint.md            server.js
package-lock.json  utils

Si la lista incluye dreams.db, tienes la versión SQLite: la base de datos es ese archivo, y no hay nada más que configurar. Si no hay dreams.db, tienes la versión PostgreSQL, y también necesitas una base de datos PostgreSQL y su cadena de conexión, una URL que comienza con postgresql:// o postgres://. Una base de datos alojada es la opción más simple, como la que configuraste en Render para el deployment del curso. Las bases de datos gratuitas de Render expiran 30 días después de su creación, así que si la tuya desapareció, crea una nueva.

Ignora el README.md en la carpeta. Describe una versión anterior de la aplicación, con un proveedor de IA diferente y puerto distinto.

JunoQué necesitas primero Verifica que node --version y npm --version ambos impriman una versión, y ten lista una clave de API de OpenAI.

Luego ejecuta ls en la carpeta del proyecto. Si ves dreams.db, no necesitas nada más; si no, también necesitas una URL de base de datos PostgreSQL.

JunoQué necesitas primero Un servidor Express hace todo aquí: envía la página a tu navegador, lee y escribe en la base de datos, y llama a OpenAI. Las dos versiones difieren solo en config/database.js, que abre dreams.db en una y se conecta a DATABASE_URL en la otra.

JunoQué necesitas primero El navegador solo llama a las rutas /api/dreams de este servidor, y el cliente de OpenAI se crea dentro del servidor, así que nada copia la clave en código que descargue el navegador. package.json concuerda con la verificación de archivos: sqlite3 en una versión, pg en la otra.

Instala los paquetes

En la misma terminal, instala las versiones exactas que el proyecto lista en su archivo de bloqueo:

$ npm ci

npm termina diciendo cuántos paquetes agregó. También imprime advertencias sobre paquetes deprecados, vulnerabilidades y allow-scripts. Ninguna de ellas detiene el proyecto; déjalas como están.

JunoInstala los paquetes Ejecuta npm ci en la carpeta que contiene package.json, y espera la línea que dice cuántos paquetes fueron agregados.

Las advertencias después de ella son esperadas. Si npm dice que no puede encontrar package.json, estás en la carpeta equivocada.

JunoInstala los paquetesnpm ci instala exactamente lo que package-lock.json registra y se rehúsa a cambiarlo, así que obtienes los mismos paquetes que usó el curso. En la versión SQLite también descarga el controlador SQLite compilado para tu computadora.

JunoInstala los paquetessqlite3 es un módulo nativo, así que su script de instalación descarga una compilación para tu sistema operativo y procesador. Por eso node_modules copiado de otra computadora falla al cargar, y por qué npm nombra sqlite3 en su advertencia allow-scripts.

Haz que npm start lea tu archivo .env

El servidor lee su configuración de process.env, pero el comando start del proyecto no carga un archivo .env, así que el servidor comenzaría sin tu clave y se detendría de inmediato. Abre package.json y cambia:

"start": "node server.js"

a:

"start": "node --env-file=.env server.js"

Node ahora lee .env por sí mismo, una sola vez, antes de que se ejecute el código del servidor. Si falta el archivo, Node se detiene con node: .env: not found.

Luego abre .gitignore. Debe listar .env, así Git nunca guarda tu clave, y node_modules. En la versión SQLite, la segunda línea está mal escrita como mode_modules; corrígela para que lea:

node_modules
.env

Mantén las líneas logs y *.log que ya están. El manual de Git explica por qué estas entradas importan en ignorar archivos y buenas prácticas.

JunoHaz que npm start lea tu archivo .env En package.json, agrega --env-file=.env al script start. Luego verifica que .gitignore liste node_modules y .env, escritos exactamente así.

JunoHaz que npm start lea tu archivo .env En Scrimba y en un host como Render, la configuración ya está en el entorno cuando el servidor comienza. En tu computadora viven en un archivo, y --env-file es la forma integrada de Node para cargarlo, sin paquete extra.

JunoHaz que npm start lea tu archivo .env Una variable ya configurada en tu shell gana sobre el mismo nombre en .env. Si alguna vez exportaste OPENAI_API_KEY en esta terminal, ese valor antiguo es el que obtiene el servidor.

Agrega tu .env e inicia

Crea un archivo llamado .env junto a package.json. La versión SQLite necesita solo la línea de clave; la versión PostgreSQL también necesita la línea DATABASE_URL:

# Solo versión PostgreSQL
DATABASE_URL=postgresql://user:password@host:5432/database

OPENAI_API_KEY=your-openai-key-here

Para PostgreSQL, reemplaza toda la URL de ejemplo con la que te proporciona tu host para conectarte desde fuera de su propia red (en Render, la URL externa en el menú Connect de la base de datos). El servidor usa gpt-4o-mini y el puerto 3001 a menos que agregues líneas OPENAI_MODEL o PORT para elegir otros.

Inicia el servidor:

$ npm start
Server running on http://localhost:3001

La versión PostgreSQL primero imprime Database initialized: se conecta a la base de datos y crea su tabla antes de comenzar a escuchar, así que Server running aparece solo una vez que la base de datos ha respondido. Si la terminal imprime Failed to initialize database: en su lugar, el servidor se ha detenido; la solución de problemas abajo coincide con el error después. En la versión PostgreSQL, también puedes abrir http://localhost:3001/health; una conexión que funciona responde con JSON que incluye "status":"ok" y "db":"connected".

Abre http://localhost:3001. La página muestra Add a New Dream y, bajo Your Dream Journal, "No dreams yet", porque ambas bases de datos comienzan vacías. Describe un sueño y haz clic en Get Interpretation. El botón dice Interpreting... mientras OpenAI escribe, y luego tu sueño aparece en el diario con su interpretación.

Si la interpretación falla, la página muestra un error: "Network error. Please check your connection and try again." en la versión SQLite, que muestra ese mensaje para cada fallo, o "AI service temporarily unavailable." en la versión PostgreSQL. De cualquier forma, mira la terminal, no tu conexión. La razón sigue a OpenAI API error:, encima de un bloque largo de detalles; la solución de problemas abajo coincide con cada uno.

Detén el servidor con Ctrl+C. Node lee .env solo cuando el servidor comienza, así que reinícialo después de cualquier cambio a .env. La versión PostgreSQL aún tiene la ruta de prueba /shutdown de la lección, que detiene el servidor cuando se abre; elimínala antes de desplegar.

JunoAgrega tu .env e inicia Pon tu clave, y para PostgreSQL tu URL de base de datos, en .env. Ejecuta npm start, espera a Server running, y abre http://localhost:3001. Agrega un sueño y haz clic en Get Interpretation.

Si la página muestra un error, lee la terminal: la razón está impresa allí.

JunoAgrega tu .env e inicia Ver la página prueba que Express la está sirviendo y la base de datos se abrió. La interpretación es el primer momento en que el servidor llama a OpenAI, así que un sueño nuevo en el diario es lo que prueba que tu clave funciona.

JunoAgrega tu .env e inicia El app.js de la versión SQLite lee una variable data indefinida cuando el servidor responde con un error, así que el ReferenceError cae en su catch de error de red. El grupo de PostgreSQL siempre solicita una conexión encriptada; un servidor PostgreSQL en tu propia computadora generalmente tiene la encriptación desactivada, así que pg se detiene con The server does not support SSL connections.

Solución de problemas

OpenAIError: The OPENAI_API_KEY environment variable is missing or empty cuando inicia: El servidor se detuvo antes de poder escuchar; el mensaje viene justo después de algunas líneas señalando hacia openai/index.mjs. Verifica que el script start contenga --env-file=.env, que .env esté junto a package.json, y que el nombre sea exactamente OPENAI_API_KEY.

node: .env: not found: El script start es correcto, pero no hay .env en la carpeta desde la que iniciaste. Créalo junto a package.json.

401 Incorrect API key provided: La clave llegó a OpenAI, pero OpenAI no la aceptó. Cópiala de nuevo desde tu cuenta de OpenAI, guarda .env, y reinicia el servidor.

429 You exceeded your current quota: La clave funciona, pero la cuenta no tiene crédito para gastar. Agrega crédito bajo Billing en tu cuenta de OpenAI, luego intenta de nuevo.

The model ... does not exist: OpenAI planea cerrar gpt-4o-mini el 14 de enero de 2027. Después de eso, agrega una línea OPENAI_MODEL a .env con el reemplazo que la página de deprecaciones de OpenAI menciona, y reinicia.

Error: Could not locate the bindings file (versión SQLite): El controlador SQLite para tu computadora falta. Elimina node_modules y ejecuta npm ci de nuevo en esta carpeta. No copies node_modules desde otra computadora.

Failed to initialize database: con ENOTFOUND: El nombre de host en DATABASE_URL no existe en tu red. Verifica que hayas reemplazado la URL de ejemplo completa, y que hayas copiado la URL externa, no una interna que funcione solo dentro de la red de tu host.

Failed to initialize database: con ECONNREFUSED: Nada respondió en esa dirección. Si el error nombra el puerto 5432 en tu propia computadora (::1 o 127.0.0.1), DATABASE_URL falta de .env o apunta a un PostgreSQL que no está ejecutándose.

Failed to initialize database: con password authentication failed: El nombre de usuario o contraseña en DATABASE_URL es incorrecto. Copia la URL de nuevo desde tu host de base de datos.

Failed to initialize database: con The server does not support SSL connections: Estás usando un servidor PostgreSQL sin encriptación, usualmente uno en tu propia computadora. Para uso local solamente, agrega ?sslmode=disable al final de DATABASE_URL, o usa una base de datos alojada en su lugar.

JunoSolución de problemas Lee la terminal, no la página. Encuentra la primera línea que contenga Error y haz coincidir sus palabras con un encabezado en negrita arriba. Luego corrige .env o el archivo nombrado, y ejecuta npm start de nuevo.

JunoSolución de problemas Cada problema se muestra en su propio momento: una clave faltante o .env tan pronto como inicias, un problema de base de datos antes de Server running, y un problema de clave, crédito o modelo solo cuando haces clic en Get Interpretation.

JunoSolución de problemas El cliente de OpenAI se construye mientras server.js importa sus rutas, así que una clave faltante detiene Node antes de que se ejecute cualquier línea de server.js. Una clave incorrecta pasa esa verificación y falla solo en la primera solicitud, con un 401.