Ejecutar el proyecto del curso de Deployment localmente

Usa esta página para ejecutar el proyecto Dream Catcher extraído en tu computadora. La versión que tienes usa una base de datos SQLite incluida o una base de datos PostgreSQL separada. Identifica esa versión primero, luego sigue su configuración local.

Lo que necesitas primero

Instala una versión LTS compatible de Node.js. Se recomienda Node 24 e incluye npm. Prepara una clave y un nombre de modelo para el proveedor importado por tu proyecto.

La versión de PostgreSQL también necesita una base de datos PostgreSQL accesible y su cadena de conexión, la URL postgresql:// que nombra el usuario, contraseña, host y base de datos. Una base de datos PostgreSQL alojada funciona si no ejecutas una localmente. La versión de SQLite incluye su archivo de base de datos y no necesita un servicio de base de datos separado.

JunoLo que necesitas primero Instala Node.js LTS y ten tu clave del proveedor de IA lista antes que cualquier otra cosa.

Si tu versión usa PostgreSQL, crea esa base de datos primero y guarda su cadena de conexión a mano. La aplicación no puede iniciarse sin ella.

JunoLo que necesitas primero Node incluye npm, así que una instalación cubre todas las herramientas. Solo la versión posterior necesita una base de datos separada, accesible a través de una cadena de conexión con la forma postgresql://user:password@host:5432/database, desde una instalación local o un servicio alojado.

JunoLo que necesitas primero La versión de SQLite comienza con su archivo de base de datos incluido. La versión de PostgreSQL se conecta y crea sus tablas antes de que Express escuche, por lo que el acceso a la red, las credenciales y TLS deben funcionar antes de que npm start pueda tener éxito.

Identifica la versión que extrajiste

Si el proyecto extraído incluye dreams.db, usa las instrucciones de SQLite. No necesita un servicio de base de datos separado. Si su servidor espera DATABASE_URL, usa las instrucciones de PostgreSQL y prepara una base de datos PostgreSQL accesible.

Las dependencias en package.json lo confirman: pg aparece en la versión de PostgreSQL, y el controlador SQLite nativo sqlite3 aparece en la anterior. El import en config/database.js muestra qué módulo de base de datos usa realmente el servidor.

Abre una terminal en la carpeta que contiene package.json:

$ cd path-to-your-downloaded-project

El README incluido está desactualizado

El README en las descargas describe una aplicación Claude y SQLite incluso después de que el código se ha movido a OpenAI o Gemini y PostgreSQL. Usa el package.json descargado, los imports y los archivos del servidor como la autoridad.

JunoIdentifica la versión que extrajiste Busca dreams.db, o un servidor que espere DATABASE_URL. Eso te dice si debes seguir las instrucciones de SQLite o PostgreSQL, así que verifica antes de configurar cualquier cosa.

JunoIdentifica la versión que extrajiste La migración cambia tanto la base de datos como los valores de entorno que la aplicación necesita, así que identifica la versión antes de configurarla. Confía en el código extraído y package.json en lugar del README, que describe una captura anterior.

JunoIdentifica la versión que extrajiste Lee las dependencias: pg significa PostgreSQL, y sqlite3 significa la versión anterior de SQLite. El import en la configuración de la base de datos muestra cuál está en uso, sin importar qué más se envíe en la carpeta.

Carga un archivo .env local

El servidor descargado lee process.env, pero su comando de inicio no carga un archivo .env local. Abre package.json y cambia:

"start": "node server.js"

a:

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

Esto usa el soporte de archivo de entorno integrado de Node sin añadir otra dependencia. Node se detiene con un error si falta el archivo nombrado por --env-file, y las variables ya establecidas en tu shell tienen precedencia sobre los valores del archivo. El proyecto Intro to AI Engineering necesita el mismo cambio de --env-file para su backend.

Asegúrate de que .gitignore contiene ambas líneas:

.env
node_modules/

Verifica la ortografía de ambas líneas en el archivo descargado antes de hacer commit. El manual de Git explica por qué estas entradas importan en ignoring files and good habits.

JunoCarga un archivo .env local Añade --env-file=.env al script de inicio para que Node lea tu archivo de configuración.

Luego verifica que .gitignore lista .env y node_modules/, para que tus claves y paquetes instalados se mantengan fuera de Git.

JunoCarga un archivo .env local El servidor lee process.env, pero nada carga tu archivo local en él. La bandera --env-file integrada de Node hace esa carga sin una nueva dependencia, así que el cambio de script de una línea es la solución completa.

JunoCarga un archivo .env local A diferencia de un cargador que ignora un archivo faltante en silencio, --env-file detiene Node al inicio, por lo que una ruta incorrecta falla ruidosamente. Una variable ya establecida en tu shell gana sobre el mismo nombre en el archivo, así que un export antiguo de una sesión anterior mantiene su valor hasta que lo deconfigures.

Ejecuta la versión de SQLite

La captura Push to GitHub importa la implementación de OpenAI por defecto. Crea .env junto a package.json:

OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=your-model-id
PORT=3001

DATABASE_PATH es opcional. Sin ella, el servidor usa dreams.db en la carpeta del proyecto. Si estableces una ruta personalizada, asegúrate de que su directorio existe y es escribible.

Instala las dependencias bloqueadas e inicia el servidor. npm ci instala exactamente las versiones en el archivo de bloqueo, y el paquete SQLite nativo necesita una instalación limpia porque se compila para tu sistema operativo y versión de Node:

$ npm ci
$ npm start

> [email protected] start
> node --env-file=.env server.js

Server running on http://localhost:3001

