Self-Hosted Maps
Using OpenStreetMap Data

While ArcGIS and QGIS are great tools for showing spatial data (and made better with a little help from tools like Photoshop or Illustrator) the maps produced are static images, better for print than the web. What if you want something dynamic that a user could zoom into, pan around, or even click on to reveal different information?

System Requirements

The following software will be installed onto a Linux computer running Ubuntu Server 24.04 LTS. This could be an existing system or a new virtual machine, and should work just as well on Ubuntu Desktop. Work is split among available CPUs, so the more you have, the less time it takes

  • Hardware

    • at least 1GB of free SSD disk space plus and 10x the size of the .osm.pbf file

    • at least 0.5x as much free RAM as the input .osm.pbf file size

  • Software to be Installed

    • Planetiler

      https://github.com/onthegomap/planetiler

      Planetiler is a tool that generates Vector Tiles from OpenStreetMap, aiming to be fast and memory-efficient in order to build a map of the world in a few hours on a single machine without any external tools or databases.

    • Martin Map Server

      https://github.com/maplibre/martin

      Martin is a tile server and toolset optimized for speed and heavy traffic that can generate and serve vector tiles on the fly from.

    • Maputnik Map Styler

      https://github.com/maplibre/maputnik

      Maputnik is an open source visual editor for the MapLibre GL stylestargeted at developers and map designers

    • NGINX Web Server

      https://nginx.org/en/

      Nginx ("engine x") is an HTTP web server, reverse proxy, content cache, load balancer, TCP/UDP proxy server, and mail proxy server.

    • Leaflet JavaScript library

      https://leafletjs.com

      Leaflet is the leading open-source JavaScript library for mobile-friendly interactive maps. Weighing just about 42 KB of JS, it has all the mapping most developers ever need

Planetiler

Planetiler is a Java file that requires Java 21+ to be installed on your system. If you don't have it installed, you can do so with the following command:

sudo apt install openjdk-21-jdk -y

After the Java Development Kit has been installed, you can then download the latest version of the Planetiler JAR file using wget.

wget https://github.com/onthegomap/planetiler/releases/latest/download/planetiler.jar

If your system has at least 1.5x as much memory as the input OSM file size, running the following command will have Planetiler use RAM to store node locations during its

java -Xmx110g \
  `# return unused heap memory to the OS` \
  -XX:MaxHeapFreeRatio=40 \
  -jar planetiler.jar \
  `# Download the latest planet.osm.pbf` \
  --area=planet --bounds=planet --download \
  `# Accelerate the download by fetching the 10 1GB chunks at a time in parallel` \
  --download-threads=10 --download-chunk-size-mb=1000 \
  `# Also download name translations from wikidata` \
  --fetch-wikidata \
  --output=output.mbtiles \
  `# Store temporary node locations in memory` \
  --nodemap-type=array --storage=ram

Alternatively, if your system is limited on memory, you can use the following command to store node location cache in a temporary memory-mapped file by setting --storage=mmap and -Xmx#g to change the JVM's memory usage.`

java -Xmx20g \
  -jar planetiler.jar \
  `# Download the latest planet.osm.pbf` \
  --area=planet --bounds=planet --download \
  `# Accelerate the download by fetching the 10 1GB chunks at a time in parallel` \
  --download-threads=10 --download-chunk-size-mb=1000 \
  `# Also download name translations from wikidata` \
  --fetch-wikidata \
  --output=output.mbtiles \
  `# Store temporary node locations at fixed positions in a memory-mapped file` \
  --nodemap-type=array --storage=mmap

Some common arguments:

  • --output tells Planetiler where to write output to, and what format to write it in.
  • --download downloads input sources automatically
  • ‍--area=planet downloads a .osm.pbf full planetary OSM file. Alternatively, you can download an extract from Geofabrik using a regional name.
  • ‍-Xmx1g controls how much RAM to give the JVM (recommended: 0.5x the input .osm.pbf file size to leave room for memory-mapped files)
  • --osm-path=path/to/file.osm.pbf points Planetiler at an existing OSM extract on disk
  • --force overwrites the output file
  • --help shows all of the options and exits

