Local Setup

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:

node --version  # Should be v18.x or higher

Install via nvm (recommended):

nvm install 18
nvm use 18

npm

Check your version:

npm --version  # Should be 9.x or higher

npm comes with Node.js installation.

Git

Check if installed:

git --version

If not installed, download Git.

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

git clone https://github.com/charle-agency/charle-os.git
cd charle-os

If you don’t have repository access, request it from the team lead.

2. Install Dependencies

Install all required packages:

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

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.

You can verify the file exists:

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:

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 in your browser.

Click “Sign in with Google”
Select your @charle.co.uk email
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

Only @charle.co.uk email addresses are allowed. Other domains will be rejected.

Verify Your Setup

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

Dashboard Loads

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.

Database Connection

Open Drizzle Studio to browse the database:

npm run db:studio

Opens at https://local.drizzle.studioYou should see all tables (users, clients, tasks, etc.).

Hot Reload Works

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.

Common Issues

Database Connection Error

Symptoms:

“Connection refused” errors
Blank dashboard
API routes returning 500 errors

Possible causes:

DATABASE_URL not set: Check .env.local has DATABASE_URL
VPN interference: Disconnect VPN and try again
Incorrect credentials: Verify .env.local wasn’t accidentally modified

Debug steps:

# 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

Module Not Found or Type Errors

Symptoms:

Import errors like “Cannot find module…”
TypeScript errors about missing types

Fix: Clear cache and reinstall:

rm -rf node_modules .next
npm install
npm run dev

Port 3000 Already in Use

Error: Port 3000 is already in useOptions:Option 1: Kill the process using port 3000:

# 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:

PORT=3001 npm run dev

Then open http://localhost:3001

Pending Role - Can't Access App

Symptom: After signing in, you see “Pending Approval” and can’t access the appCause: New accounts start with role = pending until approvedFix: Ask an admin to update your role in the database

Optional: Seed Development Data

If you want realistic data for local development:

npm run db:seed

This creates:

Sample clients
Demo tasks and quotes
Test time entries
Schedule blocks

Do NOT run this on production! The seed script is for local development only.

Development Workflow

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

Pull Latest Changes

Start each day by pulling the latest code:

git checkout main
git pull origin main

Create Feature Branch

Create a branch for your work:

git checkout -b feature/your-feature-name

Use prefixes like feature/, fix/, chore/

Make Changes

Edit files in your code editor
Save, and hot reload will update the browser
Check terminal for any errors

Test Locally

Manually test your changes in the browser
Run unit tests: npm run test
Run E2E tests if needed: npm run test:e2e

Commit and Push

git add .
git commit -m "feat: add new feature"
git push origin feature/your-feature-name

Commit messages follow Conventional Commits

Create Pull Request

Go to GitHub
Create PR from your branch to main
Vercel will automatically deploy a preview
Request reviews from teammates

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:

Project Structure

Understand how the codebase is organized

Environment Variables

Learn about all configuration options

Database

Working with Drizzle ORM and PostgreSQL

Authentication

Better Auth setup and permissions

Getting Started

Database

Authentication

Testing

Deployment

Prerequisites

Node.js 18+

npm

Git

Required Access

Setup Steps

1. Clone the Repository

2. Install Dependencies

3. Verify Environment Variables

4. Start the Development Server

Verify Your Setup

Common Issues

Optional: Seed Development Data

Development Workflow

Available Commands

Next Steps

Project Structure

Environment Variables

Database

Authentication

Getting Started

Database

Authentication

Testing

Deployment

​Prerequisites

​Node.js 18+

​npm

​Git

​Required Access

​Setup Steps

​1. Clone the Repository

​2. Install Dependencies

​3. Verify Environment Variables

​4. Start the Development Server

​5. Sign In

​Verify Your Setup

​Common Issues

​Optional: Seed Development Data

​Development Workflow

​Available Commands

​Next Steps

Project Structure

Environment Variables

Database

Authentication

Prerequisites

Node.js 18+

npm

Git

Required Access

Setup Steps

1. Clone the Repository

2. Install Dependencies

3. Verify Environment Variables

4. Start the Development Server

5. Sign In

Verify Your Setup

Common Issues

Optional: Seed Development Data

Development Workflow

Available Commands

Next Steps