Welcome to our workshop organized by MapLibre! We hope you will have fun and learn something useful.
- Create your own vector tiles with Planetiler.
- Host the vector tiles you created with Martin.
- Learn how create a MapLibre style with Maputnik.
- Intergrate your map on a web page with MapLibre GL JS.
To make best use of the time available for this workshop, we will use GitHub Codespaces to set up the development environment.
Go to the workshop repository, in the top right click the Code, then go to the Codespaces tab and click the right button to start a new codespace.
After downloading the Docker image that we prepared for you you will be dropped into a shell. If not, click the small Plus sign above the terminal window to create another shell.
We already downloaded a Boston OSM extract created with slice.openstreetmap.us.
Run the following command.
java -jar /planetiler.jar --download_dir=/data/sources --minzoom=0 --maxzoom=14 --osm_path=/data/sources/boston.osm.pbf
You should see planetiler generate a new file data/output.mbtiles. Use ll data/output.mbtiles to see it.
The MBTiles file that was generated in the previous step can be hosted with a tile server. In this workshop we will use Martin, which is pre-installed to the development container.
Run the following command:
martin data/output.mbtiles
Martin will launch on port 3000. You will get a prompt to expose this port. Expose the port to the internet.
Go to the Ports tab in VS Code to see the public URL for your Martin instance.
Make sure it is set to "Public" you can right-click to change the Visibility.
When you open the URL it shows, you should see the message:
Martin server is running.
The WebUI feature can be enabled with the --webui enable-for-all CLI flag or in the config file, making it available to all users.
A list of all available sources is at /catalog
See documentation https://github.com/maplibre/martin
Go to the catalog, and then to /output. This is a TileJSON endpoint which describes the tiles hosted at that path.
Go to Maputnik, click open and open the empty style. Next, add a new source. Use the URL of your Martin instance with the /output TileJSON endpoint.
Since you don't have any layers, you will not see anything visualized. Hower, you can switch from the 'Map' view to the 'Inspect' view to see the data contained in your tiles. If it looks something like this, you are doing great so far!
Note that we only have detailed tiles in Massachusetts due to the OSM extract that we used. To generate vector tiles for the entire world would require a more powerful server than the one that GitHub Codespaces offers!
Try adding some layers. Refer to the MapLibre Style Spec to see what kind of layers you can add. An easy one might be one for the ocean or other water bodies.
Check out what attributes exist in the Inspect view or refer to the documentation of the OpenMapTiles Schema, which is the tile schema that Planetiler uses by default.
When you are happy with the style you are created, go to Save in the top bar and then Create HTML.
Create an index.html in your Codespace and paste the contents of the HTML file that was downloaded. Next, launch a simple web server and expose it to the internet like before.
python -m http.server 1234
If everything went well, you will have created your own basemap and deployed it in under one hour!
Take a closer look to the generated HMTL to understand how MapLibre GL JS is set up. Explore the MapLibre GL JS documentation to see what APIs exist. Try for example to add markers to the map when you click somewhere.
scripts/benches.yaml describes how to create custom map tiles with planetiler containing all of the benches in Boston. Run it using the following command:
java -jar /planetiler.jar scripts/benches.yaml --download_dir=/data/sources --minzoom=0 --maxzoom=14 --osm_path=/data/sources/boston.osm.pbf --output=data/benches.mbtiles
Then run martin again to serve those tiles:
martin data/output.mbtiles data/benches.mbtiles
And you can add the source to Maputnik using https://{public URL for your Martin instance}/benches