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

# Quick Start

> Get Soundcheck running locally in minutes

Get the Soundcheck platform running locally with this quick start guide.

## Choose your component

> [card] [Mobile App](#mobile-app)
>
> React Native development

> [card] [Web App](#web-app)
>
> Next.js development

> [card] [API (api-events)](#api-events)
>
> Encore.ts backend

> [card] [Full Stack](#full-stack)
>
> Run everything together

***

## Mobile app

**1. Clone the repository**

```bash theme={null}
git clone <repository-url>
cd soundcheck-mobile-app
```

**2. Install dependencies**

```bash theme={null}
npm install
```

**3. Set up environment variables**

```bash theme={null}
cp .env.example .env
```

Add your Clerk publishable key to `.env`:

```
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key_here
EXPO_PUBLIC_API_URL=http://localhost:4000
```

**4. Start the development server**

```bash theme={null}
npm start
```

Press `i` for iOS simulator or `a` for Android emulator.

***

## Web app

**1. Navigate to web directory**

```bash theme={null}
cd web
```

**2. Install dependencies**

```bash theme={null}
npm install
```

**3. Set up environment variables**

```bash theme={null}
cp .env.example .env.local
```

Configure your `.env.local`:

```
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key
CLERK_SECRET_KEY=your_clerk_secret
NEXT_PUBLIC_API_URL=/api-proxy/api/v1
BACKEND_API_URL=http://localhost:4000
```

**4. Start the development server**

Prefer the emulator launcher (shared infra + Encore on `:4000`):

```bash theme={null}
npm run dev:emulator
```

Or plain `npm run dev` after you start api-events yourself.
Open [http://localhost:3000](http://localhost:3000)

***

## api-events

**1. Start shared infrastructure**

From the repo root:

```bash theme={null}
npm run dev:infra
```

Brings up Postgres (`:5433`), Clerk emulator (`:4711`), and Azurite.

**2. Migrate and seed**

```bash theme={null}
cd api-events
export DATABASE_URL='postgresql://postgres:postgres@localhost:5433/soundcheck?schema=public'
npm run db:migrate
npm run db:seed:baseline
# Rich demo org + Clerk personas:
# npm run db:seed:demo-full
```

**3. Run api-events**

```bash theme={null}
cd api-events && npm run dev:emulator
```

**4. Verify it's running**

* API: [http://localhost:4000](http://localhost:4000)
* Health: [http://localhost:4000/health](http://localhost:4000/health)

***

## Full stack

Run all components together for full-stack development:

**1. Start shared infrastructure**

```bash theme={null}
npm run dev:infra
cd api-events && npm run db:migrate && npm run db:seed:demo-full
```

**2. Start api-events**

In a new terminal:

```bash theme={null}
cd api-events && npm run dev:emulator
```

**3. Start the Web App**

In another terminal:

```bash theme={null}
cd web && npm run dev:emulator
```

**4. Start the Mobile App**

In another terminal:

```bash theme={null}
EXPO_PUBLIC_API_URL=http://localhost:4000 npm start
```

### Access points

| Service | URL |
| - | - |
| Web App | [http://localhost:3000](http://localhost:3000) |
| api-events | [http://localhost:4000](http://localhost:4000) |
| Clerk emulator | [http://localhost:4711](http://localhost:4711) |
| Database | localhost:5433 |

***

## Dev container (recommended)

The easiest way to get started is using a Dev Container, which provides a pre-configured development environment.

**1. Install the Dev Containers extension**

* **VS Code**: Install [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
* **Cursor**: Install the same extension from the Extensions panel

**2. Open in Dev Container**

* Open the project folder in VS Code/Cursor
* Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
* Select **"Dev Containers: Reopen in Container"**

**3. Start developing**

The container automatically installs dependencies and configures the environment.

```bash theme={null}
npm run dev:infra
cd api-events && npm run dev:emulator
```

> [!WARNING]
>
> Dev Containers run in Docker, so you cannot connect physical devices directly via USB. Use `npm run web` to test in a browser, or Expo Go on your device (connected to the same network).

***

## Next steps

> [card] [Key Concepts](https://docs.soundchecklive.io/getting-started/key-concepts.md)
>
> Understand Soundcheck fundamentals

> [card] [Platform tour](https://docs.soundchecklive.io/getting-started/overview.md)
>
> Explore the platform features

> [card] [Environment Setup](https://docs.soundchecklive.io/engineering/development/environment-setup.md)
>
> Configure your development environment

> [card] [Troubleshooting](https://docs.soundchecklive.io/reference/troubleshooting.md)
>
> Common issues and solutions


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.