Running the Deployment course project locally

Use this page to run the extracted Dream Catcher project on your computer and get a dream interpretation with your own OpenAI key. Your copy keeps its dreams in one of two databases: a SQLite file that comes inside the folder, or a PostgreSQL database you connect to. Most of the setup is the same for both; the PostgreSQL version needs a few more lines, marked below.

What you need first

Install a supported LTS version of Node.js. Node 24 is recommended and includes npm.

Check that both commands work. Your version numbers may be different:

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

You also need an OpenAI API key, because the server asks OpenAI for each interpretation. The key stays on the server, in a file on your computer, and never reaches the browser.

Then find out which version you have. Open a terminal in the extracted Dream Catcher folder, the one containing package.json and server.js, and list its files:

$ 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

If the list includes dreams.db, you have the SQLite version: the database is that file, and there is nothing else to set up. If there is no dreams.db, you have the PostgreSQL version, and you also need a PostgreSQL database and its connection string, a URL that starts with postgresql:// or postgres://. A hosted database is the simplest choice, such as the one you set up on Render for the course's deployment. Render's free databases expire 30 days after they are created, so if yours is gone, create a new one.

Ignore the README.md in the folder. It describes an older version of the app, with a different AI provider and port.

JunoWhat you need first Check that node --version and npm --version both print a version, and have an OpenAI API key ready.

Then run ls in the project folder. If you see dreams.db, you need nothing else; if not, you also need a PostgreSQL database URL.

JunoWhat you need first One Express server does everything here: it sends the page to your browser, reads and writes the database, and calls OpenAI. The two versions differ only in config/database.js, which opens dreams.db in one and connects to DATABASE_URL in the other.

JunoWhat you need first The browser only ever calls this server's /api/dreams routes, and the OpenAI client is created inside the server, so nothing copies the key into code the browser downloads. package.json agrees with the file check: sqlite3 in one version, pg in the other.

Install the packages

In the same terminal, install the exact versions the project lists in its lockfile:

$ npm ci

npm finishes by saying how many packages it added. It also prints warnings about deprecated packages, vulnerabilities, and allow-scripts. None of them stops the project; leave them as they are.

JunoInstall the packages Run npm ci in the folder that contains package.json, and wait for the line that says how many packages were added.

The warnings after it are expected. If npm says it cannot find package.json, you are in the wrong folder.

JunoInstall the packagesnpm ci installs exactly what package-lock.json records and refuses to change it, so you get the same packages the course used. In the SQLite version it also fetches the SQLite driver built for your computer.

JunoInstall the packagessqlite3 is a native module, so its install script downloads a build for your operating system and processor. That is why node_modules copied from another computer fails to load, and why npm names sqlite3 in its allow-scripts warning.

Make npm start read your .env file

The server reads its settings from process.env, but the project's start command does not load a .env file, so the server would start without your key and stop straight away. Open package.json and change:

"start": "node server.js"

to:

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

Node now reads .env itself, once, before the server code runs. If the file is missing, Node stops with node: .env: not found.

Then open .gitignore. It should list .env, so Git never saves your key, and node_modules. In the SQLite version, the second line is misspelled mode_modules; correct it so it reads:

node_modules
.env

Keep the logs and *.log lines that are already there. The Git handbook explains why these entries matter in ignoring files and good habits.

JunoMake npm start read your .env file In package.json, add --env-file=.env to the start script. Then check that .gitignore lists node_modules and .env, spelled exactly like that.

JunoMake npm start read your .env file On Scrimba and on a host such as Render, the settings are already in the environment when the server starts. On your computer they live in a file, and --env-file is Node's built-in way to load it, with no extra package.

JunoMake npm start read your .env file A variable already set in your shell wins over the same name in .env. If you once exported OPENAI_API_KEY in this terminal, that old value is the one the server gets.

Add your .env and start

Create a file called .env beside package.json. The SQLite version needs only the key line; the PostgreSQL version also needs the DATABASE_URL line:

# PostgreSQL version only
DATABASE_URL=postgresql://user:password@host:5432/database

OPENAI_API_KEY=your-openai-key-here

