Running the Deployment course project locally

Use this page to run the extracted Dream Catcher project on your computer. The version you have uses either the included SQLite database or a separate PostgreSQL database. Identify that version first, then follow its local setup.

What you need first

Install a supported LTS version of Node.js. Node 24 is recommended and includes npm. Prepare a key and model name for the provider imported by your project.

The PostgreSQL version also needs a reachable PostgreSQL database and its connection string, the postgresql:// URL that names its user, password, host, and database. A hosted PostgreSQL database works if you do not run one locally. The SQLite version includes its database file and does not need a separate database service.

JunoWhat you need first Install Node.js LTS and have your AI provider key ready before anything else.

If your version uses PostgreSQL, create that database first and keep its connection string to hand. The app cannot start without it.

JunoWhat you need first Node includes npm, so one install covers the tooling. Only the later version needs a separate database, reached through a connection string of the shape postgresql://user:password@host:5432/database, from a local install or a hosted service.

JunoWhat you need first The SQLite version starts from its bundled database file. The PostgreSQL version connects and creates its tables before Express listens, so network access, credentials, and TLS have to work before npm start can succeed.

Identify the version you extracted

If the extracted project includes dreams.db, use the SQLite instructions. It does not need a separate database service. If its server expects DATABASE_URL, use the PostgreSQL instructions and prepare a reachable PostgreSQL database.

The dependencies in package.json confirm it: pg appears in the PostgreSQL version, and the native SQLite driver sqlite3 appears in the earlier one. The import in config/database.js shows which database module the server actually uses.

Open a terminal in the folder containing package.json:

$ cd path-to-your-downloaded-project

The bundled README is stale

The README in the downloads describes a Claude and SQLite application even after the code has moved to OpenAI or Gemini and PostgreSQL. Use the downloaded package.json, imports, and server files as the authority.

JunoIdentify the version you extracted Look for dreams.db, or a server that expects DATABASE_URL. That tells you whether to follow the SQLite or the PostgreSQL instructions, so check it before you configure anything.

JunoIdentify the version you extracted The migration changes both the database and the environment values the app needs, so identify the version before configuring it. Trust the extracted code and package.json rather than the README, which describes an older snapshot.

JunoIdentify the version you extracted Read the dependencies: pg means PostgreSQL, and sqlite3 means the earlier SQLite version. The import in the database config shows which one is live, whatever else ships in the folder.

Load a local .env file

The downloaded server reads process.env, but its start command does not load a local .env file. Open package.json and change:

"start": "node server.js"

to:

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

This uses Node's built-in environment-file support without adding another dependency. Node stops with an error if the file named by --env-file is missing, and variables already set in your shell take precedence over the file's values. The Intro to AI Engineering project needs the same --env-file change for its backend.

Make sure .gitignore contains both lines:

.env
node_modules/

Check the spelling of both lines in the downloaded file before you commit. The Git handbook covers why these entries matter in ignoring files and good habits.

JunoLoad a local .env file Add --env-file=.env to the start script so Node reads your settings file.

Then check that .gitignore lists .env and node_modules/, so your keys and installed packages stay out of Git.

JunoLoad a local .env file The server reads process.env, but nothing loads your local file into it. Node's built-in --env-file flag does that loading without a new dependency, so the one-line script change is the whole fix.

JunoLoad a local .env file Unlike a loader that skips a missing file silently, --env-file stops Node at startup, so a wrong path fails loudly. A variable already set in your shell wins over the same name in the file, so an old export from an earlier session keeps its value until you unset it.

Run the SQLite version

The Push to GitHub snapshot imports the OpenAI implementation by default. Create .env beside package.json:

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

DATABASE_PATH is optional. Without it, the server uses dreams.db in the project folder. If you set a custom path, make sure its directory exists and is writable.

Install the locked dependencies and start the server. npm ci installs exactly the versions in the lockfile, and the native SQLite package needs a clean install because it is built for your operating system and Node version:

$ npm ci
$ npm start

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

