osm2pgsql Docker Quickstart

This is a simple docker-compose.yml setup using osm2pgsql with postgis. It is not well tuned, please read the osm2pgsql manual for more information on how to best use osm2pgsql.

Credit

This project started with a fork from OsmHackTW/osm2pgsql-docker.

At SOTM2022 I learned osm2pgsql is already packaged... so now this container uses debian:trixie-backports and apt-get install -y osm2pgsql/trixie-backports!

Usage

Running the following:

docker-compose up

This will build the osm2pgsql container, download the postgis/postgis image, and run them both. Within the osm2pgsql container is a script to pulldown an OpenStreetMap area from geofabrik. The region can be changed in the docker-compose file under REGION.

Support for multiple regions is not fully implemented, and requires downloading the regions seperately.

Extract

If you think you may have to setup your database more than once, consider downloading an extract (from geofabrik or elsewhere), you can specify the pbf directory in under volumes in the docker-compose.yml. (delaware is a great state to test with!)

After the file is loaded into the postgis database, you can connect to it locally with the connection information found in docker-compose.yml

Updating

You can update the database by re-running the osm2pgsql docker container, it will use osm2pgsql-replication to update the existing database.

When using multiple regions the REPLICATION_SERVER will be set to https://planet.openstreetmap.org/replication/day/.

Post-Import Hook

The importer supports an optional post-processing hook that runs after successful import or update cycles. This is useful for creating statistics views, refreshing materialized views, or running custom SQL.

Environment Variables

Variable	Required	Default	Description
POST_IMPORT_SQL	No	(empty)	Path to SQL file executed after successful import/update
POST_IMPORT_SCRIPT	No	(empty)	Path to shell script (takes precedence over SQL)
POST_IMPORT_FAIL_HARD	No	true	If true, post-import failure fails the entire import

Execution Behavior

• Script precedence: If POST_IMPORT_SCRIPT is set and exists, it runs instead of SQL
• Skip silently: If neither variable is set or files don't exist, continues without error
• Connection reuse: SQL execution inherits database connection from importer environment
• Logging: Output prefixed with [post-import] to distinguish from import logs

Example Configuration

services:
  osm2pgsql:
    environment:
      # ... other vars ...
      POST_IMPORT_SQL: /osm2pgsql-configs/post-import.sql
      POST_IMPORT_FAIL_HARD: "true"
    volumes:
      - ./osm2pgsql-configs:/osm2pgsql-configs:ro

Writing Idempotent SQL

Post-import SQL should be idempotent (safe to run on both create and update cycles):

-- Drop and recreate pattern (recommended for stats views)
DROP MATERIALIZED VIEW IF EXISTS my_stats;
CREATE MATERIALIZED VIEW my_stats AS SELECT ...;