Introduction
Note (1 November 2020)

We shall shortly update these notes since the baremaps source is now version 0.2.9, not 0.2.7 as indicated below.


In focussing on OpenStreetMap technologies for use at the project level in various contexts - see summary - for planning, design, supervision, procurement, contracts, certification, project management, project supervision, contract administration, etc., we have yet to design and organise a suitable wiki site.  Regarding implementation details for the various core technologies, for the time being we shall use blog items. This item is for Baremaps OpenStreetMap vector tiles which are currently under development, but workable nonetheless - see bares.peterboswell.net.

Baremaps



Baremaps provides an excellent way to serve vector tiles from an OpenStreetMap (OSM) database.

This is say, data is exported from a self-hosted OpenStreetMap "Rails Port" using Osmosis.

On Ubuntu18.04LTS, for user "ertert", I give terminal commands "as is" (i.e., with unedited paths).The Osmosis command to download from a local OSM Rails Port is:

/home/ertert/osm/osmosis/bin/osmosis --read-apidb-change host="localhost" database="openstreetmap" user="ertert" password="ertert" intervalBegin="2020-05-29_00:00:00" intervalEnd="2020-09-05_00:00:00" validateSchemaVersion="no" --write-xml-change file="/home/ertert/osm-site/sync_osm_databases/main-db-changes.xml"

It's probably wise to convert main-db-changes.xml to a pbf file (Osmium is recommended):

osmium cat main-db-changes.xml -o main-db-changes.pbf


Set up



To set up Baremaps, following Baremaps,  git clone from say a home directory (/home/ertert in my case):

  • $ cd
  • $ git clone https://github.com/baremaps/baremaps.git

While in /home/ertert, set the PATH:

  • export PATH=$PATH:`pwd`/baremaps/bin
  • cd baremaps

Download baremaps.zip

  • wget https://github.com/baremaps/baremaps/releases/latest/download/baremaps.zip

and

  • unzip baremaps.zip

Test



It is best to first do a test with a small map. Currently, one only has a Docker image to fill a postgis extended postgresql database (i.e., source files are not available). So run the following:

  • docker run --name baremaps-postgis --publish 5432:5432 -e POSTGRES_DB=baremaps -e POSTGRES_USER=baremaps -e POSTGRES_PASSWORD=baremaps -d baremaps/postgis:latest

One of course needs a postgresql port (5432) to be available. So for example, shut down postgresql if it  is running (sudo service postgresql stop).

One can of course change the postgresql port by using say 5433:5432 instead of 5432:5432.

Baremaps provides an OpenStreetMap example. The simplest is to copy/download config.yaml  to /home/ertert/baremaps.

An osm file for say Liechenstein is then imported into the postgresql database:

  • baremaps import --input 'liechtenstein-latest.osm.pbf' --database 'jdbc:postgresql://localhost:5432/baremaps?allowMultiQueries=true&user=baremaps&password=baremaps'

liechtenstein-latest.osm.pbf is available on the baremaps github site as liechtenstein-latest.osm.pbf but also elsewhere (e.g., Geofabrik) and as a wget:

  • wget https://download.geofabrik.de/europe/liechtenstein.html

The terminal command to load the database is:

  • baremaps import --input 'liechtenstein-latest.osm.pbf' --database 'jdbc:postgresql://localhost:5432/baremaps?allowMultiQueries=true&user=baremaps&password=baremaps'

The command:

  • baremaps serve--database 'jdbc:postgresql://localhost:5432/baremaps?allowMultiQueries=true&user=baremaps&password=baremaps' --config 'config.yaml' --watch-changes

starts a tile server at http://localhost:9000 showing what is called a Mapbox blueprint style three-dimensional map of Liechtenstein.

openstreetmap-vecto


To display the OSM database tiles, while in /home/ertert/basemaps git clone OpenStreetMap-vecto from github:

  • git clone https://github.com/baremaps/openstreetmap-vecto.git

and then move to the directory (/home/ertert/openstreetmap-vecto):

  • cd openstreetmap-vecto

To ensure that cached images are not used, the suggestion at this stage is to make sure that you have no Docker images and containers present on your system. You may need to stop the test:

  • docker stop baremaps-postgis

and then purge your system:

  •  docker system prune

Edit web page


Before setting up the OSM tiles you may want to add some controls and the like to the map (Baremaps currently includes none).

A relatively simply way is to edit the resources file that is used by the Baremaps java application.

In /home/ertert/baremaps/baremaps-cli/src/main/resources there is index.ftl. Edit this Mapbox file by perhaps changing the title, adding controls:

  • map.addControl(new mapboxgl.NavigationControl());
For adding a marker:

  var popup = new mapboxgl.Popup({ offset: 25 })

   .setText('Marais Rouge parking');

var marker = new mapboxgl.Marker()

   .setLngLat([6.157468, 46.484028])

   .setPopup(popup)

   .addTo(map);

The Mapbox  examples  indicate what is possible.

Personally, I also prefer to host the Mapbox files on my own servers. So for a standard Apache2 web server set-up I download mapbox-gl.css and mapbox-gl.js, copy them to /var/www/html/baremaps and edit index.ftl as follows:

<link href='http://map.peterboswell.net/bearmaps/mapbox-gl.css' rel='stylesheet'/>

<script src='http://map.peterboswell.net/baremaps/mapbox-gl.js'></script>

The files are downloaded using for example the links given in index.ftl:

  • wget https://api.mapbox.com/mapbox-gl-js/v0.44.0/mapbox-gl.css
  • wget https://api.mapbox.com/mapbox-gl-js/v0.44.0/mapbox-gl.js

