Advanced Web Applications Development

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.

  1. Download it from postgresapp.com. Take the release with PostgreSQL 18 (about 123 MB).
  2. Drag the app into your Applications folder and double-click it.
  3. 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:

  1. Installation directory — accept the default.
  2. Components — keep PostgreSQL Server, pgAdmin 4 and Command Line Tools. Stack Builder is not needed.
  3. Data directory — accept the default.
  4. Password — for the postgres superuser. Write this down. You will need it on Friday, and it cannot be recovered.
  5. Port — leave it as 5432.
  6. 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 postgres and 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.

Saved in this browser only.