291 lines
10 KiB
Markdown
291 lines
10 KiB
Markdown
---
|
||
title: Local Setup
|
||
tags: [development]
|
||
---
|
||
|
||
# Local Setup
|
||
|
||
This guide walks you through running both repositories of the marketplace stack on your workstation. The platform is split into two services:
|
||
|
||
- **Backend** — Node.js 22+ / Express 5 / PostgreSQL 16 / Redis 8 / Socket.IO, served on port `5001`.
|
||
- **Frontend** — Next.js 16 / React 19 / MUI v7, served on port `8083` (or `3000` in Docker dev).
|
||
|
||
By the end of this page you will have the API running locally with PostgreSQL + Redis containers, a seeded set of test accounts, and the Next.js dashboard talking to it through your browser. For ongoing reference see [[Environment Variables]], [[Project Structure]], and [[Scripts]].
|
||
|
||
---
|
||
|
||
## 1. Prerequisites
|
||
|
||
Install the following before you start:
|
||
|
||
| Tool | Version | Why |
|
||
|------|---------|-----|
|
||
| Node.js | `>= 22` (backend), `>= 20` (frontend) | Runtime |
|
||
| Yarn | `1.22.22` (Classic) | Pinned via `packageManager` field |
|
||
| Docker Desktop | latest | Runs PostgreSQL + Redis + (optionally) backend/frontend |
|
||
| Git | `>= 2.40` | SSH-based clone from Gitea |
|
||
| OpenSSL | system default | For generating local secrets |
|
||
| `ngrok` (optional) | latest | For webhook testing — see [[Scripts#start-ngrok-sh]] |
|
||
|
||
> [!tip] Use a single Node version manager (`nvm`, `fnm`, or `volta`) and pin to `22`. Yarn Classic is required — do **not** upgrade to Berry, the lockfiles are incompatible.
|
||
|
||
You also need an SSH key registered with Gitea. The Git server runs on a non-standard port (`222`), so add an entry to `~/.ssh/config`:
|
||
|
||
```ssh
|
||
Host git.manko.yoga
|
||
HostName git.manko.yoga
|
||
Port 222
|
||
User git
|
||
IdentityFile ~/.ssh/id_ed25519
|
||
```
|
||
|
||
Verify connectivity:
|
||
|
||
```bash
|
||
ssh -T git@git.manko.yoga -p 222
|
||
```
|
||
|
||
You should see a Gitea welcome line. If you see "Permission denied (publickey)", upload your public key to your Gitea profile first.
|
||
|
||
---
|
||
|
||
## 2. Clone the repos
|
||
|
||
The two repos are siblings — keep them next to each other (the production compose file references `../frontend` from the backend folder):
|
||
|
||
```bash
|
||
mkdir -p ~/code && cd ~/code
|
||
|
||
git clone ssh://git@git.manko.yoga:222/nick/backend.git
|
||
git clone ssh://git@git.manko.yoga:222/nick/frontend.git
|
||
```
|
||
|
||
Switch each repo to the active integration branch for the stack you are testing. As of 2026-05-31, the dev stack work is on `integrate-main-into-development`:
|
||
|
||
```bash
|
||
cd ~/code/backend && git checkout integrate-main-into-development
|
||
cd ~/code/frontend && git checkout integrate-main-into-development
|
||
```
|
||
|
||
> [!warning] `main`/`master` is the production branch and is consumed by the Watchtower auto-update flow. Never push WIP commits there. See [[Git Workflow]].
|
||
|
||
---
|
||
|
||
## 3. Install dependencies
|
||
|
||
Backend uses **npm** for scripts but `yarn install` for lockfile parity with Docker, while the frontend is pure Yarn:
|
||
|
||
```bash
|
||
# Backend
|
||
cd ~/code/backend
|
||
yarn install --frozen-lockfile
|
||
|
||
# Frontend
|
||
cd ~/code/frontend
|
||
yarn install --frozen-lockfile
|
||
```
|
||
|
||
Both installs take 2–5 minutes on a cold cache. If `node-gyp`/`sharp` fail on macOS, install Xcode CLT (`xcode-select --install`).
|
||
|
||
---
|
||
|
||
## 4. Configure `.env` files
|
||
|
||
Each repo ships example files. Copy them and fill in secrets — full reference is in [[Environment Variables]].
|
||
|
||
### Backend (`/Users/mojtabaheidari/code/backend/.env.local`)
|
||
|
||
`docker-compose.dev.yml` reads `.env.local`. The container expects at minimum:
|
||
|
||
```bash
|
||
NODE_ENV=development
|
||
PORT=5001
|
||
PG_URL=postgresql://postgres:postgres@postgres:5432/marketplace
|
||
REDIS_URI=redis://redis:6379
|
||
JWT_SECRET=$(openssl rand -hex 32)
|
||
JWT_EXPIRES_IN=1h
|
||
REFRESH_TOKEN_EXPIRES_IN=30d
|
||
FRONTEND_URL=http://localhost:8083
|
||
MAX_FILE_SIZE=10485760
|
||
UPLOAD_PATH=/app/uploads
|
||
RATE_LIMIT_WINDOW_MS=900000
|
||
RATE_LIMIT_MAX_REQUESTS=100
|
||
```
|
||
|
||
> [!note] `MONGODB_URI` / `MONGO_URI` / `MONGO_CONNECT_MODE` are **no longer used**. MongoDB has been fully removed from the backend runtime (v2.9.12+). The only database layer is PostgreSQL + Drizzle ORM. `PG_URL` is required.
|
||
|
||
For payments, OpenAI, SMTP, etc., refer to [[Environment Variables]].
|
||
|
||
### Frontend
|
||
|
||
Three env files already exist; pick the one that matches your scenario:
|
||
|
||
| File | When to use |
|
||
|------|-------------|
|
||
| `.env.local` | Local Next dev (`yarn dev`) — points at `http://localhost:5001` |
|
||
| `.env.development` | Docker compose dev — points at `dev.amn.gg` via Nginx |
|
||
| `.env.production` | Production build — points at `amn.gg` |
|
||
|
||
Next.js automatically picks `.env.local` for `next dev`. Do **not** check this file in if you change secrets.
|
||
|
||
---
|
||
|
||
## 5. Start the backend
|
||
|
||
You have two equivalent paths.
|
||
|
||
### Option A — All-in-Docker (recommended)
|
||
|
||
Builds the backend image, brings up PostgreSQL + Redis + backend on `nickapp-network`, and mounts `./src` for hot reload:
|
||
|
||
```bash
|
||
cd ~/code/backend
|
||
npm run docker:dev
|
||
```
|
||
|
||
Follow logs:
|
||
|
||
```bash
|
||
npm run docker:dev:logs
|
||
```
|
||
|
||
Stop:
|
||
|
||
```bash
|
||
npm run docker:dev:down
|
||
```
|
||
|
||
### Option B — Local Node + Docker datastores
|
||
|
||
Run only the datastores in Docker and the API on the host:
|
||
|
||
```bash
|
||
cd ~/code/backend
|
||
docker compose -f docker-compose.dev.yml up -d postgres redis
|
||
npm run dev # ts-node + nodemon on port 5001
|
||
```
|
||
|
||
Override `PG_URL=postgresql://postgres:postgres@localhost:5432/marketplace` in `.env` if you take this route, since `postgres` only resolves inside the compose network.
|
||
|
||
> [!tip] If port `5001` is already in use, set `PORT=5002` in `.env.local` and update `NEXT_PUBLIC_API_URL` in the frontend env to match.
|
||
|
||
---
|
||
|
||
## 5a. Apply database migrations
|
||
|
||
After starting the PostgreSQL container (and before seeding), apply all Drizzle migrations to create the 32-table schema:
|
||
|
||
```bash
|
||
cd ~/code/backend
|
||
npx drizzle-kit migrate
|
||
```
|
||
|
||
This runs the 19 migration files (0000–0019) and brings the database schema up to date. You only need to run this once on a fresh database, or after pulling commits that include new migration files.
|
||
|
||
> [!note] If you are using Option A (All-in-Docker), run this from the host after the `postgres` container is healthy but before the backend service connects.
|
||
|
||
---
|
||
|
||
## 6. Seed test data
|
||
|
||
Once PostgreSQL is healthy and migrations have been applied, populate it with default users, categories, addresses, and templates:
|
||
|
||
```bash
|
||
cd ~/code/backend
|
||
npm run seed:all # users + addresses (clears existing)
|
||
npm run seed:categories # marketplace taxonomy
|
||
```
|
||
|
||
`seed:all` creates the canonical test accounts (password `Moji6364` for all):
|
||
|
||
| Role | Email |
|
||
|------|-------|
|
||
| Admin | `admin@marketplace.com` |
|
||
| Buyer | `buyer@marketplace.com` |
|
||
| Seller | `seller@marketplace.com` |
|
||
| Seller (alt) | `seller2@marketplace.com` |
|
||
|
||
You can also enable auto-seeding on container start by adding `AUTO_SEED_ON_START=true` to `.env.local`. Auto-seed runs only when the `users` table has no non-admin entries — safe to leave on.
|
||
|
||
See [[Scripts#seed-scripts]] for the full list (`seed:users`, `seed:addresses`, `seed:categories`, `seed:all`, plus `createSupportUser.ts`, `createTestRequest.ts`, etc.).
|
||
|
||
---
|
||
|
||
## 7. Start the frontend
|
||
|
||
```bash
|
||
cd ~/code/frontend
|
||
yarn dev
|
||
```
|
||
|
||
Next.js starts on **port 8083** (`next dev -p 8083 --turbopack`). The dashboard is at:
|
||
|
||
- http://localhost:8083 — landing
|
||
- http://localhost:8083/auth/jwt/sign-in — login
|
||
- http://localhost:8083/dashboard — authenticated area
|
||
|
||
If you used the Docker compose dev workflow with the production-mode container, port `3000` may also be exposed; check the compose output.
|
||
|
||
---
|
||
|
||
## 8. Verify
|
||
|
||
Run these smoke checks before you start coding:
|
||
|
||
```bash
|
||
# Backend health (should return JSON with success: true)
|
||
curl -s http://localhost:5001/health | jq .
|
||
|
||
# API root
|
||
curl -s http://localhost:5001/ | jq .
|
||
|
||
# Login (returns JWT)
|
||
curl -s -X POST http://localhost:5001/api/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"email":"admin@marketplace.com","password":"Moji6364"}' | jq .
|
||
```
|
||
|
||
In the browser, open http://localhost:8083, log in with `admin@marketplace.com / Moji6364`, and confirm the dashboard loads. If chat or notification badges show up, sockets connected too.
|
||
|
||
> [!tip] Tail backend logs in a separate terminal: `npm run docker:dev:logs`. Look for `Connected to PostgreSQL`, `User connected`, and `Server running on port 5001`.
|
||
|
||
---
|
||
|
||
## 9. Common issues
|
||
|
||
| Symptom | Fix |
|
||
|---------|-----|
|
||
| `EADDRINUSE :::5001` | Another process owns the port — `lsof -i :5001` then `kill`, or change `PORT`. |
|
||
| `ECONNREFUSED 127.0.0.1:5432` | PostgreSQL container is down — `docker compose -f docker-compose.dev.yml ps` to check. |
|
||
| `ECONNREFUSED 127.0.0.1:6379` | Redis container is down — `docker compose -f docker-compose.dev.yml ps` to check. |
|
||
| `relation "users" does not exist` | Migrations have not been applied — run `npx drizzle-kit migrate` from the backend folder. |
|
||
| CORS errors in the browser | `FRONTEND_URL` in backend `.env.local` must exactly match the origin you open in the browser (scheme + host + port). |
|
||
| `yarn install` hangs on `sharp` | Run `yarn config set network-timeout 600000` and retry. |
|
||
| `next dev` fails with module-not-found after a `git pull` | Run `yarn install` again — Next 16 is sensitive to drift in `react`/`react-dom`. |
|
||
| Sockets do not connect | Confirm `NEXT_PUBLIC_SOCKET_URL` matches the backend origin and that no browser extension blocks WebSockets. |
|
||
|
||
---
|
||
|
||
## 10. Quick reset
|
||
|
||
If your local state gets weird, the backend ships a one-shot reset script:
|
||
|
||
```bash
|
||
cd ~/code/backend
|
||
./scripts/reset-server.sh
|
||
```
|
||
|
||
This stops the dev compose stack, restarts it, runs health checks against PostgreSQL / Redis / `/health`, and probes the login endpoint with the seeded admin user. Output is colourised and ends with the canonical test credentials. See [[Scripts#reset-server-sh]] for details.
|
||
|
||
> [!warning] `reset-server.sh` does **not** drop volumes by default. To wipe the database, uncomment the `down -v` line in the script or run `docker compose -f docker-compose.dev.yml down -v` first. You will need to re-run `npx drizzle-kit migrate` and `npm run seed:all` after a volume wipe.
|
||
|
||
---
|
||
|
||
## Next steps
|
||
|
||
- Walk the codebase via [[Project Structure]].
|
||
- Read [[Coding Standards]] before opening your first PR.
|
||
- Run the test suites — [[Testing]].
|
||
- Inspect what runs in each container — [[Docker Setup]] (Operations).
|
||
- For shipping changes through CI, see [[CI-CD Pipeline]] (Operations).
|