DDEV Nominatim

Overview

This add-on integrates Nominatim (OpenStreetMap search and reverse geocoding engine) into your DDEV project using the mediagis/nominatim Docker image, along with Nominatim UI for interactive map searching, reverse geocoding, and database inspection.

By default, the add-on downloads and imports the Monaco extract from Geofabrik for quick testing and development. You can easily configure it to import any regional extract or custom OSM data.

Requirements

• DDEV v1.24.10 or higher

Installation

ddev add-on get bradley-tran/ddev-nominatim
ddev restart

After installation, make sure to commit the .ddev directory to version control.

Usage

Accessing Nominatim

• Web UI (Host Browser):
  • HTTP: http://<projectname>.ddev.site:8765
  • HTTPS: https://<projectname>.ddev.site:8744
  • Quick launch: ddev nominatim-ui
• API (Host Browser / External Tools):
  • HTTP: http://<projectname>.ddev.site:8980
  • HTTPS: https://<projectname>.ddev.site:8943
• Internal (From web container or other services):
  • http://nominatim:8080

API Endpoints

Useful Commands

Nominatim CLI

This add-on exposes the nominatim command to run CLI commands directly inside the Nominatim container:

# Check service and database status
ddev nominatim status

# Check database health and consistency
ddev nominatim admin --check-database

# Warm database cache
ddev nominatim admin --warm

# Show Nominatim version
ddev nominatim --version

# View all available CLI commands and help
ddev nominatim --help

Configuration

Configuration is managed via .ddev/.env.nominatim. You can configure settings using ddev dotenv set:

# Example 1: Import Germany from URL instead of Monaco
ddev dotenv set .ddev/.env.nominatim --nominatim-pbf-url="https://download.geofabrik.de/europe/germany-latest.osm.pbf"
ddev restart

# Example 2: Import from a local .osm.pbf file (placed in project root or .ddev/)
ddev dotenv set .ddev/.env.nominatim --nominatim-pbf-path="data.osm.pbf"
ddev restart

Available Options

Customizing Nominatim UI

You can customize the UI by creating files in .ddev/nominatim-ui/:

• Theme Configuration: Create .ddev/nominatim-ui/config.theme.js to override frontend settings (e.g., default zoom, map center, tiles).
• Web Server Configuration: Create .ddev/nominatim-ui/nginx.conf to provide a custom Nginx configuration. After creating or editing these files, restart DDEV with ddev restart.

Data Persistence & Changing Data Extracts

The PostgreSQL database is persisted in a named Docker volume (ddev-<projectname>-nominatim-data).

If you change NOMINATIM_PBF_URL / NOMINATIM_PBF_PATH or want to re-import data from scratch:

1. Stop DDEV:

   ddev stop
   

2. Remove the existing database volume:

   docker volume rm ddev-${DDEV_SITENAME}-nominatim-data
   

3. Update your .ddev/.env.nominatim configuration:

   # Using a URL:
   ddev dotenv set .ddev/.env.nominatim --nominatim-pbf-url="https://download.geofabrik.de/europe/liechtenstein-latest.osm.pbf"
   # Or using a local file:
   ddev dotenv set .ddev/.env.nominatim --nominatim-pbf-path="data.osm.pbf"
   

4. Start DDEV (starts immediately; Nominatim imports in the background):

   ddev start
   

Hardware Considerations

• Small extracts (Monaco, Liechtenstein): ~2 GB RAM, 10–20 GB disk, finishes in minutes.
• Medium extracts (countries like Germany, France): 16–32 GB RAM, 50–100 GB fast NVMe disk, can take a few hours.
• Full Planet: 64–128 GB+ RAM, 1 TB+ NVMe SSD, takes multiple days.

Credits

Contributed and maintained by @bradley-tran