mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 19:01:08 +02:00
🧑💻 dx: add automatic database setup and dev:*:full commands
- Add scripts/setup-databases.sh for automatic DB creation and schema push - Add dev:*:full commands (chat, zitare, contacts, calendar, clock, todo, picture) - Update docker/init-db to create all databases on first startup - Add docs/LOCAL_DEVELOPMENT.md with comprehensive local dev guide - Update CLAUDE.md with new quick start commands Now developers can run `pnpm dev:chat:full` to automatically: 1. Create the database if missing 2. Push the latest schema 3. Start auth, backend, and web with colored output
This commit is contained in:
Wuesteon
parent
e423785a20
commit
67a15cc9ea
5 changed files with 517 additions and 20 deletions
275
docs/LOCAL_DEVELOPMENT.md
Normal file
275
docs/LOCAL_DEVELOPMENT.md
Normal file
|
|
@ -0,0 +1,275 @@
|
|||
# Local Development Guide
|
||||
|
||||
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
|
||||
# ... etc
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 1. Start Docker infrastructure (PostgreSQL, Redis, MinIO)
|
||||
pnpm docker:up
|
||||
|
||||
# 2. Generate environment files (runs automatically on pnpm install)
|
||||
pnpm setup:env
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database doesn't exist
|
||||
|
||||
If you see `database "xxx" does not exist`:
|
||||
|
||||
```bash
|
||||
# Option 1: Run the setup script
|
||||
pnpm setup:db:chat # or whichever service
|
||||
|
||||
# Option 2: Create manually
|
||||
PGPASSWORD=devpassword psql -h localhost -U manacore -d postgres -c "CREATE DATABASE chat;"
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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 |
|
||||
| bauntown, context, maerchenzauber, memoro, news, nutriphi, presi, quote, reader, storage, wisekeep | No backends |
|
||||
|
||||
For these, use the regular dev commands:
|
||||
|
||||
```bash
|
||||
pnpm dev:manacore:web
|
||||
pnpm dev:manadeck:app
|
||||
```
|
||||
|
||||
## Adding a New Application
|
||||
|
||||
### Step 1: Create Project Structure
|
||||
|
||||
Create the standard project structure under `apps/`:
|
||||
|
||||
```
|
||||
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
|
||||
├── pnpm-workspace.yaml
|
||||
└── CLAUDE.md # Project documentation
|
||||
```
|
||||
|
||||
### Step 2: Configure Backend Database (if applicable)
|
||||
|
||||
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 to setup script** (`scripts/setup-databases.sh`):
|
||||
|
||||
In the `setup_service()` function, add a new case:
|
||||
```bash
|
||||
newproject)
|
||||
create_db_if_not_exists "newproject"
|
||||
push_schema "@newproject/backend" "newproject"
|
||||
;;
|
||||
```
|
||||
|
||||
Also add to the `ALL_DATABASES` array:
|
||||
```bash
|
||||
ALL_DATABASES=(
|
||||
...
|
||||
"newproject"
|
||||
)
|
||||
```
|
||||
|
||||
And to the services loop at the bottom:
|
||||
```bash
|
||||
for service in auth chat ... newproject; do
|
||||
```
|
||||
|
||||
3. **Add DATABASE_URL to `.env.development`**:
|
||||
```env
|
||||
NEWPROJECT_DATABASE_URL=postgresql://manacore:devpassword@localhost:5432/newproject
|
||||
```
|
||||
|
||||
4. **Update `scripts/generate-env.mjs`** to generate the backend `.env` file.
|
||||
|
||||
### Step 3: Add Package.json Scripts
|
||||
|
||||
Add to root `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
// Project-level dev (all apps)
|
||||
"newproject:dev": "turbo run dev --filter=newproject...",
|
||||
|
||||
// Individual app commands
|
||||
"dev:newproject:web": "pnpm --filter @newproject/web dev",
|
||||
"dev:newproject:mobile": "pnpm --filter @newproject/mobile dev",
|
||||
"dev:newproject:backend": "pnpm --filter @newproject/backend dev",
|
||||
"dev:newproject:landing": "pnpm --filter @newproject/landing dev",
|
||||
"dev:newproject:app": "turbo run dev --filter=@newproject/web --filter=@newproject/backend",
|
||||
|
||||
// Full dev with auto database setup
|
||||
"dev:newproject:full": "./scripts/setup-databases.sh newproject && ./scripts/setup-databases.sh auth && concurrently -n auth,backend,web -c blue,green,cyan \"pnpm dev:auth\" \"pnpm dev:newproject:backend\" \"pnpm dev:newproject:web\"",
|
||||
|
||||
// Database shortcuts
|
||||
"newproject:db:push": "pnpm --filter @newproject/backend db:push",
|
||||
"newproject:db:studio": "pnpm --filter @newproject/backend db:studio",
|
||||
|
||||
// Setup shortcut
|
||||
"setup:db:newproject": "./scripts/setup-databases.sh newproject"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Create Project CLAUDE.md
|
||||
|
||||
Create `apps/newproject/CLAUDE.md` with:
|
||||
- Project overview
|
||||
- Structure diagram
|
||||
- Available commands
|
||||
- API endpoints (if backend)
|
||||
- Environment variables
|
||||
- Tech stack details
|
||||
|
||||
See existing projects like `apps/chat/CLAUDE.md` for reference.
|
||||
|
||||
### Step 5: Test the Setup
|
||||
|
||||
```bash
|
||||
# Create database and push schema
|
||||
pnpm setup:db:newproject
|
||||
|
||||
# Start with full dev command
|
||||
pnpm dev:newproject:full
|
||||
```
|
||||
|
||||
## Checklist for New Projects
|
||||
|
||||
- [ ] Create project structure under `apps/newproject/`
|
||||
- [ ] Add `pnpm-workspace.yaml` in project root
|
||||
- [ ] Add database to `docker/init-db/01-create-databases.sql`
|
||||
- [ ] Add service to `scripts/setup-databases.sh`
|
||||
- [ ] Add DATABASE_URL to `.env.development`
|
||||
- [ ] Update `scripts/generate-env.mjs` for env generation
|
||||
- [ ] Add scripts to root `package.json`
|
||||
- [ ] Create `CLAUDE.md` with project documentation
|
||||
- [ ] Test with `pnpm dev:newproject:full`
|
||||
Loading…
Add table
Add a link
Reference in a new issue