Photon Server

Geocoding server using Photon by Komoot for the Trufi Association stack.

Provides address search and reverse geocoding (coordinates → place name) for transit applications.

Requirements

• Docker and Docker Compose
• Internet connection (to download data)
• wget, tar, bzip2 (for the init script)

Quick Start

1. Download country data

Run the interactive script that shows all available countries:

./init.sh

The script will:

• Check that you have the required dependencies
• Show the list of available countries from GraphHopper
• Let you select a country by ISO code (e.g., rw, bo, us)
• Download and extract the data automatically

2. Start the server

docker-compose up -d --build

3. Verify it's working

curl 'http://localhost:2322/api?q=test'

Configuration

Memory

The memory limit is set to 2GB (mem_limit: 2g). Adjust according to the country data size:

• Small countries: 1-2 GB
• Medium countries: 2-4 GB
• Large countries (US, BR, etc.): 4-8 GB

API

Photon API usage examples:

# Simple search
curl 'http://localhost:2322/api?q=airport'

# Search with result limit
curl 'http://localhost:2322/api?q=hotel&limit=5'

# Search with location filter (lat, lon)
curl 'http://localhost:2322/api?q=restaurant&lat=-1.9403&lon=29.8739'

# Reverse geocoding
curl 'http://localhost:2322/reverse?lat=-1.9403&lon=29.8739'

Integration with trufi-server

This service is designed to work with trufi-server.

1. Add to docker-compose

Add this to your trufi-server docker-compose.yml or include it as a separate service:

services:
  photon:
    build:
      context: ./trufi-server-photon
    volumes:
      - ./trufi-server-photon/photon_data:/app/photon_data
    restart: unless-stopped
    mem_limit: 2g
    networks:
      - trufi-server

2. Configure trufi-server

Add Photon to your data/config/appsettings.json:

{
  "LettuceEncrypt": {
    "DomainNames": ["yourdomain.com", "photon.yourdomain.com"],
    "EmailAddress": "[email protected]"
  },
  "ReverseProxy": {
    "Routes": {
      "photon": {
        "ClusterId": "photon",
        "Match": {
          "Hosts": ["photon.yourdomain.com"]
        }
      }
    },
    "Clusters": {
      "photon": {
        "Destinations": {
          "photon": {
            "Address": "http://photon:2322"
          }
        }
      }
    }
  }
}

3. Apply changes

docker compose restart server

4. Test the integration

curl 'https://photon.yourdomain.com/api?q=test'

SSL certificates are obtained automatically by trufi-server using LettuceEncrypt.

Project Structure

trufi-server-photon/
├── init.sh              # Data download script
├── Dockerfile           # Photon image
├── docker-compose.yml   # Service orchestration
├── README.md
└── photon_data/         # Data (generated by init.sh)

Troubleshooting

Container won't start

1. Verify that photon_data/ exists and has data:

   ls -la photon_data/

2. Check the logs:

   docker-compose logs photon

Memory errors

If you see Java heap space errors, increase mem_limit in docker-compose.yml.

Corrupted data

Delete and re-download:

rm -rf photon_data/
./init.sh

Data Source

Data comes from GraphHopper, periodically updated with OpenStreetMap data.

Credits

• Photon - Open source geocoder by Komoot
• GraphHopper - Country data extracts
• OpenStreetMap - Map data
• Trufi Association - Open source transit tools for the Global South

License

This Docker configuration is part of the Trufi server stack. Photon is licensed under Apache 2.0.