---
title: Local Development
description: Set up and run Manacore applications locally with automatic database setup.
---

import { Tabs, TabItem, Steps, Aside } from '@astrojs/starlight/components';

# Local Development

This guide explains how to set up and run applications locally with automatic database setup.

## Quick Start

For any project with a backend, use the `dev:*:full` command:

```bash
pnpm dev:chat:full      # Start chat with auth + database setup
pnpm dev:zitare:full    # Start zitare with auth + database setup
pnpm dev:contacts:full  # Start contacts with auth + database setup
```

These commands automatically:
1. Create the database if it doesn't exist
2. Push the latest schema (Drizzle `db:push`)
3. Start the auth service (mana-core-auth)
4. Start the backend and web app with colored output

## Available Full Dev Commands

| Command | Database | Backend Port | Web Port |
|---------|----------|--------------|----------|
| `pnpm dev:chat:full` | chat | 3002 | 5173 |
| `pnpm dev:zitare:full` | zitare | 3007 | 5177 |
| `pnpm dev:contacts:full` | contacts | 3015 | 5184 |
| `pnpm dev:calendar:full` | calendar | 3014 | 5179 |
| `pnpm dev:clock:full` | clock | 3017 | 5187 |
| `pnpm dev:todo:full` | todo | 3018 | 5188 |
| `pnpm dev:picture:full` | picture | 3006 | 5175 |

## Prerequisites

Before running any `dev:*:full` command:

<Steps>
1. **Start Docker infrastructure**

   This starts PostgreSQL, Redis, and MinIO:
   ```bash
   pnpm docker:up
   ```

2. **Generate environment files**

   This runs automatically on `pnpm install`, but you can run manually:
   ```bash
   pnpm setup:env
   ```
</Steps>

## Database Setup Commands

### Individual Service Setup

```bash
pnpm setup:db:auth      # Setup mana-core-auth database + schema
pnpm setup:db:chat      # Setup chat database + schema
pnpm setup:db:zitare    # Setup zitare database + schema
pnpm setup:db:contacts  # Setup contacts database + schema
pnpm setup:db:calendar  # Setup calendar database + schema
pnpm setup:db:clock     # Setup clock database + schema
pnpm setup:db:todo      # Setup todo database + schema
pnpm setup:db:picture   # Setup picture database + schema
```

### Setup All Databases

```bash
pnpm setup:db           # Creates ALL databases and pushes ALL schemas
```

This is useful when setting up a fresh environment or after pulling new schema changes.

## How It Works

### Docker Init Script

On first `pnpm docker:up`, the PostgreSQL container runs `docker/init-db/01-create-databases.sql` which creates all databases:

- manacore, chat, zitare, contacts, calendar, clock, todo, manadeck
- storage, mail, moodlit, finance, inventory, techbase, voxel_lava, figgos

### Setup Script

The `scripts/setup-databases.sh` script:

1. **Creates database** if it doesn't exist (using `psql`)
2. **Pushes schema** using `drizzle-kit push --force`

The `--force` flag auto-approves schema changes without interactive prompts.

## Apps Without Full Commands

Some apps don't have backends or don't use Drizzle:

| App | Reason |
|-----|--------|
| manacore | No backend (uses other services) |
| manadeck | Backend exists but no db:push |

For these, use the regular dev commands:

```bash
pnpm dev:manacore:web
pnpm dev:manadeck:app
```

## Troubleshooting

### Database doesn't exist

If you see `database "xxx" does not exist`:

<Tabs>
  <TabItem label="Option 1: Setup Script">
    ```bash
    pnpm setup:db:chat  # or whichever service
    ```
  </TabItem>
  <TabItem label="Option 2: Manual">
    ```bash
    PGPASSWORD=devpassword psql -h localhost -U manacore -d postgres -c "CREATE DATABASE chat;"
    ```
  </TabItem>
</Tabs>

### Schema out of date

If you see errors about missing tables/columns:

```bash
# Push the latest schema
pnpm --filter @chat/backend db:push --force
```

### Port already in use

If auth (port 3001) is already running:

```bash
# Check what's using the port
lsof -i :3001

# Kill the process if needed
kill <PID>
```

### Fresh Start (Nuclear Option)

To completely reset all databases:

```bash
# Stop and remove all containers + volumes
pnpm docker:clean

# Start fresh
pnpm docker:up

# Setup all databases
pnpm setup:db
```

## Adding a New Application

<Aside type="tip">
See the [Project Structure](/getting-started/project-structure) guide for the full directory layout.
</Aside>

### Step 1: Create Project Structure

```
apps/newproject/
├── apps/
│   ├── backend/      # NestJS API (if needed)
│   ├── mobile/       # Expo React Native app
│   ├── web/          # SvelteKit web app
│   └── landing/      # Astro marketing page
├── packages/         # Project-specific shared code
├── package.json      # Workspace root
└── CLAUDE.md         # Project documentation
```

### Step 2: Configure Backend Database

If your backend uses Drizzle ORM:

1. **Add database to Docker init** (`docker/init-db/01-create-databases.sql`):
   ```sql
   CREATE DATABASE IF NOT EXISTS newproject;
   GRANT ALL PRIVILEGES ON DATABASE newproject TO manacore;
   ```

2. **Add DATABASE_URL to `.env.development`**:
   ```env
   NEWPROJECT_DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/newproject
   ```

3. **Update `scripts/generate-env.mjs`** to generate the backend `.env` file.

### Step 3: Add Package.json Scripts

Add to root `package.json`:

```json
{
  "scripts": {
    "dev:newproject:full": "./scripts/setup-databases.sh newproject && ./scripts/setup-databases.sh auth && concurrently \"pnpm dev:auth\" \"pnpm dev:newproject:backend\" \"pnpm dev:newproject:web\"",
    "setup:db:newproject": "./scripts/setup-databases.sh newproject"
  }
}
```

### Step 4: Test

```bash
pnpm setup:db:newproject
pnpm dev:newproject:full
```