NOTE: This process can take several hours depending on your system hardware and configuration settings. For instance, storing node locations in memory is faster than writing them to disk. Additionally, the default OpenMapTiles profile merges nearby buildings at zoom-level 13 (for example, see Boston). This adds about 14 CPU hours (~50 minutes with 16 CPUs) to planet generation time and can be disabled using --building-merge-z13=false

Martin Map Server

Now that the map data has been reformatted, it needs to be served so that web services can use it. That's the purpose of the Martin Map Server.

Like Planetiler, the package is downloaded onto the system via wget.

wget https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb

Unlike Planetiler however, the software has to be installed onto the system before it can be ran. 

sudo dpkg -i ./martin-Debian-x86_64.deb

Serving your map data can then be accomplished with a single line. This can be scripted so it runs on system startup, but that's an optional step that can be found elsewhere with a simple search.

martin /path/to/output.mbtiles

Once running, Martin will host your map tiles on port 3000. A JSON file listing all of the available sources will be shown at <your_ip_address>:3000/catalog.

{
    "tiles": {
        "output": {
            "content_type": "application/x-protobuf",
            "content_encoding": "gzip",
            "name": "OpenMapTiles",
            "description": "A tileset showcasing all layers in OpenMapTiles. https://openmaptiles.org",
            "attribution": "<a href=\"https://www.openmaptiles.org/\" target=\"_blank\">&copy; OpenMapTiles</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
        }
    },
    "sprites": {},
    "fonts": {}
}

Navigating to a specific tileset, e.g: <your_ip_address>:3000/output, shows the various layer names, field names and formats, the zoom layers they're expected to show at, and the address used to retrieve each map tile.

