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)

# 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

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

# 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

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

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)

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

# 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

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

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