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

# Local Setup

> Get CharleOS running on your local machine

This guide walks you through setting up CharleOS for local development, from cloning the repository to signing in for the first time.

## Prerequisites

Before you begin, ensure you have the following installed:

### Node.js 18+

Check your version:

```bash theme={null}
node --version  # Should be v18.x or higher
```

Install via [nvm](https://github.com/nvm-sh/nvm) (recommended):

```bash theme={null}
nvm install 18
nvm use 18
```

### npm

Check your version:

```bash theme={null}
npm --version  # Should be 9.x or higher
```

npm comes with Node.js installation.

### Git

Check if installed:

```bash theme={null}
git --version
```

If not installed, [download Git](https://git-scm.com/downloads).

### Required Access

* **@charle.co.uk Email** - Required for Google OAuth sign-in
* **GitHub Repository Access** - Request access from an admin

## Setup Steps

### 1. Clone the Repository

```bash theme={null}
git clone https://github.com/charle-agency/charle-os.git
cd charle-os
```

<Note>
  If you don't have repository access, request it from the team lead.
</Note>

### 2. Install Dependencies

Install all required packages:

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

This installs:

* Next.js and React
* Better Auth for authentication
* Drizzle ORM for database access
* shadcn/ui components
* Testing frameworks (Vitest, Playwright)
* All other dependencies

**Expected time:** 1-2 minutes

### 3. Verify Environment Variables

The repository already includes a `.env.local` file with all necessary configuration:

* Database credentials (development database)
* Auth secrets and OAuth credentials
* API keys for integrations
* Feature flags

<Note>
  The `.env.local` file is checked into the repository and configured for local development. **Do NOT pull from Vercel** as that would overwrite with production credentials.
</Note>

You can verify the file exists:

```bash theme={null}
cat .env.local | head -5
```

You should see environment variables for Better Auth and the database.

### 4. Start the Development Server

Start the Next.js development server:

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

You should see:

```
  ▲ Next.js 16.0.10
  - Local:        http://localhost:3000
  - Environments: .env.local

✓ Starting...
✓ Ready in 2.3s
```

Open [http://localhost:3000](http://localhost:3000) in your browser.

### 5. Sign In

1. Click **"Sign in with Google"**
2. Select your **@charle.co.uk** email
3. Authorize the application

**After first sign-in:**

* Your account is created with role = `pending`
* You'll see "Pending Approval" message
* Contact an admin to update your role to `developer`, `pm`, `csm`, or `admin`

<Info>
  Only **@charle.co.uk** email addresses are allowed. Other domains will be rejected.
</Info>

## Verify Your Setup

Once signed in (and approved by admin), verify everything works:

<AccordionGroup>
  <Accordion title="Dashboard Loads" icon="gauge">
    Navigate to the dashboard. You should see:

    * Day rates chart
    * Client list
    * Task counts
    * Schedule preview

    If data is missing, the database connection is working but you may not have access to client data yet.
  </Accordion>

  <Accordion title="Database Connection" icon="database">
    Open Drizzle Studio to browse the database:

    ```bash theme={null}
    npm run db:studio
    ```

    Opens at [https://local.drizzle.studio](https://local.drizzle.studio)

    You should see all tables (users, clients, tasks, etc.).
  </Accordion>

  <Accordion title="Hot Reload Works" icon="arrows-rotate">
    Make a small change to any file (e.g., add a comment). The browser should automatically reload with your changes.

    If it doesn't, check the terminal for build errors.
  </Accordion>
</AccordionGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Database Connection Error" icon="database">
    **Symptoms:**

    * "Connection refused" errors
    * Blank dashboard
    * API routes returning 500 errors

    **Possible causes:**

    1. **DATABASE\_URL not set**: Check `.env.local` has `DATABASE_URL`
    2. **VPN interference**: Disconnect VPN and try again
    3. **Incorrect credentials**: Verify `.env.local` wasn't accidentally modified

    **Debug steps:**

    ```bash theme={null}
    # Verify DATABASE_URL is set
    cat .env.local | grep DATABASE_URL

    # If modified, restore from git
    git checkout .env.local

    # Restart dev server
    npm run dev
    ```
  </Accordion>

  <Accordion title="Module Not Found or Type Errors" icon="cube">
    **Symptoms:**

    * Import errors like "Cannot find module..."
    * TypeScript errors about missing types

    **Fix:** Clear cache and reinstall:

    ```bash theme={null}
    rm -rf node_modules .next
    npm install
    npm run dev
    ```
  </Accordion>

  <Accordion title="Port 3000 Already in Use" icon="network-wired">
    **Error:** `Port 3000 is already in use`

    **Options:**

    **Option 1:** Kill the process using port 3000:

    ```bash theme={null}
    # macOS/Linux
    lsof -ti:3000 | xargs kill -9

    # Windows (PowerShell)
    Stop-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess -Force
    ```

    **Option 2:** Use a different port:

    ```bash theme={null}
    PORT=3001 npm run dev
    ```

    Then open [http://localhost:3001](http://localhost:3001)
  </Accordion>

  <Accordion title="Pending Role - Can't Access App" icon="user-lock">
    **Symptom:** After signing in, you see "Pending Approval" and can't access the app

    **Cause:** New accounts start with `role = pending` until approved

    **Fix:** Ask an admin to update your role in the database
  </Accordion>
</AccordionGroup>

## Optional: Seed Development Data

If you want realistic data for local development:

```bash theme={null}
npm run db:seed
```

This creates:

* Sample clients
* Demo tasks and quotes
* Test time entries
* Schedule blocks

<Warning>
  **Do NOT run this on production!** The seed script is for local development only.
</Warning>

## Development Workflow

Now that you're set up, here's the typical development workflow:

<Steps>
  <Step title="Pull Latest Changes">
    Start each day by pulling the latest code:

    ```bash theme={null}
    git checkout main
    git pull origin main
    ```
  </Step>

  <Step title="Create Feature Branch">
    Create a branch for your work:

    ```bash theme={null}
    git checkout -b feature/your-feature-name
    ```

    Use prefixes like `feature/`, `fix/`, `chore/`
  </Step>

  <Step title="Make Changes">
    * Edit files in your code editor
    * Save, and hot reload will update the browser
    * Check terminal for any errors
  </Step>

  <Step title="Test Locally">
    * Manually test your changes in the browser
    * Run unit tests: `npm run test`
    * Run E2E tests if needed: `npm run test:e2e`
  </Step>

  <Step title="Commit and Push">
    ```bash theme={null}
    git add .
    git commit -m "feat: add new feature"
    git push origin feature/your-feature-name
    ```

    Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
  </Step>

  <Step title="Create Pull Request">
    * Go to GitHub
    * Create PR from your branch to `main`
    * Vercel will automatically deploy a preview
    * Request reviews from teammates
  </Step>
</Steps>

## Available Commands

Common commands for local development:

| Command               | Description                                 |
| --------------------- | ------------------------------------------- |
| `npm run dev`         | Start development server                    |
| `npm run build`       | Build for production (test build locally)   |
| `npm run lint`        | Run ESLint to catch code issues             |
| `npm run format`      | Format code with Prettier                   |
| `npm run type-check`  | Check TypeScript types without building     |
| `npm run test`        | Run unit tests                              |
| `npm run test:watch`  | Run tests in watch mode                     |
| `npm run test:e2e`    | Run E2E tests                               |
| `npm run db:push`     | Push schema changes to database (local dev) |
| `npm run db:generate` | Generate migration file (for production)    |
| `npm run db:studio`   | Open Drizzle Studio (database browser)      |
| `npm run db:seed`     | Seed development data                       |

See `package.json` for the complete list.

## Next Steps

Now that you're set up, explore the codebase:

<CardGroup cols={2}>
  <Card title="Project Structure" icon="folder-tree" href="/developer/getting-started/project-structure">
    Understand how the codebase is organized
  </Card>

  <Card title="Environment Variables" icon="key" href="/developer/getting-started/environment">
    Learn about all configuration options
  </Card>

  <Card title="Database" icon="database" href="/developer/database">
    Working with Drizzle ORM and PostgreSQL
  </Card>

  <Card title="Authentication" icon="lock" href="/developer/auth">
    Better Auth setup and permissions
  </Card>
</CardGroup>