How to use this image

This image on startup initializes with data on first start. To do it properly it needs a bit of guidance in form of enviroment variables.

• OVERPASS_MODE - takes the value of either init or clone
• OVERPASS_META - yes, no or attic - passed to Overpass as --meta or --keep-attic
• OVERPASS_DIFF_URL - url to diff's directory for updating the instance (eg. https://planet.openstreetmap.org/replication/minute/)
• OVERPASS_PLANET_URL - url to "planet" file in init mode
• OVERPASS_COMPRESSION - takes values of no, gz or lz4. Specifies compression mode of the Overpass database. Ony useful in init mode. Defaults to gz
• OVERPASS_RULES_LOAD - desired load generated by areas generation. Controls how long the script will sleep before regenerating areas. Set it to 1, and script will sleep 99x times longer than it works, set it to 50 - and script will sleep as long as last execution, set it to 100, and script will sleep 3 seconds between each execution. Defaults to 1.
• OVERPASS_UPDATE_SLEEP - integer, how long is the delay between updates (seconds)
• OVERPASS_COOKIE_JAR_CONTENTS - cookie-jar compatible content to be used when fetching planet.osm file and updates
• OVERPASS_PLANET_PREPROCESS - commands to be run before passing planet.osm file to update_database, e.g. conversion from pbf to osm.bz2 using osmium
• USE_OAUTH_COOKIE_CLIENT - set to yes if you want to use oauth_cookie_client to update cookies before each update. Settings are read from /secrets/oauth-settings.json. Read the documentation here
• OVERPASS_FASTCGI_PROCESSES - number of fcgiwarp processes. Defaults to 4. Use higher values if you notice performance problems.
• OVERPASS_RATE_LIMIT - set the maximum allowed number of concurrent accesses from a single IP
• OVERPASS_TIME - set the maximum amount of time units (available time)
• OVERPASS_SPACE - set the maximum amount of RAM (available space) in bytes
• OVERPASS_MAX_TIMEOUT - set the maximum timeout for queries (default: 1000s). Translates to send/recv timeout for fastcgi_wrap

Image works in two modes clone or init. This affects how the instance gets initialized. If the mode is set to clone then data is copied from http://dev.overpass-api.de/api_drolbr/ and then updated from diffs. This will result in Overpass instance covering whole world. This mode works only with minute diffs.

In init mode you need to point OVERPASS_PLANET_URL to address with planet (partial) dump. This file will be downloaded, indexed by Overpass and later - updated using OVERPASS_DIFF_URL.

Start initalization mode with -i and -t options to docker run so you will have a chance to monitor the progress of file downloads etc.

After initialization is finished Docker container will stop. Once you start it again (with docker start command) it will start downloading minute diffs, applying them to database and serving API requests.

Container exposes port 80, map it to your host port using -p. Overpass API is available at /api/interpreter.

Container includes binaries of pyosmium (in /app/venv/bin/) and osmium-tool (in /usr/bin)

All data resides within /db directory in container.

Examples

Overpass instance covering part of the world

In this example Overpass instance will be initialized with planet file for Monaco downloaded from Geofabrik. Data will be stored in folder /big/docker/overpass_db/ on the host machine. Overpass will be available on port 12345 on host machine. Data will not contain metadata as this example uses public Geofabrik extracts, that do not contain metadata (such as changeset and user).

docker run \
  -e OVERPASS_META=yes \
  -e OVERPASS_MODE=init \
  -e OVERPASS_PLANET_URL=http://download.geofabrik.de/europe/monaco-latest.osm.bz2 \
  -e OVERPASS_DIFF_URL=http://download.openstreetmap.fr/replication/europe/monaco/minute/ \
  -e OVERPASS_RULES_LOAD=10 \
  -v /big/docker/overpass_db/:/db \
  -p 12345:80 \
  -i -t \
  --name overpass_monaco wiktorn/overpass-api

Overpass clone covering whole world

In this example Overpass instance will be initialized with data from main Overpass instance and updated with master planet diffs. Data will be stored in /big/docker/overpass_clone_db/ directory on the host machine and API will be exposed on port 12346 on host machine.

docker run \
  -e OVERPASS_META=yes \
  -e OVERPASS_MODE=clone \
  -e OVERPASS_DIFF_URL=https://planet.openstreetmap.org/replication/minute/ \
  -v /big/docker/overpass_clone_db/:/db \
  -p 12346:80 \
  -i -t \
  --name overpass_world \
  wiktorn/overpass-api

Overpass instance covering part of the world using cookie

In this example Overpass instance will be initialized with planet file for Monaco downloaded from internal Geofabrik server. Data will be stored in folder /big/docker/overpass_db/ on the host machine. Overpass will be available on port 12347 on host machine.

Prepare file with your credentials /home/osm/oauth-settings.json:

{
  "user": "your-username",
  "password": "your-secure-password",
  "osm_host": "https://www.openstreetmap.org",
  "consumer_url": "https://osm-internal.download.geofabrik.de/get_cookie"
}

Because Geofabrik provides only PBF extracts with metadata, osmium is used in OVERPASS_PLANET_PREPROCESS to convert pbf file to osm.bz2 that's used by Overpass.

docker run \
    -e OVERPASS_META=yes \
    -e OVERPASS_MODE=init \
    -e OVERPASS_PLANET_URL=https://osm-internal.download.geofabrik.de/europe/monaco-latest-internal.osm.pbf \
    -e OVERPASS_DIFF_URL=https://osm-internal.download.geofabrik.de/europe/monaco-updates/ \
    -e OVERPASS_RULES_LOAD=10 \
    -e OVERPASS_COMPRESSION=gz \
    -e OVERPASS_UPDATE_SLEEP=3600 \
    -e OVERPASS_PLANET_PREPROCESS='mv /db/planet.osm.bz2 /db/planet.osm.pbf && osmium cat -o /db/planet.osm.bz2 /db/planet.osm.pbf && rm /db/planet.osm.pbf' \
    -e USE_OAUTH_COOKIE_CLIENT=yes \
    --mount type=bind,source=/home/osm/oauth-settings.json,target=/secrets/oauth-settings.json \
    -v /big/docker/overpass_db/:/db \
    -p 12347:80 \
    -i -t \
    --name overpass_monaco wiktorn/overpass-api

How to use Overpass API after deploying using above examples

Overpass API will be exposed on specified port (12345 or 12346 resp.) - as for example http://localhost:12346/api/interpreter. You may then use this directly as Overpass API url, or use it within Overpass Turbo. Just go to settings and set Server to: http://localhost:12345/api/, now you will use your local Overpass instance for your queries.