Chapter 7

This chapter will show how you can establish completely free OSM based map by using United Nations Vector Tiles Toolkits (UNVT). In Rwanda and Kenya, we are using UNVT as one of base maps which is completeley license free’s map generated from Open Street Map.

If you are suffering for the payment for Google Map, Mapbox, Maptiler or any other map services providers, UNVT would be the great tool for your organization.

Hosting UNVT map for a country on Github pages

UNVT is mainly designed for operating on Raspberry Pi, however it can be hosted on Github pages to distribute OSM based vactor tiles. It can produce vector tiles very fast and lightly.

For hosting on Github pages, you can use unvt/naru respository.

Here, I introduce how to generate by using Docker.

1. Fork unvt/naru

Firstly, you can fork unvt/naru on your Github.

2. Setup

Firstly, you can install Docker and docker-compose on your computer either Windows, MacOS or Linux. See the instruction here.

Then, you can download the source code from Github, and build Docker image.

git clone{your organization name}/naru.git
cd naru
docker build . --tag unvt/naru
3. Generate vector tiles
cd naru
docker run -v $(pwd):/usr/src/app -p 9966:9966 -it unvt/naru
# now you entered into Docker container
cd /usr/src/app
cp .env.example .env
vi .env # edit environmental variable

Here, we are going to generate UNVT map for Rwanda in Easern Africa. You can confirm the region and area on Geofabrik.

The below is an example of .env.


Now, you execute the following commands to generate each components for vector tiles map.

rake inet:download # download osm.pbf
rake inet:mbgljs # download mapbox-gl-js package
rake js # rollup javascript code
rake inet:sprite # download maki and build sprite
rake inet:fonts # download fonts and create glyphs
rake tiles # create mbtiles under src folder
rake style # create style.json

After running the above commands, all of resources will be created under docs folder. docs folder is normally used for Github pages public directory.

the structure of docs directory should be as below.

Now you can ready to check your map on local browser!

Just run the below command to host tiles by budo.

rake host

open http://localhost:9966 on your browser to check your UNVT map.

4. Uploading tiles to Github

If your UNVT map’s everything is okay, you can now upload it to Github for publishing.

git add docs -f  # we use -f option to force to commit all documents
git commit -m "generated vectortiles"
git push origin master
5. Make docs folder publish as Github pages

Go to settings of your naru repository page, then you can find Github Pages section on Options tab. You can configure github pages there.

Please also see more detailed information on their public website here.

After publishing as Github pages, you can access your UNVT map from the URL like https://{your organization}

Also, you can access your all components of map as following.

  • Vector Tiles
https://{your organization}{z}/{x}/{y}.pbf
  • Sprite file
https://{your organization}
  • Glyphs
https://{your organization}{fontstack}/{range}.pbf

Advanced development

a. Interageration Natural Earth Map for low scale zoom levels 0 - 5

UNVT’s OSM map only generate zoom level 6 to 15. If you need low scale map, you can add Natural Earth based UNVT.

In order to add Natural Earth Map, you need to modify Rakefile in your repository.

  • rake inet:download section
desc 'download source geospatial data to the place'
task :download do
  if !File.exist?("src/#{AREA}-latest.osm.pbf")
    u = "{REGION}/{#{AREA}-latest.osm.pbf}"
    sh "curl -C - #{u} --output './src/#1'"
  # add the below command.
  if !File.exist?("src/ne_tiles.mbtiles")
    u = "{ne_tiles.mbtiles}"
    sh "curl -C - #{u} --output './src/#1'"
  • rake tiles section
desc 'build tiles from source data'
task :tiles do
  sh "osmium export --config osmium-export-config.json --index-type=sparse_file_array --output-format=geojsonseq --output=- src/#{AREA}-latest.osm.pbf | node filter.js | tippecanoe --no-feature-limit --no-tile-size-limit --force --simplification=2 --maximum-zoom=15 --base-zoom=15 --hilbert --output=#{MBTILES}"
  # You need to tile-join tiles.mbtiles and ne_tiles.mbtiles
  sh "tile-join --force --no-tile-compression --output-to-directory=docs/zxy --no-tile-size-limit #{MBTILES} src/ne_tiles.mbtiles"
  • add style for Natural Earth layers You need to add style for additional natural earth layers. You can use the style from this repository. I indicated the file name start with ne- as Natural Earth layers.

If you think it is difficult, just simply copy hocon folder from WASAC/naru repository.

b. Automate to update tiles data by using Github Actions

WASAC/naru repository is fully adopted Github Actions to automate updating OSM data.

You can use the same workflow file for your repository.

deploy.yaml. This yaml is for updating every two weeks on 1st and 15th each month.

name: deploy

  # push:
  #   branches: [ develop ]

    - cron:  '0 0 1,15 * *'


    runs-on: ubuntu-latest
    - uses: actions/checkout@v2
    - name: Generate tiles
        REGION: africa
        AREA: rwanda
      run: |
                docker-compose up
    - name: Use Node.js
      uses: actions/setup-node@v1
        node-version: 12.x
    - run: yarn
    - name: configure git and deploy
        NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}
        # below option might be required for large area of the country's map
        NODE_OPTIONS: "--max-old-space-size=8192"
      run: |
        git config --global "{your organization name}+githubci"
        git config --global "{your organization name}"
        git remote set-url origin https://x-access-token:${NODE_AUTH_TOKEN}{your organization name}/naru.git
        yarn run deploy