Development Environment Setup

This guide will help you set up a local development environment for Roadtrip Planner.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Git: Version control system
```
# Check if installed
git --version
```
Docker Desktop (recommended) or Docker Engine with Docker Compose
- Docker Desktop includes Docker Compose
- Minimum version: Docker 20.10+ and Docker Compose v2+
```
# Check Docker installation
docker --version
docker compose version
```

System Requirements

Operating System: Linux, macOS, or Windows with WSL2
Memory: 4GB RAM minimum (8GB recommended)
Storage: 2GB free space for containers and dependencies
Network: Internet connection for downloading dependencies

Quick Setup

1. Clone the Repository

git clone https://github.com/mnaray/roadtrip_planner.git
cd roadtrip_planner

2. Environment Configuration

Create a .env file in the project root:

# Copy from the example or create manually
cp .env.example .env

# Or create the file with required variables
cat > .env << EOF
POSTGRES_DB=roadtrip_planner_development
POSTGRES_USER=roadtrip_planner
POSTGRES_PASSWORD=your_secure_password
DATABASE_HOST=db
EOF

3. Build and Start Services

# Build Docker images
docker compose build

# Start all services
docker compose up

# Or start in detached mode
docker compose up -d

The first run will automatically:

Install Ruby gems
Install Node.js packages
Create and migrate the database
Start the Rails server

4. Access the Application

Open your browser and navigate to: http://localhost:3000

Detailed Setup Guide

Docker Configuration

The application uses Docker Compose with the following services:

# docker-compose.yml structure
services:
  web:     # Rails application (port 3000)
  db:      # PostgreSQL database (port 5432)

Service Details

Web Service:

Based on Ruby 3.4-slim image
Includes Node.js 20.x for frontend tooling
Runs as non-root user for security
Volume mounts for live code reloading

Database Service:

PostgreSQL 17 official image
Persistent data volume
Configured with environment variables

Environment Variables

Variable	Description	Default
`POSTGRES_DB`	Database name	`roadtrip_planner_development`
`POSTGRES_USER`	Database user	`roadtrip_planner`
`POSTGRES_PASSWORD`	Database password	(required)
`DATABASE_HOST`	Database host	`db`
`RAILS_ENV`	Rails environment	`development`

Directory Structure

roadtrip_planner/
├── app/                 # Application code
│   ├── components/      # Phlex view components
│   ├── controllers/     # Rails controllers
│   ├── models/         # ActiveRecord models
│   ├── services/       # Business logic services
│   └── javascript/     # Stimulus controllers
├── config/             # Rails configuration
├── db/                 # Database migrations and schema
├── spec/               # RSpec tests
├── docs/               # This documentation
├── Dockerfile          # Container definition
├── docker-compose.yml  # Multi-container orchestration
└── .env               # Environment variables (create this)

Common Development Tasks

Database Operations

# Create and migrate database
docker compose exec web rails db:create db:migrate

# Reset database
docker compose exec web rails db:reset

# Run migrations
docker compose exec web rails db:migrate

# Rollback migration
docker compose exec web rails db:rollback

# Seed database
docker compose exec web rails db:seed

Running Tests

# Run all tests
docker compose exec web rspec

# Run specific test file
docker compose exec web rspec spec/requests/user_registration_spec.rb

# Run tests with specific format
docker compose exec web rspec --format documentation

# Run specific test line
docker compose exec web rspec spec/models/user_spec.rb:10

Code Quality Checks

# Run RuboCop linting
docker compose exec web rubocop

# Auto-fix RuboCop issues
docker compose exec web rubocop -a

# Run security audit
docker compose exec web brakeman

# Run JavaScript import audit
docker compose exec web bin/importmap audit

CSS Development

# Build CSS (development mode with watching)
docker compose exec web npm run build-css

# Build CSS for production
docker compose exec web npm run build-css:production

Rails Console

# Open Rails console
docker compose exec web rails console

# Or use the shorter alias
docker compose exec web rails c

Log Monitoring

# View logs for all services
docker compose logs

# Follow logs in real-time
docker compose logs -f

# View logs for specific service
docker compose logs web
docker compose logs db

Troubleshooting

Common Issues

Port Already in Use

# Check what's using port 3000
lsof -i :3000

# Stop existing containers
docker compose down

Database Connection Issues

# Check database service status
docker compose ps

# View database logs
docker compose logs db

# Reset database service
docker compose down
docker compose up db

Permission Issues

# Fix file permissions (Linux/macOS)
sudo chown -R $USER:$USER .

# On Windows WSL2, ensure files are in Linux filesystem

Container Build Issues

# Clean build (removes cache)
docker compose build --no-cache

# Remove all containers and volumes
docker compose down -v
docker system prune -a

Performance Optimization

Volume Mounting Performance

For better performance on macOS/Windows:

# Use cached volumes in docker-compose.yml
volumes:
  - .:/app:cached
  - gem_cache:/usr/local/bundle:delegated
  - node_modules:/app/node_modules:delegated

Memory Settings

Increase Docker Desktop memory allocation:

macOS/Windows: Docker Desktop → Settings → Resources → Advanced
Recommended: 4-8GB RAM

Development Workflow

Daily Development

Start Development Environment
```
docker compose up -d
```
Make Changes
- Code changes are automatically reloaded
- CSS changes require rebuild: npm run build-css
Run Tests
```
docker compose exec web rspec
```
Check Code Quality
```
docker compose exec web rubocop
```
Stop Environment
```
docker compose down
```

Branch Workflow

Create Feature Branch
```
git checkout -b feature/new-feature
```

Develop and Test

# Make changes, run tests
docker compose exec web rspec

Commit Changes

git add .
git commit -m "feat: add new feature"

Push and Create PR

git push origin feature/new-feature
# Create PR on GitHub

IDE Setup

VS Code (Recommended)

Install these extensions:

Ruby LSP
Docker
Ruby Test Explorer
Tailwind CSS IntelliSense

RubyMine

Configure Docker integration:

File → Settings → Build, Execution, Deployment → Docker
Set up Remote SDK with Docker Compose

Next Steps

Once your environment is set up:

Explore the Architecture Overview
Learn about Models
Understand Services
Review Testing Guidelines (coming soon)

Getting Help

If you encounter issues:

Check the Troubleshooting section
Search existing GitHub Issues
Create a new issue with detailed error information
Ask for help in the development discussions

Prerequisites​

Required Software​

System Requirements​

Quick Setup​

1. Clone the Repository​

2. Environment Configuration​

3. Build and Start Services​

4. Access the Application​

Detailed Setup Guide​

Docker Configuration​

Service Details​

Environment Variables​

Directory Structure​

Common Development Tasks​

Database Operations​

Running Tests​

Code Quality Checks​

CSS Development​

Rails Console​

Log Monitoring​

Troubleshooting​

Common Issues​

Port Already in Use​

Database Connection Issues​

Permission Issues​

Container Build Issues​

Performance Optimization​

Volume Mounting Performance​

Memory Settings​

Development Workflow​

Daily Development​

Branch Workflow​

IDE Setup​

VS Code (Recommended)​

RubyMine​

Next Steps​

Getting Help​