For PostgreSQL, replace the whole example URL with the one your host gives you for connecting from outside its own network (on Render, the external URL in the database's Connect menu). The server uses gpt-4o-mini and port 3001 unless you add OPENAI_MODEL or PORT lines to choose others.

Start the server:

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

The PostgreSQL version first prints Database initialized: it connects to the database and creates its table before it starts listening, so Server running appears only once the database has answered. If the terminal prints Failed to initialize database: instead, the server has stopped; the troubleshooting below matches the error after it. In the PostgreSQL version, you can also open http://localhost:3001/health; a working connection answers with JSON that includes "status":"ok" and "db":"connected".

Open http://localhost:3001. The page shows Add a New Dream and, under Your Dream Journal, "No dreams yet", because both databases start empty. Describe a dream and click Get Interpretation. The button reads Interpreting... while OpenAI writes, and then your dream appears in the journal with its interpretation.

If the interpretation fails, the page shows an error: "Network error. Please check your connection and try again." in the SQLite version, which shows that message for every failure, or "AI service temporarily unavailable." in the PostgreSQL version. Either way, look at the terminal, not your connection. The reason follows OpenAI API error:, above a long block of details; the troubleshooting below matches each one.

Stop the server with Ctrl+C. Node reads .env only when the server starts, so restart it after any change to .env. The PostgreSQL version still has the lesson's /shutdown test route, which stops the server when opened; delete it before you deploy.

JunoAdd your .env and start Put your key, and for PostgreSQL your database URL, in .env. Run npm start, wait for Server running, and open http://localhost:3001. Add a dream and click Get Interpretation.

If the page shows an error, read the terminal: the reason is printed there.

JunoAdd your .env and start Seeing the page proves that Express is serving it and the database opened. The interpretation is the first moment the server calls OpenAI, so a new dream in the journal is what proves your key works.

JunoAdd your .env and start The SQLite version's app.js reads an undefined data variable when the server answers with an error, so the ReferenceError lands in its network-error catch. The PostgreSQL pool always asks for an encrypted connection; a PostgreSQL server on your own computer usually has encryption switched off, so pg stops with The server does not support SSL connections.

Troubleshooting

OpenAIError: The OPENAI_API_KEY environment variable is missing or empty when you start: The server stopped before it could listen; the message comes just after a few lines pointing into openai/index.mjs. Check that the start script contains --env-file=.env, that .env is beside package.json, and that the name is exactly OPENAI_API_KEY.

node: .env: not found: The start script is right, but there is no .env in the folder you started from. Create it beside package.json.

401 Incorrect API key provided: The key reached OpenAI, but OpenAI did not accept it. Copy it again from your OpenAI account, save .env, and restart the server.

429 You exceeded your current quota: The key works, but the account has no credit to spend. Add credit under Billing in your OpenAI account, then try again.

The model ... does not exist: OpenAI plans to shut down gpt-4o-mini on January 14, 2027. After that, add an OPENAI_MODEL line to .env with the replacement OpenAI's deprecations page names, and restart.

Error: Could not locate the bindings file (SQLite version): The SQLite driver for your computer is missing. Delete node_modules and run npm ci again in this folder. Don't copy node_modules from another computer.

Failed to initialize database: with ENOTFOUND: The host name in DATABASE_URL does not exist on your network. Check that you replaced the whole example URL, and that you copied the external URL, not an internal one that works only inside your host's network.

Failed to initialize database: with ECONNREFUSED: Nothing answered at that address. If the error names port 5432 on your own computer (::1 or 127.0.0.1), DATABASE_URL is missing from .env or points at a PostgreSQL that is not running.

Failed to initialize database: with password authentication failed: The user name or password in DATABASE_URL is wrong. Copy the URL again from your database host.

Failed to initialize database: with The server does not support SSL connections: You are using a PostgreSQL server without encryption, usually one on your own computer. For local use only, add ?sslmode=disable to the end of DATABASE_URL, or use a hosted database instead.

JunoTroubleshooting Read the terminal, not the page. Find the first line containing Error and match its words to a bold heading above. Then fix .env or the file named, and run npm start again.

JunoTroubleshooting Each problem shows up at its own moment: a missing key or .env as soon as you start, a database problem before Server running, and a key, credit or model problem only when you click Get Interpretation.

JunoTroubleshooting The OpenAI client is built while server.js imports its routes, so a missing key stops Node before any line of server.js runs. A wrong key passes that check and fails only on the first request, with a 401.