Serving Your Own OpenStreetMap Tiles with Portainer

Want to take control of your map data? This guide will walk you through setting up your very own OpenStreetMap tile server using Docker and Portainer. We'll leverage the excellent overv/openstreetmap-tile-server Docker image, and you'll have the flexibility to choose between using Docker volumes or mounting a host folder for your map data.

Prerequisites

• Docker and Portainer: Ensure you have Docker installed and Portainer running on your server.
• OpenStreetMap Data: Download an OSM data file (.osm.pbf format) for your desired region from a provider like Geofabrik.
• Server Access: You'll need access to your server's Portainer interface and potentially the command line.

Method 1: Using a Docker Volume for Data Persistence

This method is great for keeping your Docker environment clean and self-contained. The data is managed by Docker itself.

Step 1: Create the Data Volume

1. In Portainer, navigate to Volumes in the left menu.
2. Click the + Add volume button.
3. Enter osm-data as the Name.
4. Click Create the volume.

Step 2: Import the Map Data

1. Go to Containers and click + Add container.
2. Name: osm-importer (this is temporary).
3. Image: overv/openstreetmap-tile-server:latest.
4. Volumes: Click map additional volume twice.
   • Map 1 (Bind Mount - for the .pbf file):
     • Type: Bind
     • Host path: (Replace with the absolute path to your .osm.pbf file, e.g., /srv/data/zambia-latest.osm.pbf)
     • Container path: /data/region.osm.pbf
   • Map 2 (Named Volume - for the database):
     • Type: Volume
     • Volume: Select the osm-data volume you created.
     • Container path: /data/database/
5. Under the Command & logging tab, in the Command field, enter import.
6. Click Deploy the container.
7. Monitor the container logs until you see INFO:root: Import complete. Once done, you can stop and remove the osm-importer container.

Step 3: Run the Tile Server

1. Go to Containers and click + Add container.
2. Name: osm-tile-server.
3. Image: overv/openstreetmap-tile-server:latest.
4. Ports: Click publish a new network port.
   • Host: 8080 (or an available port).
   • Container: 80.
5. Volumes: Click map additional volume.
   • Type: Volume
   • Volume: Select the osm-data volume.
   • Container path: /data/database/
6. Under the Command & logging tab, in the Command field, enter run.
7. Under the Restart policy tab, set it to Unless stopped.
8. Click Deploy the container.

Method 2: Using a Host Folder (Bind Mount) for Data

This method is useful if you want direct access to the database files on your server for backups or inspection.

Prerequisites (for Host Folder Method)

• Ensure you have an empty folder on your server where the map database will be stored (e.g., /srv/data/osm-database).

Step 1: Import the Map Data

1. Go to Containers and click + Add container.
2. Name: osm-importer (temporary).
3. Image: overv/openstreetmap-tile-server:latest.
4. Volumes: Click map additional volume twice.
   • Map 1 (Bind Mount - for the .pbf file):
     • Type: Bind
     • Host path: (Replace with the absolute path to your .osm.pbf file, e.g., /srv/data/zambia-latest.osm.pbf)
     • Container path: /data/region.osm.pbf
   • Map 2 (Bind Mount - for the database folder):
     • Type: Bind
     • Host path: (Replace with the absolute path to your empty database folder, e.g., /srv/data/osm-database)
     • Container path: /data/database/
5. Under the Command & logging tab, in the Command field, enter import.
6. Click Deploy the container.
7. Monitor the container logs until you see INFO:root: Import complete. Once done, you can stop and remove the osm-importer container.

Step 2: Run the Tile Server

1. Go to Containers and click + Add container.
2. Name: osm-tile-server.
3. Image: overv/openstreetmap-tile-server:latest.
4. Ports: Click publish a new network port.
   • Host: 8080 (or an available port).
   • Container: 80.
5. Volumes: Click map additional volume.
   • Type: Bind
   • Host path: (Replace with the absolute path to your database folder, e.g., /srv/data/osm-database)
   • Container path: /data/database/
6. Under the Command & logging tab, in the Command field, enter run.
7. Under the Restart policy tab, set it to Unless stopped.
8. Click Deploy the container.

Verification and Troubleshooting

Verify Your Setup

Whichever method you chose, you can verify it's working by opening your web browser and navigating to:

• http://<your-server-ip>:8080/tile/0/0/0.png (You should see a map image of the world)
• http://<your-server-ip>:8080 (You should see a fully interactive map)

Troubleshooting Tips

• Permissions: If using a bind mount, ensure Docker has the necessary read/write permissions for your host folders.
• Disk Space: Creating the tile database can require significant disk space (30GB+ for even small extracts).
• Import Errors: If the import fails, you must delete the data and start over. For Method 1, delete the osm-data Docker volume. For Method 2, delete the contents of your host database folder. Check the container logs for clues.

Congratulations! You've now set up your own OpenStreetMap tile server using Portainer. You can further explore the overv/openstreetmap-tile-server image documentation for more advanced configuration options.