{
  "tilejson":"3.0.0",
  "tiles":["http://<your_ip_address>:3000/output/{z}/{x}/{y}"],
  "vector_layers":[{
    "id":"aerodrome_label",
    "fields":{
      "class":"String",
      "ele_ft":"Number",
      "icao":"String",
      "name":"String",
      ...},
    "maxzoom":14,
    "minzoom":8
    },{
    "id":"boundary",
    "fields":{
      "adm0_l":"String",
      "adm0_r":"String",
      ...

Maputnik Map Styler

Having data by itself is meaningless, and without a way to style the map data, none of it will be seen. Maputnik allows you to apply custom styling to each layer exposed by Martin and, although it can be hosted locally on your own system, the MapLibre's hosted version works well enough for a standard OSM file.

https://maplibre.org/maputnik

The easiest way to get started is choosing an existing style as a starting point. Once opened. Each come from various sources, and may not match our layers exactly, but the MapTiler Basic does pretty well.

Once you are done editing the style, you'll need to change the data source to your Martin server. You could also expose Martin so that it's reachable outside of your LAN, but there's too many security concerns and other issues to go into here.
‍
Go into the Data Sources, add a new source and delete the pre-existing active source.

  • Source ID - openmaptiles (or whatever the name of the current active source is, without the #)
  • Source Type - Vector (Tile URLs)
  • Tile URL - http://<your_ip_address>:3000/output/{z}/{x}/{y} whatever was specified in your tile set)
  • Scheme Type - xyz (Slippy map tile names scheme)
  • Min Zoom - 0
  • Max Zoom - 14

Download the modified style in JSON format.

While Maputnik can provide nearly infinite options for creating custom map styles, map design is a complex subject, focused not only the look of the map, but also choices about data, interaction, and more. If you're interested in more information about how to better use Maputnik to create a pleasing visual style, I'd suggest looking at the link below.

https://github.com/maplibre/maputnik/wiki

NGINX

NGINX is a web server that allows you to host the various files and tools that allow people to view your maps. Since we're doing all of this on an Ubuntu server, it's easiest to use their simple installation guide

https://ubuntu.com/tutorials/install-and-configure-nginx

Mapping a shared folder allows you to easily upload new styles, data overlays, and more without needing to regularly log into your map server. If you're mapping a folder housed on a Windows system, you can permanently mount the folder using CIFS 

sudo apt install cifs-utils

Create a file in the root directory to hold the credentials, and populate it with the username, password, and domain or workgroup name of a Windows user with access to the folder.

sudo nano /root/.creds

username=shared_usr
password=secret
domain=mydomain_or_workgroup

With the permissions file made, you can now edit the /etc/fstab file to map the Windows folder to the /var/www/html folder that NGINX will use to serve files from.

sudo nano /etc/fstab

//IP/Share/Folder\040Path/ /var/www/html cifs _netdev,vers=3.0,noperm,credentials=/root/.creds

NOTE: Any spaces within your folder's path or folder name will need to be replaced with \040 to be recognized as a space by the Linux system. So, a path of //172.16.0.12/shares/My Shared Folder will look like
//172.16.0.12/shares/My\040Shared\040Folder

Once saved, the folder will be auto-mapped each time the computer starts. To avoid performing a reboot now, you can simply do the following: 

mount -o remount -a

Leaflet

To show and interact with your map, you need a webpage that can display your custom map styles. Leaflet is a JavaScript library that can be added to an existing page with only a few lines of code, and can be extended through the use of plugins.

To add Leaflet to a webpage, references to Leaflet's CSS and JS files need to be added to the page's head section. These files can either be downloaded to the shared folder you just created, or linked to a set hosted by the UNPKG CDN. In the examples below, we're linking to the hosted versions of files. 

 <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"/>
 <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

We'll also need references to the MapLibre GL JavaScript library to translate our vector maps into a format that Leaflet can understand. Like before, while these can reference a self-hosted version, we'll be linking to the CDN version. Add these lines to your page's head section, just below the Leaflet references.

 <link href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css" rel='stylesheet' />
 <script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>
 <script src="https://unpkg.com/@maplibre/maplibre-gl-leaflet@0.0.22/leaflet-maplibre-gl.js"></script>

In the page's body, add a div element with a unique id where you want your map to be. This will act as a container for your map. Make sure it has a specified height, either by defining it as an inline style or by adding it to your page's CSS file.

<div id="my_map" style="height:300px"></div>

With the initial setup complete, we can now add and configure our map. At the bottom of your page's body, add the following script.

<script type="text/javascript">
  var map = L.map('my_map').setView([40.71, -74.0], 8);
  var gl = L.maplibreGL({
    style: 'http://your_ip_address/custom_style.json'
  }).addTo(map);
</script>

A breakdown of what that script is.

  • var map = L.map('my_map').setView([40.71, -74.0], 8);
    This line defines our map and links it to the container we specified earlier. The setView function centers the map on a specific latitude and longitude, and sets a zoom level.
  • var gl = L.maplibreGL({
      style: 'http://your_ip_address/custom_style.json'
    }).addTo(map);
    This line tells Leaflet to add a MapLibreGL layer with a specified style to our map object. In our case, it's the custom style we saved from Maputnik and copied to the shared Nginx folder

You can also add more functions to this portion of the script, to display GPX files, interactive markers and polygons, GIS data, and other items. Browse through Leaflet's plugins to see the different options and how to use them.
‍
Putting this all together, a bare-minimum webpage that shows a full-screen map centered on New York City would look like below.

<html>
<head>
  <title>A Basic Webmap</title>
  <style>
    html, body, #map {
      width: 100%;
      height: 100%;
      margin: 0px;
    }
  </style>
  
  <!-- Leaflet -->
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"/>
  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
  <!-- Maplibre GL -->
  <link href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css" rel='stylesheet' />
  <script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>
  <script src="https://unpkg.com/@maplibre/maplibre-gl-leaflet@0.0.22/leaflet-maplibre-gl.js"></script>
</head>

<body>
  <div id="map"></div>
  <script type="text/javascript">
    var map = L.map('map').setView([40.71, -74.0], 8);
    var gl = L.maplibreGL({
      style: 'http://your_ip_address/custom_style.json'
    }).addTo(map);
  </script>
</body>
</html>

Save this file to your shared folder as index.html, and you'll be able to navigate to it by pointing your web browser to http://<your_ip_address>

Result