placebo.mk/README-DEVELOPMENT.md

# Placebo.mk - Development Setup

This project supports two development modes:
1. **Docker Mode** (Recommended): All services run in Docker containers
2. **Local Mode**: Services run locally with npm, PostgreSQL in Docker

## Quick Start

### Option 1: Docker Mode (Recommended)
```bash
# Start all services in Docker
npm run docker:up

# Or use the alias
npm run dev:docker
```

Services will be available at:
- Frontend: http://localhost:5173
- Backend API: http://localhost:3000
- CMS (Strapi): http://localhost:1337/admin
- PostgreSQL: localhost:5432

### Option 2: Local Mode
```bash
# Start PostgreSQL in Docker
docker-compose -f docker-compose.dev.yml up postgres

# In another terminal, start backend and frontend locally
npm run dev:local
```

## Environment Configuration

### Backend Configuration
The backend uses `.env` files for configuration:

- `.env` - Default Docker configuration (committed)
- `.env.local` - Local development configuration (not committed)
- `.env.docker` - Docker configuration template
- `.env.example` - Example configuration

**Switching between modes:**
```bash
# Switch to local mode
cd backend && npm run dev:local

# Switch back to Docker mode
cd backend && npm run dev:reset-env
```

### Frontend Configuration
The frontend also uses `.env` files:

- `.env` - Default Docker configuration (committed)
- `.env.local` - Local development configuration (not committed)
- `.env.docker` - Docker configuration template

**API URL differences:**
- Docker: `VITE_API_URL=http://backend:3000/api/v1`
- Local: `VITE_API_URL=http://localhost:3000/api/v1`

## Development Scripts

### Root Level Scripts
```bash
# Docker commands
npm run docker:up          # Start all services
npm run docker:down        # Stop all services
npm run docker:build       # Rebuild containers
npm run docker:logs        # View logs
npm run docker:ps          # Check container status

# Development modes
npm run dev:docker         # Docker mode (alias for docker:up)
npm run dev:local          # Local mode

# Utility
npm run reset:env          # Reset .env files to Docker defaults
npm run lint               # Run linting on all services
npm run type-check         # Run TypeScript checks
```

### Backend Scripts (in backend/ directory)
```bash
npm run dev:docker         # Start in Docker mode (uses .env)
npm run dev:local          # Start in local mode (uses .env.local)
npm run start:dev          # Original NestJS dev command
npm run dev:reset-env      # Reset .env to Docker defaults
```

### Frontend Scripts (in frontend/ directory)
```bash
npm run dev:docker         # Start in Docker mode
npm run dev:local          # Start in local mode
npm run dev                # Original Vite dev command
npm run dev:reset-env      # Reset .env to Docker defaults
```

## Database Management

### PostgreSQL in Docker
The PostgreSQL container is configured with:
- Host: `localhost:5432` (from host) or `postgres:5432` (from Docker)
- Database: `placebo_backend_db` (backend), `placebo_cms_db` (CMS)
- User: `placebo_user`
- Password: `placebo_password`

### Connecting to Database
```bash
# From host machine
psql -h localhost -p 5432 -U placebo_user -d placebo_backend_db

# From within Docker container
psql -h postgres -p 5432 -U placebo_user -d placebo_backend_db
```

## Project Structure

```
placeboMk/
├── backend/              # NestJS backend API
│   ├── .env             # Docker configuration (default)
│   ├── .env.local       # Local development configuration
│   └── src/
├── frontend/            # React/Vite frontend
│   ├── .env             # Docker configuration (default)
│   ├── .env.local       # Local development configuration
│   └── src/
├── cms/cms/             # Strapi CMS
├── docker-compose.yml       # Production configuration
├── docker-compose.dev.yml   # Development configuration
└── package.json         # Root scripts
```

## Troubleshooting

### Common Issues

1. **Port conflicts**
   - Check if ports 3000, 5173, 1337, 5432 are free
   - Use `lsof -i :3000` to check what's using a port

2. **Database connection errors**
   - Ensure PostgreSQL container is running: `docker ps`
   - Check logs: `docker logs placebo-postgres-dev`
   - Verify credentials in `.env` files

3. **Environment configuration**
   - Run `npm run reset:env` to reset to Docker defaults
   - Ensure `.env.local` exists for local development

4. **Docker container issues**
   - Rebuild containers: `npm run docker:build`
   - Clear Docker cache: `docker system prune -f`

### Reset Everything
```bash
# Stop and remove containers
npm run docker:down
docker system prune -f

# Reset environment files
npm run reset:env

# Start fresh
npm run docker:up
```

## Production Deployment

For production, use:
```bash
docker-compose -f docker-compose.yml up -d
```

Production configuration:
- Uses separate `docker-compose.yml`
- Includes Nginx reverse proxy
- No hot reload, optimized builds
- Health checks and proper logging

## Notes

- **Docker-first approach**: `.env` files are configured for Docker by default
- **Local development**: Uses `.env.local` files when running services locally
- **PostgreSQL**: Always runs in Docker for consistency
- **Secrets**: Never commit actual secrets to repository