Laca-City/valhalla/README.md

Valhalla Routing Engine

This directory contains the configuration and setup for the Valhalla routing engine.

🚀 Quick Setup

1. Download OSM Data

Download OpenStreetMap data for your region from Geofabrik:

# For Vietnam/Southeast Asia
wget https://download.geofabrik.de/asia/vietnam-latest.osm.pbf -P custom_files/

# For smaller regions (Ho Chi Minh City area)
wget https://download.geofabrik.de/asia/vietnam-latest.osm.pbf -P custom_files/

2. Build and Run

# Build Valhalla container
docker-compose up -d valhalla

# Check status
curl http://localhost:8002/status

📊 API Endpoints

Route Calculation

# POST /route
curl -X POST http://localhost:8002/route \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {"lat": 10.7769, "lon": 106.7009},
      {"lat": 10.7796, "lon": 106.7019}
    ],
    "costing": "auto",
    "directions_options": {
      "units": "kilometers"
    }
  }'

Locate Nearby Roads

# POST /locate
curl -X POST http://localhost:8002/locate \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {"lat": 10.7769, "lon": 106.7009}
    ],
    "costing": "auto"
  }'

Health Check

# GET /status
curl http://localhost:8002/status

⚙️ Configuration

The valhalla.json file contains the routing engine configuration:

• Costing models: auto, bicycle, pedestrian
• Data sources: OpenStreetMap
• Service endpoints: route, locate, status
• Logging: Configurable log levels

🗺️ Supported Regions

Current OSM data includes:

• Vietnam (complete)
• Southeast Asia (partial)
• Custom boundary areas

To add new regions:

1. Download .osm.pbf files to custom_files/
2. Restart the container
3. Wait for data processing to complete

🔧 Performance Tuning

Memory Configuration

{
  "mjolnir": {
    "tile_dir": "/data/valhalla",
    "max_cache_size": 1000000000
  }
}

Costing Options

{
  "costing_options": {
    "auto": {
      "maneuver_penalty": 5,
      "gate_cost": 30,
      "toll_booth_cost": 15
    }
  }
}

📈 Monitoring

Health Checks

• Container status: docker ps
• Service health: curl http://localhost:8002/status
• Logs: docker logs valhalla

Performance Metrics

• Route calculation time
• Memory usage
• Cache hit rate
• Request throughput

🐛 Troubleshooting

Common Issues

1. Container won't start

   • Check OSM data files in custom_files/
   • Verify memory allocation (minimum 2GB)
   • Check port conflicts

2. Slow route calculation

   • Increase cache size in configuration
   • Optimize OSM data for your region
   • Add more memory to container

3. Routes not found

   • Verify coordinates are within OSM data bounds
   • Check road connectivity
   • Try different costing models

Debug Mode

# Enable debug logging
docker-compose up valhalla --build
docker logs -f valhalla

🔄 Updates

Update OSM Data

# Download new data
wget https://download.geofabrik.de/asia/vietnam-latest.osm.pbf -P custom_files/

# Rebuild container
docker-compose down valhalla
docker-compose up -d valhalla --build

Update Valhalla Version

# Update base image in Dockerfile
# Rebuild container
docker-compose build valhalla --no-cache