Skip to content

Local setup — 5 minutes from clone to dev server

End state: npm run dev serves http://localhost:3000, Postgres has the canonical catalog seeded, and npx vitest run passes 43/43.

Prerequisites

Tool Version Why
Node.js 22.x Next.js 16 runtime
Docker any recent Postgres + Redis containers
git any clone
Python (optional) 3.12+ only if you want to preview the docs site locally

Steps

1. Clone

git clone https://github.com/Amine32/961tech.git
cd 961tech

2. Install Node deps

npm install

3. Set up env

cp .env.example .env

Edit .env only if you want to override anything. The defaults assume:

  • Postgres on localhost:5433 (not the default 5432 — see ADR-0001)
  • Redis on localhost:6379

For the full reference, see Env vars.

4. Start the database + queue

docker compose up -d

This launches:

  • Postgres 17 on host port 5433
  • Redis 7 on host port 6379

5. Run migrations + seed

npx prisma migrate reset

This nukes the DB, re-applies migrations, and seeds the canonical catalog (303 products across 8 categories). Confirm with y when prompted.

6. Start the dev server

npm run dev

Open http://localhost:3000. You should see the landing page with the live build card.

7. (Optional) Run a scrape

npm run scrape

Takes 1-2 minutes; populates ~1,700 listings from PCAndParts, 961Souq, and Macrotronics. Required if you want the browse and build pages to show real data.

8. (Optional) Run tests

npx vitest run

Should report 43/43 passing across 7 files.

9. (Optional) Preview the docs site

pip install -r docs/requirements.txt
mkdocs serve

Open http://localhost:8000.

Verification

  • http://localhost:3000 renders the landing page with cedar accents
  • http://localhost:3000/products shows products in 8 categories
  • http://localhost:3000/build shows 8 empty slots + 3 quick-start templates
  • docker ps shows two healthy containers (postgres + redis)
  • npx prisma studio opens a DB browser at http://localhost:5555 (Prisma Studio) showing populated tables

Troubleshooting

Symptom Likely cause Fix
connection refused on port 5433 Postgres container didn't start docker compose logs postgres
Migrations fail on a fresh DB Prisma client out of sync npx prisma generate && npx prisma migrate reset
npm install complains about Node version Wrong Node Install Node 22 (try nvm use 22)
Dev server starts but pages 404 Cached .next/ from another branch rm -rf .next && npm run dev
Hummingbot conflict on 5432 You changed the DB port back to 5432 Don't — see ADR-0001. Keep 5433.

Next