> ## Documentation Index
> Fetch the complete documentation index at: https://docs.folksbase.joselito.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get the project running locally

This guide walks you through setting up folksbase on your local machine.

## Prerequisites

Before you start, make sure you have:

* **Node.js 24+** — [download here](https://nodejs.org/)
* **pnpm 10+** — install with `npm install -g pnpm`
* **A Neon Postgres database** — [create one](https://neon.tech/)
* **A Supabase project** — [create one](https://supabase.com/) (for authentication)

You'll also need these services (or compatible alternatives):

* **Upstash Redis** — caching and rate limiting
* **Vercel Blob** — CSV file storage
* **Inngest** — background job processing
* **Anthropic API key** — AI-powered CSV column mapping

<Note>
  The app degrades gracefully if any of these are missing, but all four are required for full functionality.
</Note>

## 1. Clone and Install

```bash theme={"dark"}
git clone https://github.com/breakzplatform/folksbase.git
cd folksbase
pnpm install
```

## 2. Configure Environment Variables

Copy the example files and fill in your values:

```bash theme={"dark"}
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
```

At minimum, you need these values to get started:

**`apps/api/.env`** — backend configuration:

| Variable                   | Description                                   |
| -------------------------- | --------------------------------------------- |
| `DATABASE_URL`             | Neon Postgres connection string               |
| `SUPABASE_URL`             | Your Supabase project URL                     |
| `SUPABASE_PUBLISHABLE_KEY` | Supabase anon/public key                      |
| `SUPABASE_SECRET_KEY`      | Supabase service role key                     |
| `ENCRYPTION_KEY`           | 64-char hex string for AES-256-GCM encryption |

Generate an encryption key with:

```bash theme={"dark"}
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

**`apps/web/.env`** — frontend configuration:

| Variable                               | Description                 |
| -------------------------------------- | --------------------------- |
| `NEXT_PUBLIC_API_URL`                  | `http://localhost:3001/api` |
| `NEXT_PUBLIC_SUPABASE_URL`             | Your Supabase project URL   |
| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Supabase anon/public key    |

<Note>
  See the [Environment Variables](/deployment/environment) page for the full list of configuration options.
</Note>

## 3. Set Up the Database

Push the Drizzle schema to your Neon database:

```bash theme={"dark"}
pnpm --filter @folksbase/db db:push
```

Optionally, seed the database with sample data:

```bash theme={"dark"}
pnpm --filter @folksbase/db seed
```

## 4. Start Development

Run all apps in dev mode with a single command:

```bash theme={"dark"}
pnpm dev
```

This starts:

| App           | URL                                            |
| ------------- | ---------------------------------------------- |
| Web (Next.js) | [http://localhost:3000](http://localhost:3000) |
| API (Hono)    | [http://localhost:3001](http://localhost:3001) |

## 5. Verify It Works

1. Open [http://localhost:3000](http://localhost:3000) in your browser
2. Sign up or log in through Supabase Auth
3. Try importing a CSV file or creating a contact manually
4. Check the dashboard for stats and recent activity

You can also verify the API is running:

```bash theme={"dark"}
curl http://localhost:3001/health
```

You should see a response like:

```json theme={"dark"}
{ "status": "ok", "checks": { "db": "ok", "redis": "ok" } }
```

## Useful Commands

```bash theme={"dark"}
pnpm dev                # Run all apps in dev mode
pnpm build              # Build everything
pnpm typecheck          # Typecheck all packages
pnpm lint               # Lint with Biome
pnpm test               # Run unit tests
```

## What's Next?

<CardGroup cols={2}>
  <Card title="Architecture Overview" icon="sitemap" href="/architecture/overview">
    Understand how the monorepo is structured and why.
  </Card>

  <Card title="Contributing Setup" icon="code" href="/contributing/setup">
    Detailed development environment setup for contributors.
  </Card>
</CardGroup>