Bartendie Development Environment Guide

This guide provides multiple ways to run the Bartendie development environment as persistent services, making it accessible to both you and Augment AI for collaborative development.

🚀 Quick Start Options

Option 1: Simple Service Manager (Recommended)

The easiest way to start both frontend and backend as persistent services:

# Start both services
pnpm dev

# Or use the script directly
./scripts/dev-services.sh start

# Check status
pnpm run dev:status

# View logs
pnpm run dev:logs

# Stop services
pnpm run dev:stop

Option 2: HTTPS Development (For SSL Testing)

# Setup HTTPS certificates (one-time)
./scripts/setup-https-dev.sh

# Start with HTTPS
pnpm run dev:https

Option 3: Docker Compose (Full Isolation)

# Start all services including databases
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f

# Stop services
docker-compose -f docker-compose.dev.yml down

📋 Available Commands

Root Project Commands

# Development
pnpm dev                    # Start both services
pnpm run dev:stop          # Stop both services
pnpm run dev:restart       # Restart both services
pnpm run dev:status        # Check service status
pnpm run dev:logs          # View logs from both services
pnpm run dev:logs:backend  # View backend logs only
pnpm run dev:logs:frontend # View frontend logs only
pnpm run dev:follow        # Follow logs in real-time
pnpm run dev:https         # Start with HTTPS support

# Individual services
pnpm run backend           # Start only backend
pnpm run frontend          # Start only frontend

# Setup and maintenance
pnpm run setup             # Install all dependencies
pnpm test                  # Run all tests
pnpm run test:backend      # Run backend tests only
pnpm run test:frontend     # Run frontend tests only
pnpm run test:e2e          # Run end-to-end tests
pnpm run quality           # Run code quality checks

Service Manager Commands

./scripts/dev-services.sh start           # Start both services
./scripts/dev-services.sh stop            # Stop both services
./scripts/dev-services.sh restart         # Restart both services
./scripts/dev-services.sh status          # Show service status
./scripts/dev-services.sh logs [service]  # Show logs
./scripts/dev-services.sh follow [service] # Follow logs
./scripts/dev-services.sh backend         # Start only backend
./scripts/dev-services.sh frontend        # Start only frontend
./scripts/dev-services.sh help            # Show help

🌐 Development URLs

Once services are running, access the application at:

Frontend Application: http://dev.bartendie.com:3001
Backend API: http://dev.bartendie.com:4001
GraphQL Playground: http://dev.bartendie.com:4001/api/graphql
Phoenix LiveDashboard: http://dev.bartendie.com:4001/dashboard

Alternative URLs (localhost)

Frontend: http://localhost:3001
Backend: http://localhost:4001
GraphQL: http://localhost:4001/api/graphql

🔧 Service Management Features

Persistent Services

The development services run as background processes and persist until explicitly stopped. This means:

✅ Services continue running even if you close your terminal
✅ Both you and Augment can access the same running instance
✅ No need to restart services when switching between tasks
✅ Automatic process management with PID tracking

Log Management

Real-time logs: pnpm run dev:follow
Service-specific logs: pnpm run dev:logs:backend or pnpm run dev:logs:frontend
Log files: Stored in .dev-services/ directory
Log rotation: Automatic cleanup of old logs

Health Monitoring

Service status: pnpm run dev:status
Port availability: Automatic port conflict detection
Health checks: Built-in service health verification
Auto-restart: Services restart automatically on failure

🐳 Docker Development

For complete isolation and consistency:

Start Services

# Start all services (backend, frontend, databases)
docker-compose -f docker-compose.dev.yml up -d

# Start specific service
docker-compose -f docker-compose.dev.yml up backend

Monitor Services

# View all logs
docker-compose -f docker-compose.dev.yml logs -f

# View specific service logs
docker-compose -f docker-compose.dev.yml logs -f backend
docker-compose -f docker-compose.dev.yml logs -f frontend

# Check service status
docker-compose -f docker-compose.dev.yml ps

Stop Services

# Stop all services
docker-compose -f docker-compose.dev.yml down

# Stop and remove volumes
docker-compose -f docker-compose.dev.yml down -v

🛠️ WebStorm Integration

Configure WebStorm Run Configurations

Backend Configuration:
- Name: “Bartendie Backend”
- Command: ./scripts/dev-services.sh backend
- Working Directory: Project root
Frontend Configuration:
- Name: “Bartendie Frontend”
- Command: ./scripts/dev-services.sh frontend
- Working Directory: Project root
Full Development:
- Name: “Bartendie Dev Services”
- Command: pnpm dev
- Working Directory: Project root

WebStorm Terminal Integration

Add these aliases to your shell profile:

# Add to ~/.zshrc or ~/.bashrc
alias bd-dev="cd /path/to/bartendie && pnpm dev"
alias bd-status="cd /path/to/bartendie && pnpm run dev:status"
alias bd-logs="cd /path/to/bartendie && pnpm run dev:logs"
alias bd-stop="cd /path/to/bartendie && pnpm run dev:stop"

🔍 Troubleshooting

Port Conflicts

If ports 3001 or 4001 are in use:

# Check what's using the ports
lsof -i :3001
lsof -i :4001

# Kill processes if needed
kill -9 <PID>

# Or use the service manager to stop cleanly
pnpm run dev:stop

Service Not Starting

# Check service status
pnpm run dev:status

# View logs for errors
pnpm run dev:logs

# Restart services
pnpm run dev:restart

Database Issues

# Reset database (if using local PostgreSQL)
mix ecto.reset

# Or use Docker for isolated database
docker-compose -f docker-compose.dev.yml up postgres eventstore -d

Frontend Build Issues

# Clear node_modules and reinstall
cd frontend
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Or restart just the frontend service
pnpm run dev:stop
pnpm run frontend

📁 File Structure

bartendie/
├── scripts/
│   ├── dev-services.sh          # Main service manager
│   ├── start-dev-https.sh       # HTTPS development
│   └── setup-https-dev.sh       # HTTPS setup
├── .dev-services/               # Service management files
│   ├── backend.pid              # Backend process ID
│   ├── frontend.pid             # Frontend process ID
│   ├── backend.log              # Backend logs
│   └── frontend.log             # Frontend logs
├── docker-compose.dev.yml       # Docker development setup
├── Dockerfile.dev               # Development Docker image
├── package.json                 # Root project scripts
└── DEV_ENVIRONMENT_GUIDE.md     # This guide

🤝 Collaborative Development

This setup enables seamless collaboration between you and Augment:

Shared Services: Both can access the same running instance
Persistent State: Services maintain state across sessions
Real-time Updates: Hot reloading works for both users
Log Sharing: Both can view the same logs and debug information
Consistent Environment: Same URLs and ports for everyone

🎯 Best Practices

Always check status first: pnpm run dev:status
Use service manager: Prefer pnpm dev over manual starts
Monitor logs: Use pnpm run dev:follow for active development
Clean shutdown: Always use pnpm run dev:stop to stop services
Regular restarts: Use pnpm run dev:restart if services become unresponsive