The-transit-Project/monitoring_ui/docs/DOCKER_README.md

Docker Setup for Transit Project APIs

This project contains Docker configuration for all APIs, the Admin Control Center, the Monitoring UI, and external/local PostgreSQL databases.

Files

• auth_api/Dockerfile - Image for Authentication API (port 5000)
• employee_api/Dockerfile - Image for Employee API (port 4000)
• transit_api/Dockerfile - Image for Transit API (port 5001)
• admin_ui/Dockerfile - Image for Admin Control Center (port 5174)
• monitoring_ui/Dockerfile - Image for Monitoring UI Dashboard (port 5175)
• docker-compose.yml - Orchestration for all services
• .dockerignore - Files excluded from Docker images
• .env.example - Template for environment variables
• DEPLOYMENT.md - Detailed deployment guide
• scripts/deploy.sh - Deployment helper script
• scripts/build-and-push.sh - Build and push script for container registry

Prerequisites

• Docker (>=20.10)
• Docker Compose (>=2.0)

Installation & Setup

1. Configure Environment Variables

cp .env.example .env
# Edit .env with your specific configuration values

2. Start Services

# Start all services (APIs + Admin UI + Monitoring UI)
docker-compose up -d

# Or build and start simultaneously (after code modifications)
docker-compose up -d --build

# Quick start using helper script
./scripts/deploy.sh start

3. View Logs

# All service logs
docker-compose logs -f

# Logs for a specific service
docker-compose logs -f auth_api
docker-compose logs -f transit_api
docker-compose logs -f admin_ui

# Via helper script
./scripts/deploy.sh logs admin_ui

Available Services

Service	Port	Description
admin_ui	5174	Admin Control Center (React + Nginx)
monitoring_ui	5175	Monitoring Dashboard & Docs Hub (React + Nginx)
auth_api	5000	Authentication endpoints
employee_api	4000	Employee management endpoints
transit_api	5001	Transit management endpoints
error_log_api	5003	Centralized error logging API

Commands

Manage Services (Quick Way)

# Using helper script
./scripts/deploy.sh start       # Start all services
./scripts/deploy.sh stop        # Stop all services
./scripts/deploy.sh restart     # Restart all services
./scripts/deploy.sh status      # Show status
./scripts/deploy.sh logs        # View admin_ui logs
./scripts/deploy.sh logs transit_api  # View specific service logs

Manage Services (Docker Compose)

# Start services
docker-compose up -d

# Stop services
docker-compose down

# Restart services
docker-compose restart

# Remove containers and volumes
docker-compose down -v

Individual Services

# Restart a specific service
docker-compose restart auth_api
docker-compose restart admin_ui

# Build a specific image
docker-compose build auth_api

# Tail logs of a specific service
docker-compose logs -f transit_api

Admin UI

# Access Admin UI in browser
http://localhost:5174

# View logs
docker-compose logs -f admin_ui

# Interactive shell in container
docker-compose exec admin_ui sh

Troubleshooting

Port Already in Use

# Check which process or container is using the port
docker ps
# or
lsof -i :5000

# Modify the host port in docker-compose.yml (e.g. change "5000:5000" to "5010:5000")

Database Connection Error

# Check database container status (if running local db)
docker-compose logs db

# Restart database
docker-compose restart db

API Startup Issue

# Check service logs
docker-compose logs auth_api

# Verify environment variables in .env
# Verify database connection string and network reachability

Admin UI Not Reachable

# Check Admin UI container status
docker-compose logs admin_ui

# Ensure port 5174 is not bound by another process
lsof -i :5174

Admin Control Center

The Admin UI is a modern React + Vite application that provides administrative management tools.

Features

• Authentication: JWT-based login with dev token helper
• Stop Management: Create and manage transit stops with geo-coordinates
• Bus Lines: Define bus routes with start/end stops and travel duration
• Fleet Management: Monitor fleet vehicles
• Stop Linking: Assign stops to bus lines with sequence ordering and ETA

Access

URL: http://localhost:5174

Deployment Configuration

Environment variables in docker-compose.yml:

• VITE_AUTH_API: URL to auth_api (default: http://auth_api:5000)
• VITE_TRANSIT_API: URL to transit_api (default: http://transit_api:5001)

For external access, update URLs to your deployment domain.

Build and Deployment

# Build Admin UI image
docker-compose build admin_ui

# Push to container registry
./scripts/build-and-push.sh ghcr.io/your-org/xtransit latest

# Deploy with updated image
docker-compose up -d

Development

Applying Code Changes

# Rebuild container
docker-compose build auth_api

# Restart service
docker-compose restart auth_api

Code Hot-Reloading

For live reloading during development, you can mount source directories as volumes in docker-compose.yml:

volumes:
  - ./auth_api:/app

Note: This may impact performance on some host platforms. Use during local development only.

Production Tips

1. Security: Change all default passwords and JWT_SECRET in .env.
2. Database: Use a managed database service or secured host in production.
3. Logging: Configure centralized logging via error_log_api or log aggregators.
4. Backups: Configure automated backup procedures for PostgreSQL.
5. Health Checks: Monitor the /health endpoints of all deployed APIs.
6. SSL/TLS: Use a reverse proxy (Nginx, Traefik) to provide HTTPS.

Networking

Services communicate internally via:

• auth_api: http://auth_api:5000
• employee_api: http://employee_api:4000
• transit_api: http://transit_api:5001
• database: db:5432 or external host