Server running on http://localhost:3001

Open http://localhost:3001/, or the port you put in .env. Stop the server with Ctrl+C.

The project also contains a Gemini implementation, but the route imports the OpenAI file by default. If you follow the course's provider-switching code, use GEMINI_API_KEY and optional GEMINI_MODEL instead.

JunoRun the SQLite version Create .env, run npm ci and npm start, then open port 3001 in your browser.

The database file already comes with the project, so there is nothing else to set up.

JunoRun the SQLite version The imported provider file decides which AI variables you need, so match the names to the import. A working page and dream list prove the database works but say nothing about the AI request, so create a new dream to confirm the provider as well.

JunoRun the SQLite versionsqlite3 is a native module built for your operating system and Node version, so an install copied from another machine fails to load. npm ci from a clean extraction on the recommended LTS installs it correctly; fix a failed install before changing database paths or provider settings.

Run the PostgreSQL version

The later project replaces SQLite with PostgreSQL. Create a database first, then add its connection string to .env along with the AI configuration:

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

Then run:

$ npm ci
$ npm start

The final project initializes its tables before listening, so Server running on http://localhost:3001 appears only once the database answers. If the database is unreachable or rejects its TLS settings, startup stops with Failed to initialize database: followed by the error. The error text points at the cause: ENOTFOUND means the hostname did not resolve, password authentication failed means the credentials, and an SSL or TLS message means the encryption settings. The course code requests an SSL connection, which suits a hosted database; if your local PostgreSQL has no TLS, the connection settings need to match it.

The /health endpoint checks the connection after startup:

http://localhost:3001/health

A healthy server answers with JSON that includes "status": "ok" and "db": "connected". If the database drops out later, the same URL returns "db": "disconnected" with the database error message.

Remove the temporary shutdown route

The Terminating Processes & Signals lesson includes a /shutdown endpoint only for testing graceful termination. Follow the lesson instruction to delete that route before sharing or deploying the application. Leaving a public URL that terminates your server is unsafe.

JunoRun the PostgreSQL version Create your database first, put its connection string in .env, start the app, then visit /health and look for "db": "connected".

Remove the temporary shutdown route before you share the app with anyone.

JunoRun the PostgreSQL version Connecting and creating tables happen before Express listens, so a network, credential, or TLS problem stops startup entirely. When the server never prints its Server running line, look at the database first, not the app code.

JunoRun the PostgreSQL version Read the startup error before changing anything: ENOTFOUND is DNS, password authentication failed is credentials, and an SSL complaint is TLS. The pool requests SSL, so a local server without TLS needs its connection settings brought into line with that.

Troubleshooting

OPENAI_API_KEY environment variable is missing or empty: Confirm that the start script contains --env-file=.env, that .env is beside package.json, and that the variable name matches the imported provider file.

The page opens but creating a dream returns an AI error: Check the provider key and model together. No live AI request is needed to verify that the page and existing-dream API work.

SQLite reports a native-module error: Reinstall from a clean extraction with the supported Node LTS release, using npm ci. Do not copy node_modules from another operating system.

PostgreSQL startup fails: Read the error after Failed to initialize database:, then check the full DATABASE_URL, database network access, credentials, and TLS requirements. The final course code requests an SSL connection.

The database is empty after switching versions: SQLite data in dreams.db does not automatically appear in PostgreSQL. Run the course's migration steps or seed the new database separately.

JunoTroubleshooting Check environment loading first, then the provider, then the database, in that order.

SQLite data does not move into PostgreSQL on its own, so an empty dream list after switching is expected until you migrate or seed it.

JunoTroubleshooting Separate dependency issues, provider requests, SQLite paths, and PostgreSQL connectivity before changing the project. Data does not carry itself between the two versions; migrate or seed the new database deliberately.

JunoTroubleshooting Debug in startup order: .env loading, then the SQLite install or the PostgreSQL connection and TLS, then table setup, then the provider request. The first error in the terminal is usually the cause; what follows it is often a consequence.