Before you come
Before Friday: set up your laptop
Install Node, Git and PostgreSQL, create the database, and confirm it all works — about twenty minutes.
In this chapter
- Installing Node, Git and PostgreSQL on your own laptop
- Creating the database and the connection string
- Cloning the project and proving it runs
Do this before Friday, on the laptop you will bring. The session is hands-on from the first fifteen minutes, so anything installed in the room is time taken from the labs.
If something fails, do not fight it alone. Send me the error text and we can sort it out on a call before the day.
You need four things: Node.js, Git, a code editor, and PostgreSQL. Follow your own operating system below, then do the two sections at the end, which are the same for everyone.
macOS
Node.js. Download the LTS installer from
nodejs.org/en/download. The current LTS is
26.13.1. Run the .pkg and accept the defaults.
Git. Open Terminal and run:
xcode-select --install
That installs Apple’s command line tools, which include Git. If you already
have Homebrew, brew install git works too.
PostgreSQL. The simplest route on a Mac is Postgres.app — no installer, no background service to manage.
- Download it from postgresapp.com. Take the release with PostgreSQL 18 (about 123 MB).
- Drag the app into your Applications folder and double-click it.
- Click Initialize. You now have a server running on port 5432.
Then add its command line tools to your PATH, so psql works in Terminal:
sudo mkdir -p /etc/paths.d && echo /Applications/Postgres.app/Contents/Versions/latest/bin | sudo tee /etc/paths.d/postgresapp
Close Terminal and open it again for that to take effect.
If you prefer Homebrew:
brew install postgresql@18
brew services start postgresql@18
Homebrew installs this one “keg-only”, which means psql may not be on your
PATH. Check with psql --version; if it is not found, add
$(brew --prefix postgresql@18)/bin to your PATH.
Windows
Node.js. Download the LTS Windows Installer (.msi) from
nodejs.org/en/download — currently 26.13.1 —
and accept the defaults.
Git. Download it from git-scm.com/install/windows (currently 2.56.1) and accept the defaults. If you use winget:
winget install --id Git.Git -e --source winget
PostgreSQL. Use the EDB installer, linked from postgresql.org/download/windows. Choose PostgreSQL 18 for Windows x86-64. Do not take version 19 — it is a release candidate, not for real use.
The installer asks you, in this order:
- Installation directory — accept the default.
- Components — keep PostgreSQL Server, pgAdmin 4 and Command Line Tools. Stack Builder is not needed.
- Data directory — accept the default.
- Password — for the
postgressuperuser. Write this down. You will need it on Friday, and it cannot be recovered. - Port — leave it as 5432.
- Locale — accept the default.
At the end it offers to launch Stack Builder. Untick that and finish.
One extra step on Windows: the installer does not add psql to your PATH.
Add this folder to your system Path variable:
C:\Program Files\PostgreSQL\18\bin
Then open a new Command Prompt — an old window keeps the old PATH.
Ubuntu and other Debian-based Linux
Node.js and Git:
sudo apt update
sudo apt install -y git
For Node, use the LTS installer from nodejs.org/en/download rather than the version in apt, which is often old.
PostgreSQL. Use the official PostgreSQL apt repository, not the one that ships with Ubuntu, so you get version 18:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt update
sudo apt install -y postgresql-18
On Linux, PostgreSQL trusts your operating system user name. A first
connection as yourself will fail unless a database role with your name
exists, so connect as the postgres user instead:
sudo -u postgres psql
A code editor
If you do not already have one, install VS Code. Any editor you are comfortable with is fine.
Check everything is there
Open a terminal — Command Prompt on Windows, Terminal on macOS or Linux — and run these three:
node --version
git --version
psql --version
You should see three version numbers. Node should be 20 or higher, and PostgreSQL should start with 18. If any command says “not found”, the tool is installed but not on your PATH — that is the step to go back to.
Create the database
We will use one database for the whole session. Connect to PostgreSQL:
- macOS:
psql postgres - Windows:
psql -U postgresand enter the password you wrote down - Linux:
sudo -u postgres psql
Then run these three lines, replacing choose-a-password with something you
will remember:
CREATE USER fares WITH PASSWORD 'choose-a-password';
CREATE DATABASE passo_fares OWNER fares;
\q
Your connection string for Friday is:
postgresql://fares:choose-a-password@localhost:5432/passo_fares
Keep it somewhere you can copy from. Use letters and numbers only — something
like passo2026 is fine for a workshop database. If your password contains
@, :, /, # or %, those characters have to be escaped in a connection
string, and that is a needless thing to debug on the day.
Get the project
Fork it first. On Friday you will commit your own work and push it, so you
need your own copy. Open
github.com/bott627/passo, click Fork,
and keep the name passo.
Then clone your fork, replacing your-username:
git clone https://github.com/your-username/passo.git
cd passo
npm install
Copy the example settings file and open it:
cp .env.example .env
On Windows use copy .env.example .env instead.
Inside .env, change the password in DATABASE_URL to the one you chose
above. It is the first setting in the file:
DATABASE_URL="postgresql://fares:passo2026@localhost:5432/passo_fares"
If you used passo2026 and the username fares, that line is already correct
and you can leave it alone. Leave PORT and SESSION_SECRET as they are —
SESSION_SECRET only matters in Lab C.
Now create the tables and fill them with sample fares:
npm run setup
Start the server:
npm run dev
Open localhost:3000. You should see the Passo search form with a list of stops — Westfield, Brikama, Banjul and the rest. Choosing two stops and pressing Find the fare will say the search is not built yet. That is correct: building it is Lab A.
Check it works
Stop the server with Ctrl+C, then run:
npm test
Two tests should pass: one says the server can reach the database, the other says the stops are seeded.
What to send me
Take a screenshot of npm test showing the two passing tests, and email it to
[email protected] by Thursday evening.
That screenshot is how I know you are ready. If instead you hit an error, send me the error text — the words, not a photo of the screen — and we will fix it on a call.