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

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

### 2. Start Services

```bash
# 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

```bash
# 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)

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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
```bash
# 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
```bash
# Check database container status (if running local db)
docker-compose logs db

# Restart database
docker-compose restart db
```

### API Startup Issue
```bash
# Check service logs
docker-compose logs auth_api

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

### Admin UI Not Reachable
```bash
# 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

```bash
# 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

```bash
# 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`:

```yaml
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