Environment Setup

Each of the eight projects installs differently. This page only covers the general prerequisites you will need on your machine before your project's own setup steps will work.

Start with STUDENTS.md, not this page

Every repository in this course has a STUDENTS.md in its root, written for this course. That is where you begin: it covers installing dependencies and running that particular project.

Use this page for the runtimes and services STUDENTS.md assumes you already have. If STUDENTS.md and this page disagree, follow STUDENTS.md. Beyond it, the project's own README.md, CONTRIBUTING.md and docs site are the next places to look.

What Each Project Needs

Project	Language runtime	Also needs
Actual Budget	Node.js + Yarn	—
Excalidraw	Node.js + Yarn	—
Gitea	Go, Node.js	Make
Medusa	Node.js + Yarn	PostgreSQL, Redis
Chatwoot	Ruby, Node.js + pnpm	PostgreSQL, Redis
Discourse	Ruby, Node.js + pnpm	PostgreSQL, Redis, ImageMagick
Cal.diy	Node.js + Yarn	PostgreSQL
Outline	Node.js + Yarn	PostgreSQL, Redis

Version requirements change over time. Take the exact versions from your project's .nvmrc, .node-version, .ruby-version, go.mod, or package.json engines field rather than from this page.

A Note on Docker

Several of these projects offer a Docker or devcontainer setup that brings up the database and cache for you. If your project offers one, use it. It is almost always faster than installing PostgreSQL and Redis by hand, and it gives everyone on your team an identical environment, which removes an entire category of "works on my machine" problems.

• Install Docker Desktop (Mac, Windows, Linux)
• On Windows, Docker Desktop works best with the WSL2 backend — see the WSL2 section below.

Node.js

Most of these projects are Node-based. Install a version manager rather than a single system-wide Node, because different projects will want different versions.

Mac / LinuxWindows

Install nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Then, inside your project directory:

nvm install     # reads .nvmrc if the project has one
nvm use
node --version

Use nvm-windows, or install Node inside WSL2 with the Mac/Linux instructions. If your project needs PostgreSQL or Redis, prefer WSL2.

Package managers

Check which one your project uses — the lockfile tells you (yarn.lock, pnpm-lock.yaml, package-lock.json). Using the wrong one will churn the lockfile and produce a messy diff in your pull request.

corepack enable          # ships with modern Node; sets up yarn and pnpm

Ruby (Chatwoot, Discourse)

Install a Ruby version manager and the version named in the project's .ruby-version:

# rbenv
brew install rbenv        # Mac
rbenv install $(cat .ruby-version)
rbenv local $(cat .ruby-version)

Discourse maintains a well-tested setup path for contributors — follow their development install guide rather than improvising. Chatwoot's own docs cover its Rails setup.

Go (Gitea)

Install Go from go.dev/dl, matching the version in Gitea's go.mod:

go version
make build      # Gitea builds through its Makefile

Gitea also needs Node installed to build its frontend assets.

PostgreSQL and Redis

If you are not using Docker, install these natively:

MacUbuntu / WSL2Windows

brew install postgresql@16 redis
brew services start postgresql@16
brew services start redis

sudo apt update
sudo apt install postgresql redis-server
sudo service postgresql start
sudo service redis-server start

Run them inside WSL2 with the Ubuntu instructions, or use Docker. Native Windows builds of these services exist but are more trouble than they are worth here.

Windows and WSL2

If you are on Windows, we strongly recommend developing inside WSL2 rather than native Windows for every project in this course. Most of these codebases are developed and tested primarily on Mac and Linux, and their setup scripts assume a Unix shell.

Follow Microsoft's WSL2 install guide, then install your language runtime inside the WSL2 environment rather than on Windows.

Keep your repository inside the Linux filesystem

Clone into your WSL2 home directory (~/projects/...), not into /mnt/c/.... Working across the Windows/Linux filesystem boundary makes file watching and installs dramatically slower, and breaks some build tools outright.

When You Get Stuck

These are large systems, and setup problems are common and normal. Before posting:

1. Read the error. Follow the stack trace to the first line that mentions your project.
2. Search the project's own issue tracker for the error string — someone has usually hit it.
3. Check you are on the version of Node, Ruby, or Go that the project asks for. This is by far the most common cause.

If you are still stuck after a reasonable effort, ask on Ed Discussions and include the exact command you ran, the full error output, your operating system, and your runtime version. See also the FAQ.