4. Start the database and the app

There are two ways to run the app. Use the first to see it working in one command. Use the second while you build, because it reloads the app every time you or your agent change the code.

Both use the same database: PostgreSQL (Postgres for short), running in a Docker container, with its data kept in a Docker volume so it survives restarts.

Option 1: everything in Docker

From the repository root:

docker compose up -d frontend backend maildev

The first run builds the app images and takes a few minutes. -d gives you your terminal back while the containers run. This path does not read your .env files: docker-compose.yml sets its own development values, and the backend creates the database tables itself when it starts.

When it is up:

• the website is at http://localhost:3000
• the backend answers {"ok":true} at http://localhost:4000
• the local mail inbox (MailDev) is at http://localhost:1080

Stop it with docker compose stop. Your data stays.

Option 2: run the app on your machine

Stop Option 1 first if it is running (docker compose stop), since both use ports 3000 and 4000. Then, from the repository root, start only the database and the mail inbox, create the tables, and start the backend:

docker compose up -d --wait postgres maildev
cd backend
npm run migrate
npm run dev

--wait returns once the database is ready to accept connections. npm run migrate runs the migrations, the files in backend/migrations/ that create and change the database tables. Run it again whenever a new migration appears, for example after your agent adds a feature.

Leave that terminal running. In a second terminal, from the repository root:

cd frontend
npm run dev

The same three addresses as Option 1 now serve your local code. Stop each half with Ctrl+C, and the containers with docker compose stop.

No Docker for the mail inbox? npm run dev:email from backend/ runs the same MailDev without it; see Email.

Postgres is published on port 5433 of your machine, so it does not collide with a Postgres you may already run on the usual port 5432. DATABASE_URL in backend/.env already points at it. To look inside it with a database client, connect to postgresql://postgres:postgres@localhost:5433/crabstack.

Sample data (optional)

To fill the app with sample users, items, blog posts and email campaigns, run docker compose run --rm seed with Option 1, or npm run seed from backend/ with Option 2.

If something does not start

• npm run migrate fails with Acquire connection error: it could not reach the database. Start it with the docker compose up command above, then run it again.
• Port 5433 is already in use: create a file named .env at the repository root containing POSTGRES_PORT=5434 (Docker Compose reads it), run the docker compose up command again, and use 5434 in DATABASE_URL.
• Port 3000, 4000, 1080 or 1025 is already in use: another program has it. These ports have no setting in docker-compose.yml, so stop that program first. lsof -i :3000 shows which one it is.

Next: Sign in for the first time