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 o bien la base de datos SQLite incluida o una base de datos PostgreSQL separada. Identifica la versión primero, luego sigue su configuración local.

Qué necesitas primero

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

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

JunoQué necesitas primero Instala Node.js LTS y ten tu clave de proveedor de IA lista antes que nada. Si tu versión usa PostgreSQL, crea esa base de datos primero; una vez comencé la app antes de que la base de datos existiera, ¡y falló al iniciar cada vez!

JunoQué necesitas primero Node incluye npm, así que una instalación cubre toda la herramienta. Solo la versión posterior necesita una base de datos separada: una cadena de conexión con la forma postgresql://user:password@host:5432/database, desde una instalación local o el nivel gratuito de un servicio alojado.

JunoQué necesitas primero La versión SQLite comienza desde su archivo de base de datos incluido; la de PostgreSQL ni siquiera escuchará hasta que su base de datos sea accesible. Configura el acceso de red, las credenciales y TLS antes de npm start, no después del primer stack trace.

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.

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 de 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, las importaciones y los archivos del servidor como la autoridad.

Las dependencias en package.json confirman la versión: pg aparece en la versión PostgreSQL, un driver SQLite nativo aparece en la anterior, y la importación del archivo del servidor muestra cuál módulo de base de datos está activo.

JunoIdentifica la versión que extrajiste Busca dreams.db o un servidor que quiera DATABASE_URL; eso te dice si debes seguir las instrucciones de SQLite o PostgreSQL. Diez segundos de verificación ahora te ahorran trabajar a través del conjunto de instrucciones incorrecto después.

JunoIdentifica la versión que extrajiste La migración cambia tanto la base de datos como los valores de entorno requeridos, así que identifica antes de configurar. Confía en el código extraído y package.json en lugar del README, que describe una snapshot más antigua.

JunoIdentifica la versión que extrajiste Lee las dependencias en package.json: pg significa la versión PostgreSQL, y un driver SQLite nativo significa la anterior. La importación del archivo del servidor muestra cuál está realmente activo, sin importar qué más venga en la carpeta. Confío en las importaciones en lugar de los READMEs, y esta descarga es un buen ejemplo de por qué.

Carga un archivo .env local

El servidor descargado lee process.env, pero su comando start 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 incorporado de Node sin agregar otra dependencia. Node se detiene con un error si el archivo nombrado por --env-file no existe, y las variables ya configuradas en tu shell tienen precedencia sobre los valores del archivo. El proyecto Intro to AI Engineering necesita el mismo cambio --env-file para su backend.

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

.env
node_modules/

Una snapshot del curso contiene el error tipográfico mode_modules; corrígelo a node_modules/ antes de confirmar tu proyecto. El manual de Git cubre por qué estas entradas importan en ignoring files and good habits.

JunoCarga un archivo .env local Agrega --env-file=.env al script start para que Node lea tu archivo de configuración, y mantén .env y node_modules/ fuera de Git. Mi primera clave filtrada me enseñó esa lección más rápido que cualquier curso.

JunoCarga un archivo .env local El servidor lee process.env, pero nada carga tu archivo local en él. La bandera --env-file incorporada de Node hace ese cargamento sin agregar una dependencia, así que haz el cambio de script de una línea y continúa.

JunoCarga un archivo .env local El paquete dotenv continúa silenciosamente cuando su archivo no existe, mientras que --env-file detiene Node con un error, lo que convierte una configuración errónea silenciosa en una falla inmediata al iniciar. Una variable ya configurada en tu shell siempre tiene precedencia sobre el mismo nombre en el archivo, así que un export anterior de una sesión anterior sigue ganando hasta que lo borres. He perdido tiempo real por uno de esos exports antiguos.

Ejecuta la versión SQLite

La snapshot 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 él, 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 lo necesita, porque se compila para tu sistema operativo y versión de Node:

$ npm ci
$ npm start

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 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 extra para que configures aquí.

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

JunoEjecuta la versión SQLite El driver SQLite es un módulo nativo, compilado para tu exacto sistema operativo y versión mayor de Node, así que una instalación trasladada de otra máquina falla al cargar. npm ci en el LTS recomendado desde una extracción limpia lo reconstruye correctamente. Cuando la instalación falla, arregla eso antes de cambiar rutas de base de datos o configuraciones de proveedor.

Ejecuta la versión PostgreSQL

El proyecto posterior reemplaza SQLite con PostgreSQL. Crea una base de datos primero, luego agrega 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. Si la base de datos no es accesible o rechaza su configuración de TLS, el inicio se detiene con un error de base de datos. 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 pide una conexión SSL, así que un PostgreSQL local sin TLS necesita que ese requisito se ajuste en la cadena de conexión. El endpoint /health verifica la conexión después del inicio:

http://localhost:3001/health

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 no es seguro.

JunoEjecuta la versión PostgreSQL Crea tu base de datos primero, pon su cadena de conexión en .env, inicia la app, luego visita /health para confirmar la conexión. Elimina la ruta de apagado temporal antes de compartir la app con alguien; yo mismo he olvidado ese paso, y no es uno que quieras dejar en una app compartida.

JunoEjecuta la versión PostgreSQL La conexión de base de datos y la inicialización de tabla ocurren antes de que Express escuche, así que problemas de red, credenciales o TLS detienen el inicio completamente. Cuando el servidor nunca imprime su línea de escucha, mira la base de datos primero, no el código de la app.

JunoEjecuta la versión PostgreSQL Lee el error de inicio antes de cambiar nada: ENOTFOUND es DNS, password authentication failed es credenciales, y una queja de SSL es TLS. El código del curso pide SSL, así que un PostgreSQL local sin TLS necesita que la cadena de conexión se ajuste para que coincida. He elegido el incorrecto de esos tres causas más de una vez.

Solución de problemas

OPENAI_API_KEY environment variable is missing or empty: Confirma que el script start 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 activa 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 el release de Node LTS soportado, usando npm ci. No copies node_modules desde otro sistema operativo.

El inicio de PostgreSQL falla: Verifica la DATABASE_URL completa, el acceso de red de la base de datos, las credenciales y los requisitos de TLS. El código del curso final pide una conexión SSL.

La base de datos está vacía después de cambiar versiones: 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 de entorno primero, luego el proveedor, luego la base de datos, en ese orden. Y recuerda que los datos de SQLite no se mueven a PostgreSQL por sí solos; una vez me quedé mirando una lista de sueños vacía durante demasiado tiempo antes de que entendiera eso.

JunoSolución de problemas Separa problemas de dependencia, solicitudes de proveedor, rutas de SQLite y conectividad de PostgreSQL antes de cambiar el proyecto. Los datos no se transportan a sí mismos entre las versiones SQLite y PostgreSQL; 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 configuración de tabla, luego la solicitud del proveedor. El primer error en la terminal es el real; todo lo impreso después es generalmente una consecuencia de esa primera falla.