Local Development Setup¶

Complete guide to setting up your local development environment for the Portugal Odyssey platform.

Prerequisites¶

Install the following tools:

Required¶

Docker Desktop (Mac/Windows) or Docker Engine (Linux) 24+
Docker Compose v2
Node.js 20+ (for local service development)
npm 9+ or yarn
Git

Optional¶

VS Code with recommended extensions
Postman for API testing
pgAdmin or DBeaver for database access

Initial Setup¶

1. Clone Repository¶

git clone https://gitlab.com/portugalodissey/po-platform.git
cd po-platform

2. Create Docker Networks¶

make networks

This creates the required Docker networks: - traefik-public - portugal-odyssey-postgres-network - portugal-odyssey-redis-network - portugal-odyssey-rabbitmq-network

3. Configure Environment¶

# Copy environment templates
cp infrastructure/env-templates/.env.development .env.dev

# Edit with your configuration
nano .env.dev  # or use your preferred editor

See Environment Setup for detailed configuration.

4. Start Development Stack¶

# Start everything (infrastructure + services + frontend)
make dev

# Or start just infrastructure
make infrastructure

# View logs
make dev-logs

Development Modes¶

Full Docker Stack¶

All services run in Docker containers:

make dev

Pros: - Matches production environment - No local dependencies - Easy to reset

Cons: - Slower feedback loop - More resource intensive

Hybrid Mode¶

Infrastructure in Docker, services locally:

# Start infrastructure
make infrastructure

# Run service locally
cd services/notification-service
npm install
npm run dev

Pros: - Faster development feedback - Better debugging experience - Hot reload

Cons: - Need to manage local dependencies - Environment differences

Service-Specific Setup¶

Frontend (React)¶

cd frontends/public-fo
npm install
npm run dev

Access at: http://localhost:5173

NestJS Services¶

cd services/[service-name]
npm install
npm run dev  # Uses nodemon for hot reload

Strapi CMS¶

cd services/strapi-cms
npm install
npm run develop

Access at: http://localhost:1337/admin

Docker Commands¶

Useful Makefile Targets¶

make dev          # Start development stack
make dev-build    # Rebuild and start
make dev-logs     # View logs
make dev-stop     # Stop all services
make dev-clean    # Remove containers and volumes

Manual Docker Commose¶

# Start specific environment
docker compose -f docker-compose.yml -f infrastructure/compose/development.yml up -d

# View logs
docker compose -f docker-compose.yml -f infrastructure/compose/development.yml logs -f

# Stop services
docker compose -f docker-compose.yml -f infrastructure/compose/development.yml down

IDE Setup¶

VS Code¶

Recommended extensions: - Docker - Docker support - ESLint - JavaScript linting - Prettier - Code formatting - TypeScript - TypeScript support - GitLens - Git integration

Workspace Settings¶

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.tsdk": "node_modules/typescript/lib",
  "files.exclude": {
    "**/node_modules": true,
    "**/dist": true
  }
}

Troubleshooting¶

Port Conflicts¶

If ports are already in use:

# Find process using port
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Kill process or change port in .env.dev

Docker Issues¶

# Restart Docker
# macOS/Windows: Restart Docker Desktop
# Linux: sudo systemctl restart docker

# Clean up Docker
docker system prune -a

Database Connection Issues¶

# Check PostgreSQL is running
docker ps | grep postgres

# Check connection
docker exec po-postgres psql -U postgres -c "SELECT version();"