Abre http://localhost:3001/, o el puerto que pusiste en .env. Detén el servidor con Ctrl+C.

El proyecto también contiene una implementación de Gemini, pero la ruta importa el archivo de OpenAI por defecto. Si sigues el código de cambio de proveedor del curso, usa GEMINI_API_KEY y GEMINI_MODEL opcional en su lugar.

JunoEjecuta la versión de SQLite Crea .env, ejecuta npm ci y npm start, luego abre el puerto 3001 en tu navegador.

El archivo de base de datos ya viene con el proyecto, así que no hay nada más que configurar.

JunoEjecuta la versión de SQLite El archivo del proveedor importado decide qué variables de IA necesitas, así que haz coincidir los nombres con el import. Una página funcional y una lista de sueños prueban que la base de datos funciona pero no dicen nada sobre la solicitud de IA, así que crea un nuevo sueño para confirmar el proveedor también.

JunoEjecuta la versión de SQLitesqlite3 es un módulo nativo compilado para tu sistema operativo y versión de Node, así que una instalación copiada de otra máquina falla al cargarse. npm ci desde una extracción limpia en el LTS recomendado lo instala correctamente; soluciona una instalación fallida antes de cambiar rutas de base de datos o configuraciones de proveedor.

Ejecuta la versión de PostgreSQL

El proyecto posterior reemplaza SQLite con PostgreSQL. Crea una base de datos primero, luego añade su cadena de conexión a .env junto con la configuración de IA:

DATABASE_URL=postgresql://user:password@host:5432/database
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=your-model-id
PORT=3001

Luego ejecuta:

$ npm ci
$ npm start

El proyecto final inicializa sus tablas antes de escuchar, así que Server running on http://localhost:3001 aparece solo una vez que la base de datos responde. Si la base de datos es inalcanzable o rechaza su configuración de TLS, el inicio se detiene con Failed to initialize database: seguido del error. El texto del error apunta a la causa: ENOTFOUND significa que el nombre de host no se resolvió, password authentication failed significa las credenciales, y un mensaje de SSL o TLS significa la configuración de encriptación. El código del curso solicita una conexión SSL, que se adapta a una base de datos alojada; si tu PostgreSQL local no tiene TLS, la configuración de conexión necesita coincidir con ello.

El endpoint /health comprueba la conexión después del inicio:

http://localhost:3001/health

Un servidor saludable responde con JSON que incluye "status": "ok" y "db": "connected". Si la base de datos se cae más tarde, la misma URL devuelve "db": "disconnected" con el mensaje de error de la base de datos.

Elimina la ruta de apagado temporal

La lección Terminating Processes & Signals incluye un endpoint /shutdown solo para probar la terminación elegante. Sigue la instrucción de la lección para eliminar esa ruta antes de compartir o desplegar la aplicación. Dejar una URL pública que termine tu servidor es inseguro.

JunoEjecuta la versión de PostgreSQL Crea tu base de datos primero, pon su cadena de conexión en .env, inicia la aplicación, luego visita /health y busca "db": "connected".

Elimina la ruta de apagado temporal antes de compartir la aplicación con alguien.

JunoEjecuta la versión de PostgreSQL La conexión y creación de tablas ocurren antes de que Express escuche, así que un problema de red, credenciales o TLS detiene completamente el inicio. Cuando el servidor nunca imprime su línea Server running, mira la base de datos primero, no el código de la aplicación.

JunoEjecuta la versión de PostgreSQL Lee el error de inicio antes de cambiar cualquier cosa: ENOTFOUND es DNS, password authentication failed son credenciales, y una queja de SSL es TLS. El pool solicita SSL, así que un servidor local sin TLS necesita que su configuración de conexión se alinee con eso.

Solución de problemas

OPENAI_API_KEY environment variable is missing or empty: Confirma que el script de inicio contiene --env-file=.env, que .env está junto a package.json, y que el nombre de la variable coincide con el archivo del proveedor importado.

La página abre pero crear un sueño devuelve un error de IA: Verifica la clave del proveedor y el modelo juntos. No se necesita una solicitud de IA en vivo para verificar que la página y la API de sueño existente funcionan.

SQLite reporta un error de módulo nativo: Reinstala desde una extracción limpia con la versión LTS de Node compatible, usando npm ci. No copies node_modules de otro sistema operativo.

El inicio de PostgreSQL falla: Lee el error después de Failed to initialize database:, luego verifica la DATABASE_URL completa, el acceso a la red de la base de datos, las credenciales y los requisitos de TLS. El código del curso final solicita una conexión SSL.

La base de datos está vacía después de cambiar de versión: Los datos de SQLite en dreams.db no aparecen automáticamente en PostgreSQL. Ejecuta los pasos de migración del curso o siembra la nueva base de datos por separado.

JunoSolución de problemas Verifica la carga del entorno primero, luego el proveedor, luego la base de datos, en ese orden.

Los datos de SQLite no se mueven a PostgreSQL por su cuenta, así que una lista de sueños vacía después de cambiar es esperada hasta que migres o siembres.

JunoSolución de problemas Separa los problemas de dependencias, solicitudes de proveedor, rutas de SQLite y conectividad de PostgreSQL antes de cambiar el proyecto. Los datos no se transportan solos entre las dos versiones; migra o siembra la nueva base de datos deliberadamente.

JunoSolución de problemas Depura en orden de inicio: carga de .env, luego la instalación de SQLite o la conexión y TLS de PostgreSQL, luego la configuración de tablas, luego la solicitud del proveedor. El primer error en la terminal es generalmente la causa; lo que sigue es a menudo una consecuencia.