Local Setup

How to run the Seken project locally from scratch. For developers onboarding to the project.

Prerequisites

Install these tools before starting:

Tool	Version	Install
Node.js	20+	nodejs.org
pnpm	9+	npm install -g pnpm or corepack enable
Git	Any	git-scm.com
Docker	Latest	docker.com (for local Postgres)
Flutter SDK	3.41	flutter.dev
Dart	3.x	Included with Flutter
Android Studio / Xcode	Latest	For mobile builds

---

1. Clone the Repository

git clone https://github.com/pasarseken/pasarseken.git
cd pasarseken

---

2. Set Up Environment Variables

Copy the example env file and fill in your values:

cp .env.example .env

See Environment Variables → for the full list of required variables. Get values from the team's shared secrets manager.

Never Commit .env

The .env file is in .gitignore. Never commit it. If you accidentally commit secrets, rotate the affected keys immediately, see Maintenance Guide →.

---

3. Install Web Dependencies

pnpm install

The project is pnpm-only (pnpm-lock.yaml). Don't use npm install, it will produce a conflicting package-lock.json.

---

4. Start the Web Dev Server

pnpm dev

The React app will be available at http://localhost:5173 (or the port Vite assigns).

# Other useful commands
pnpm build        # Production build
pnpm preflight    # Typecheck + lint + brand-check + tests (run before every push)

---

5. Start the Backend

The backend is a NestJS + Fastify application. It expects a PostgreSQL connection via DATABASE_URL.

For local development, start a PostgreSQL instance via Docker (or point at the staging database if approved):

# Example: start a local Postgres container
docker run -d --name seken-pg \
  -e POSTGRES_PASSWORD=localpass \
  -p 5432:5432 postgres:15

# Set DATABASE_URL in your .env
# DATABASE_URL=postgresql://postgres:localpass@localhost:5432/seken

Then start the NestJS backend:

cd backend
pnpm install
pnpm start:dev

Apply the database schema (migrations live at supabase/migrations/*.sql — path is historical):

# Apply the SQL migration files to your local Postgres, in filename order
for f in supabase/migrations/*.sql; do psql "$DATABASE_URL" -f "$f"; done

Test the health check:

curl http://localhost:3000/health
# Expected: { "ok": true, "version": "..." }

A seed data script does not exist yet. To populate test data, create a listing manually through the web app UI after starting the dev server.

---

6. Set Up the Flutter App

cd mobile

# Get dependencies
flutter pub get

# Check your environment
flutter doctor

# Run on a connected device or simulator.
# The mobile app reads ALL config at compile time via Flutter dart-defines —
# running with none starts with empty defaults. Pass them inline
# (or put them in a file and use --dart-define-from-file=.env):
flutter run \
  --dart-define=FLUTTER_ENV=development \
  --dart-define=API_BASE_URL=http://localhost:3000

# Run on a specific platform (append the same --dart-define flags)
flutter run -d ios
flutter run -d android
flutter run -d chrome   # Web target (limited support)

See Flutter → for project structure, conventions, and common tasks. The mobile README.md in the pasarseken repo is the authoritative source for the full dart-define contract (every required key).

---

7. Verify Everything Works

After setup, test these flows manually:

• Web app loads at http://localhost:5173
• Backend health check returns { ok: true } at http://localhost:3000/health
• Mobile app runs on simulator
• Login / signup flow works
• Create a test listing with photos
• AI categorization returns results

---

Development Workflow

# Before every push
pnpm preflight        # Must pass — typecheck, lint, brand-check, tests

# Branch flow: branch off main, then open two PRs from the same branch:
# first into develop (staging validation), then into main. Never branch off
# develop, and never open a PR from develop into main.
# CI auto-deploys both frontend and backend via DOCR + Dokploy on each branch merge.

See Deployment → for the full release process.

---

Common Setup Issues

Problem	Likely Cause	Fix
Postgres connection refused	Docker container not running	Start the Postgres container; check DATABASE_URL in .env
Backend 401 on all routes	Missing or malformed auth headers	Ensure both Authorization and X-User-Token are sent
Flutter pub get fails	Outdated Flutter SDK	Run flutter upgrade
Vite port conflict	Port 5173 in use	Kill the process or set VITE_PORT in .env
OpenAI vision returns error	Invalid API key	Check OPENAI_API_KEY in .env
Apple Silicon, Flutter build fails for iOS	Rosetta not installed	Run softwareupdate --install-rosetta then retry
Apple Silicon, pnpm install native module errors	Architecture mismatch	Run arch -x86_64 pnpm install or use an x86_64 terminal session

Add new issues to this table as they are discovered during onboarding.