# Installation (https://prood.com/docs/run-locally/installation)

Prood uses a **pnpm + Turborepo** monorepo. All applications live under `apps/` and shared libraries under `packages/`.

## Prerequisites [#prerequisites]

Install the following before proceeding:

- **Node.js 24+** — required by all apps (`engines.node >= 24`)
- **pnpm 10** — package manager (`corepack enable` or `npm i -g pnpm`)
- **Neon Postgres** — provision a database and copy the connection string

Optional services for full functionality:

| Service | Used by | Purpose |
| --- | --- | --- |
| Upstash Redis | `apps/checkout` | Checkout session persistence |
| Cloudflare R2 | `@prood/storage-s3` | File storage |
| Stripe / Easypay / Ifthenpay | Payment providers | Live payment flows |

## Step 1 — Clone and install [#step-1--clone-and-install]

```bash
git clone <your-repo-url>
cd prood-commerce-platform
pnpm install
```

This installs all workspace packages and runs `postinstall` hooks (including `fumadocs-mdx` for the docs app).

## Step 2 — Environment configuration [#step-2--environment-configuration]

Copy the example env file and fill in required values:

```bash
cp .env.example .env.local
pnpm env:link
```

At minimum, set:

```bash
DATABASE_URL="postgresql://user:password@host/db?sslmode=require"
BETTER_AUTH_SECRET="<openssl rand -base64 32>"
NEXT_PUBLIC_PLATFORM_DOMAIN="localhost"
```

See [Environment variables](/docs/run-locally/environment) for the complete reference.

## Step 3 — Database setup [#step-3--database-setup]

Apply the migrations, then seed the demo store:

```bash
pnpm db:migrate
pnpm db:seed
```

| Script | What it does |
| --- | --- |
| `pnpm db:migrate` | Applies pending migrations from `packages/platform/drizzle` (commerce + Better Auth tables, `prood_app` role, RLS policies). Re-running it is a no-op. |
| `pnpm db:seed` | Seeds `org_demo`, European countries, the demo catalog and (with `ADMIN_EMAIL` / `ADMIN_PASSWORD`) an admin user. Idempotent. |
| `pnpm db:generate` | Generates the next migration after a schema change. |

### Verify the seed [#verify-the-seed]

Connect to your database and query the demo products as the tenant role, the
same way `withTenant()` does:

```sql
BEGIN;
SELECT set_config('app.current_org_id', 'org_demo', true);
SET LOCAL ROLE prood_app;
SELECT id, slug FROM products;
COMMIT;
```

The connecting role (for example `neondb_owner` on Neon) has `BYPASSRLS` and
sees every tenant's rows; `prood_app` only sees the tenant in `app.current_org_id`.

## Step 4 — Start development [#step-4--start-development]

```bash
pnpm dev
```

Turbo runs all apps in parallel. Individual apps can also be started:

```bash
pnpm --filter storefront dev    # :3000
pnpm --filter dashboard dev     # :3002
pnpm --filter checkout dev      # :3004
pnpm --filter api dev           # :3005
pnpm --filter docs dev          # :3003
pnpm --filter admin dev         # :3006
pnpm --filter web dev           # :3001, the gateway
```

## Monorepo structure [#monorepo-structure]

```mermaid
flowchart TB
  ROOT[prood-commerce-platform]

  subgraph apps [apps/]
    SF[storefront]
    DB[dashboard]
    CHK[checkout]
    API[api]
    DOCS[docs]
    WEB[web]
  end

  subgraph packages [packages/]
    TYPES[types]
    PLATFORM[platform]
    COMMERCE[commerce]
    CHPKG[checkout]
    HOST[checkout-host]
    CLIENT[api-client]
    UI[ui]
    PAY[payment-*]
    STORE[storage-*]
  end

  ROOT --> apps
  ROOT --> packages
```

## Build and quality scripts [#build-and-quality-scripts]

| Command | Description |
| --- | --- |
| `pnpm build` | Build all apps and packages via Turbo |
| `pnpm typecheck` | TypeScript check across the monorepo |
| `pnpm lint` | ESLint across the monorepo |
| `pnpm --filter @prood/platform build` | Build the platform package only |

## Adding UI components [#adding-ui-components]

Shared shadcn primitives live in `@prood/ui`:

```bash
pnpm dlx shadcn@latest add button -c packages/ui
```

Commerce-specific components (product grid, cart drawer, checkout stepper, etc.) are in `packages/ui/src/components/` and imported as `@prood/ui/components/<name>`.

## Troubleshooting [#troubleshooting]

### `DATABASE_URL` not set [#database_url-not-set]

Every app that touches auth or commerce requires `DATABASE_URL`. Ensure `.env.local` exists at the repo root and `pnpm env:link` has been run.

### Checkout sessions fail to create [#checkout-sessions-fail-to-create]

`apps/checkout` requires Upstash Redis. Set `KV_REST_API_URL` and `KV_REST_API_TOKEN` in `.env.local`. Without Redis, session creation returns 500.

### Storefront redirects to the marketing site [#storefront-redirects-to-the-marketing-site]

The storefront resolves the store from the request host (a verified custom domain or `{slug}.{NEXT_PUBLIC_PLATFORM_DOMAIN}`). Unknown hosts redirect to `NEXT_PUBLIC_WEB_URL`. Locally, open `http://prood-demo.localhost:3000` after `pnpm db:seed`.

### Auth tables missing [#auth-tables-missing]

Run `pnpm db:migrate`. Better Auth tables are part of the same versioned migrations as the commerce schema.