Build Documentation

Smart Route Planning - Build Documentation

This document provides comprehensive instructions for building and running the Route Planning Application. The project supports both containerized deployment using Docker (recommended) and local development setup.

Environment Configuration

Before running the application, you need to configure environment variables for both frontend and backend components.

Frontend Environment Variables

Create frontend/.env with the following configuration:

# API Configuration
VITE_API_URL=http://localhost:8080

# Google Maps Integration
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here

Backend Environment Variables

Create backend/.env with the following configuration:

# Google Maps API
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here

# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0

Obtaining API Keys

1. Google Maps API Key:
   • Visit the [Google Cloud Console](https://console.cloud.google.com/)
   • Create a new project or select an existing one
   • Enable the Maps JavaScript API and Geocoding API
   • Create credentials (API Key)
   • Restrict the API key to your domain for security

Quick Start

For immediate setup with Docker:

git clone https://github.com/amosproj/amos2025ss03-route-planning-app.git
cd amos2025ss03-route-planning-app
# Create and configure environment files as shown in Environment Configuration section above
docker-compose up --build

Access the application at http://localhost:3000/.

Prerequisites

Docker Deployment Requirements

• Docker: https://www.docker.com/
  Version 20.10 or higher
• Docker Compose: https://docs.docker.com/compose/
  Version 2.0 or higher

Local Development Requirements

• Node.js: https://nodejs.org/
  Version 18 or higher
• npm: https://www.npmjs.com/
  Version 8 or higher
• Python: https://www.python.org/
  Version 3.9 or higher
• pip: https://pip.pypa.io/
  Latest version recommended

Docker Deployment (Recommended)

Docker deployment provides a consistent environment across different systems and simplifies the setup process.

Setup Steps

1. Clone the Repository

   git clone https://github.com/amosproj/amos2025ss03-route-planning-app.git
   cd amos2025ss03-route-planning-app

2. Configure Environment Variables

   Create the required environment files:

   touch frontend/.env
   touch backend/.env

   Edit these files with your specific values as shown in the Environment Configuration section above.

3. Build and Start Services

   # Build and start all services
   docker-compose up --build
   
   # Run in detached mode (background)
   docker-compose up --build -d

4. Verify Deployment

   • Frontend Application: http://localhost:3000/
   • Backend API: http://localhost:8080/
   • API Documentation: http://localhost:8080/docs

Docker Management Commands

# Stop all services
docker-compose down

# Rebuild specific service
docker-compose up --build <service-name>

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f <service-name>

# Execute commands in running container
docker-compose exec <service-name> <command>

Local Development Setup

Local development setup is recommended for active development and debugging.

Frontend Setup

1. Navigate to Frontend Directory

   cd frontend

2. Install Dependencies

   npm install

3. Configure Environment

   touch .env
   # Edit .env with your configuration as shown in Environment Configuration section above

4. Start Development Server

   npm run dev

   The frontend will be available at http://localhost:5173/.

Backend Setup

1. Navigate to Backend Directory

   cd backend

2. Create Virtual Environment

   python -m venv venv

3. Activate Virtual Environment

   # Windows
   venv\Scripts\activate
   
   # macOS/Linux
   source venv/bin/activate

4. Install Dependencies

   pip install -r requirements.txt

5. Configure Environment

   touch .env
   # Edit .env with your configuration as shown in Environment Configuration section above

6. Start Development Server

   # Option 1: Using uvicorn directly
   uvicorn app:app --reload --port 8080
   
   # Option 2: Using Python script
   python app.py

   The backend will be available at http://localhost:8080/.

Production Build

Frontend Production Build

cd frontend
npm run build

Output: The production build will be created in the frontend/dist/ directory.

Deployment Options:

• Static hosting services (Netlify, Vercel, GitHub Pages)
• CDN deployment (CloudFront, CloudFlare)
• Web servers (Nginx, Apache)

Backend Production Deployment

For production deployment, consider using:

# Using Gunicorn (recommended for production)
pip install gunicorn
gunicorn app:app -w 4 -k uvicorn.workers.UvicornWorker

# Using Docker in production
docker-compose -f docker-compose.prod.yml up --build

API Documentation

FastAPI automatically generates interactive API documentation:

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc
• OpenAPI Schema: http://localhost:8080/openapi.json

Troubleshooting

Common Issues

Docker Issues

Problem: Port already in use

# Solution: Stop conflicting services or change ports
docker-compose down
# Or modify docker-compose.yml to use different ports

Problem: Build failures

# Solution: Clean Docker cache and rebuild
docker-compose down
docker system prune -a
docker-compose up --build

Local Development Issues

Problem: Node.js version conflicts

# Solution: Use Node Version Manager (nvm)
nvm install 18
nvm use 18

Problem: Python virtual environment issues

# Solution: Recreate virtual environment
rm -rf venv
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

Environment Configuration Issues

Problem: API keys not working

• Verify API keys are correct and active
• Check API key restrictions and permissions
• Ensure environment files are properly loaded

Problem: Services cannot communicate

• Verify network configuration in Docker
• Check firewall settings
• Ensure services are running on expected ports

---

Note: This documentation assumes you have basic familiarity with Docker, Node.js, and Python development environments. For additional help with these technologies, refer to their official documentation.