In order to incorporate the edited index.ftl file it is necessary to compile the Baremaps Java application. Using Maven is perhaps the simplest. So in /home/ertert/baremaps:

  • mvn clean package

There is one complication. A relatively well-known byte error may be thrown during execution if the Java version used to compile Baremaps is not the same as that used by the Baremaps developers. 

The simplest solution is to run the Maven package with the same version as the Java version of the jar files in baremaps.zip (which was downloaded at the begining). The jar files in baremaps.zip are currently version 0.2.6 (i.e., the cli jar file in /home/ertert/baremaps/baremaps.zip/baremaps/lib is called baremaps-cli-0.2.6.jar). The Java version of baremaps-cli is currently 0.2.7. 

It is necessary to change the version of baremaps-cli to 0.2.6 by running:

  • mvn versions:set -DnewVersion=0.2.6

and copy/pastebaremaps-cli-0.2.6.jar in /home/ertert/baremaps/baremaps-cli/target/ to /home/ertert/baremaps.zip/baremaps/lib

The zip file with the edited baremaps-cli jar file should then be copied to /var/www/html/baremaps:

  • sudo cp /home/ertert/baremaps/baremaps.zip /var/www/html/baremaps
This procedure possibly assume that baremaps-cli does not change when other basemaps jars are changed to new versions. This seems to be the case at present.

Build - baremaps.zip


As explained on the  Baremaps openstreemap-vecto github page, the Docker image for vecto is built using: 

  • docker build . --tag baremaps/osmvecto  --no-cache

with the "no-cache" added to ensure once again that cached layers are not included in the image.

Personally, I have a Docker account called something like peter, so I would use:

  • docker build . --tag peter/osmvecto 

and push the Docker image after it is built to Docker using:

  • docker push peter/osmvecto

Before building, one needs to edit the Dockerfile in /home/ertert/baremaps/openstreetmap-carto by changing: 

RUN wget https://github.com/baremaps/baremaps/releases/latest/download/baremaps.zip 

to the baremaps.zip at the website:

RUN wget http://map.peterboswell.net/baremaps/baremaps.zip  

Build - script


The build command calls a script (scripts/input.sh). In order to display the database data (main-db-changes.pbf - see above), input.sh needed to be edited by changing: 

wget -O openstreetmap.pbf https://download.geofabrik.de/europe/switzerland-latest.osm.pbf

to:

wget -O openstreetmap.pbf http://maps.peterboswell.net/baremaps/main-db-changes.pbf

Build and serve


Once:

  • docker build . --tag peter/osmvecto 

is run and the image maybe pushed to Docker, the image is run (from a terminal at /home/ertert/baremaps/openstreetmap-vecto):

  • docker run -d --name osmvecto --publish 5432:5432 --publish 9000:9000 --volume $(pwd):/home peter/osmvecto:latest

and the data is imported into the database:

  • docker exec -ti osmvecto bash -c scripts/import.sh

and the Baremaps tile server is started with:

  • docker exec -ti osmvecto bash -c scripts/start.sh

Configuration


The config.yaml file at /home/ertert/baremaps/openstreetmap-carto can be altered while the server is live. Personally, I change the host and port:

host: 192.168.1.111

port: 9090

and proxy to this from an Apache2 website.

The stylesheets are in development. An interesting change is to add the following to the building layer file (/home/ertert/baremaps/openstreetmap-vecto/config/building/layer.yml)

  - minZoom: 14

    maxZoom: 18

    sql: 

      SELECT id, tags, geom 

      FROM osm_nodes WHERE tags ? 'building'

  - minZoom: 14

    maxZoom: 18

    sql: 

      SELECT id, tags || hstore('building:height'::text, ((CASE WHEN tags -> 'building:levels' ~ '^[0-9\.]+$' 

      THEN tags -> 'building:levels' 

      ELSE '1' END)::real * 3)::text), geom 

      FROM osm_ways 

      WHERE tags ? 'building' 

It gives extruded three-dimensional buildings based on the building level as explained in the Baremaps building example.

Updating

 


One suspects that it should be possible to update the Docker image directly and not rebuild the image each time index.ftl is changed. For example, following the command:

  • docker run -it peter/osmvecto:latest /bin/bash

the command: 

  • find / -type f -iname "*baremaps*"

lists the baremaps jar files.

baremaps-cli-0.2.6.jar is removed with:

  • rm /lib/baremaps-cli-0.2.6.jar

and the new baremaps-cli-0.2.6.jar discussed above can be copied into the image with:

  • sudo docker baremaps-cli-0.2.6.jar abcdef123456:/lib 

after submitting "exit" to exit the docker container. One understands that the id of the parent Docker layer is abcdef123456 which is displayed at the command prompt on running the bin/bash/ command. 

This approach needs checking as locally build Docker images are relatively complicated.

Precautions


Take care to run the import.sh and start.sh terminal commands from /home/ertert/baremaps/openstreemap-vecto otherwise the bash command may not work (a fairly well known issue).

Conclusion


There is of course much to be done in terms of completing the layers and style sheets. But overall the results so far are excellent since a fairly complicated pipeline can be set up and adjusted to a limited extent to give workable, OSM vector tiles, not only at a localised project level but also at a much larger, even global, scale.


5 September 2020


Email: peter@peterboswell.com
Phone: +41792989666
Skype: live:petergboswell
WhatsApp: PeterBoswellcom
Messenger: petergboswell
Telegram: PeterBoswellBot
LinkedIn
Facebook
Twitter
OneName