# inazo-steps: step-by-step tutorial of `inazo`


# The step-by-step guide
## 0. What is this?
This is a step-by-step guide that introduce how to use [unvt/inazo](https://hub.docker.com/r/unvt/inazo/tags).

The Docker container image `unvt/inazo` is a package of the [United Nations Vector Tile Toolkit](https://github.com/un-vector-tile-toolkit) for hands-on training and demo purpose.

[EuroGlobalMap](https://github.com/optgeo/geojsons-euroglobalmap) is used as the source data.

### Related materials
#### JICA training material
This material is prepared in tandem with the JICA traing course slides below:

{%speakerdeck smellman/distrubute-vector-tile %}

#### FOSS4G 2019 presentation
You may want to check the following slides:

{%speakerdeck hfu/design-and-development-of-the-un-vector-tile-toolkit %}

### What is the United Nations Vector Tile Toolkit?
1. The United Nations Vector Tile Toolkit (UNVT) is an Open Source software toolkit that supports production of vector tiles from vector data, hosting vector tiles, styling vector tiles, and optimizing the size of vector tiles, by making use of existing Open Source software.
2. UNVT is a project under the United Nations Open GIS Initiative. Engineers from the following organizations are participating to the UNVT project: the United Nations Geospatial Information Section (UNGIS), the United Nations Global Service Centre (UNGSC), the Geospatial Information Authority of Japan (GSI), the National Institute for Agro-Environmental Sciences (NIAES), OSGeo Japan Chapter (OSGeo.JP), Mapbox Inc., and Mapple ON Co., Ltd.
3. Current focus of the project is on developing an Docker container image named `rasv` that contain UNVT.
4. This hands-on material titled `inazo` is based on this `rasv`.

## 0. What is the result of this hands-on session?
You will be able to produce and host the web map as below.

<iframe width='100%' height='500px' src='https://un-vector-tile-toolkit.github.io/inazo-static'>
</iframe>

This site shows coastline, road, and boundary data from EuroGlobalMap. Because the data contains other layers, you will be able to add other layers if you have time to do so.

## 1. Install Docker Desktop

You can download the software titled Docker Desktop from [Docker Inc.](https://www.docker.com/products/docker-desktop).

## 2. Test `inazo` for the first time

% docker run -ti --rm -p 3000:3000 -p 8888:8888 unvt/inazo
$ ls
$ tippecanoe -v
$ exit
%

<a href="https://asciinema.org/a/nKYlTsyehzgXMXvZwRttNl1SF" target="_blank"><img src="https://asciinema.org/a/nKYlTsyehzgXMXvZwRttNl1SF.svg" /></a>

Please ask tutors for support if the system does not work correctly.

### What is happening here?
- We log in to a virtual machine running a Docker container image named `smellman/inazo` develped by us.
- We checked what files are there by `ls`.
- We checked the version of `tippecanoe` which is a tool to produce vector tiles.

## 3. Check tools included in `inazo`

% docker run -ti --rm -p 3000:3000 -p 8888:8888 unvt/inazo
$ tippecanoe -v
$ tile-join
$ ogr2ogr --version
$ osmium --version
$ node -v
$ budo --version
$ pm2 --version
$ browserify --version
$ vi --version
$ parse-hocon -v
$ gl-style-validate
$ exit
%

<a href="https://asciinema.org/a/2cLRoWpnm4spSrExBf5Hc31Sy" target="_blank"><img src="https://asciinema.org/a/2cLRoWpnm4spSrExBf5Hc31Sy.svg" /></a>

### What are these commands?
In the UNVT we have both _geospatial_ and _web_ commands that supports web map using vector tile technology.

#### tippecanoe (_geospatial_)
[Tippecanoe](https://github.com/mapbox/tippecanoe) is a command line tool to build vector tile packages from large collections of GeoJSONS features.

The official name of GeoJSONS is [RFC 8142](https://tools.ietf.org/html/rfc8142) or GeoJSON Text Sequences.

The default format of the vector tile package is [mbtiles-spec](https://github.com/mapbox/mbtiles-spec).

#### tile-join (_geospatial_)
`tile-join`, which is a part of [Tippecanoe](https://github.com/mapbox/tippecanoe, is a command line tool that can be used to convert a vector tile package into vector tiles.

#### ogr2ogr (_geospatial_)
[ogr2ogr](https://gdal.org/programs/ogr2ogr.html) is a standard open source tool that converts vector data (to be more specific, simple feature data) between file formats.

#### osmium-tool (_geospatial_)
[osmium-tool](https://osmcode.org/osmium-tool/) is a multipurpose command line tool based on the Osmium Library.

The [Osmium Library](https://osmcode.org/libosmium/) is a fast and flexible C++ library for working with OpenStreetMap data.

#### node (_web_)
[Node.js](https://nodejs.org/en/) is a JavaScript runtime built on Chrome's V8 JavaScript engine.

#### budo (_web_)
[budo](https://github.com/mattdesl/budo) is a browserify development server focused on incremental reloading, LiveReload integration (including CSS injection) and other high-level features for rapid prototyping.

#### PM2 (_web_)
[PM2](http://pm2.keymetrics.io/) is an advanced, production process manager for Node.js. We use PM2 for more production-ready vector tile hosting.

#### browserify (_web_)
[browserify](http://browserify.org/) is a tool to convert a JavaScript program for web browsers. We use this internally in our Toolkit.

#### Vim (basic UNIX command)
[Vim](https://www.vim.org/) is a highly configurable text editor for efficiently creating and changing any kind of text.

We use such a text editor to edit the style description for the vector tiles.

Do not worry! We also have [nano](https://nano-editor.org/), a small and friendly text editor, included in `rasv`.

#### parse-hocon (_web_)
[hocon-parser](https://github.com/josephtzeng/hocon-parser) has a command line tool named `parse-hocon` to convert [Human-Optimized Config Object Notation (HOCON)](https://github.com/lightbend/config/blob/master/HOCON.md) files to a JSON. We think that the `include` syntax is helpful for us to nicely organize a complex style description.

We use this to organize the [Mapbox Style](https://docs.mapbox.com/mapbox-gl-js/style-spec/) description for our vector tiles.

### gl-style-validate (_geospatial_)
`gl-style-validate` is a command line tool as a part of [Mapbox GL style specification & utilities](https://github.com/mapbox/mapbox-gl-js/tree/master/src/style-spec) which validat the given style JSON and print errors.

We think this tool helps efficient style development because we can see the error before we actually checks the vector tiles on a web browser.

## 4. Produce vector tiles with `inazo`

% docker run -ti --rm -p 3000:3000 -p 8888:8888 unvt/inazo 
$ cd inazo-produce
$ rake
$ exit
%

<a href="https://asciinema.org/a/dgY3HqRscssjr72uzUeelyDqy" target="_blank"><img src="https://asciinema.org/a/dgY3HqRscssjr72uzUeelyDqy.svg" /></a>

### What does `rake` do?
The following lines in the [inazo-produce/Rakefile](https://github.com/un-vector-tile-toolkit/inazo-produce/blob/master/Rakefile) shows what is done with this command.

task :default do
  sh "node index.js"
  sh "tile-join --force --output-to-directory=zxy\
    tiles.mbtiles --no-tile-compression --no-tile-size-limit"
end

#### Command 1
The first command `node index.js` opens GeoJSONS data in `~/geojsons-euroglobalmap`, apply some feature modifications described in `~/inazo-produce/modify.js`, and feed the resulting GeoJSON Text to `tippecanoe`, resulting the production of vector tile package in `~/inazo-produce/tiles.mbtiles`.

You can check the [source code of index.js on GitHub](https://github.com/un-vector-tile-toolkit/inazo-produce/blob/master/index.js).

#### Command 2
The second command `tile-join --force --output-to-directory=zxy tiles.mbtiles --no-tile-compression --no-tile-size-limit` extracts the raw vector tiles from the vector tile package `tiles.mbtiles`. Raw vector tiles are useful to host them on a plain web server or [GitHub Pages](https://pages.github.com/) like in [inazo-static](https://un-vector-tile-toolkit.github.io/inazo-static) ([repository](https://github.com/un-vector-tile-toolkit/inazo-static)).

## 5. Host vector tiles with `inazo`

% docker run -ti --rm -p 3000:3000 -p 8888:8888 unvt/inazo
$ cd inazo-host
$ rake build
$ rake start
$ # open http://localhost:3000 in your web browser
$ rake stop
$ exit
%

<a href="https://asciinema.org/a/QYDhOsJC6IAw9qAPInAf6bH9J" target="_blank"><img src="https://asciinema.org/a/QYDhOsJC6IAw9qAPInAf6bH9J.svg" /></a>

### What does `rake build` do?

task :build do 
  sh "parse-hocon hocon/style.conf --output htdocs/style.json"
  unless ENV['URL'].nil?
    target = 'http://localhost:3000'
    buf = File.open('htdocs/style.json', 'r') { |f| f.read() }
    buf.gsub!(target) { ENV['URL'] }
    File.open('htdocs/style.json', 'w') { |f| f.write(buf) }
  end
  sh "gl-style-validate htdocs/style.json"
  sh "browserify -o htdocs/bundle.js -t " +
    "[ babelify --presets [ @babel/preset-env ] ] app.js"
end

#### Command 1
`parse-hocon hocon/style.conf --output htdocs/style.json` generates Mapbox Style description of our vector tiles at `htdocs/style.json` from the human-optimized style description in `hocon/` directory, whose root is `hocon/style.conf`.

#### Command 2
`gl-style-validate htdocs/style.json` vadilates resulting `htdocs/style.json` generated by the Command 1. If there are any errors, the command stops and you will be fixing the style description in the `hocon/` directory.

#### Command 3
`browserify -o htdocs/bundle.js -t [ babelify --presets [ @babel/preset-env ] ] app.js` creates `htdocs/bundle.js` from `app.js`.

The file `app.js` contains the JavaScript program for the web site:

const map = new mapboxgl.Map({
  container: 'map',
  style: 'style.json',
  attributionControl: true,
  hash: true
})

You may be interested in [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/api/).

### What does `rake start` do?

task :start do
  sh "pm2 start process.yml"
end

This starts the web server. The content of `process.yml` is as below.

apps:
  - script: index.js
    name: inazo
    instances: 1
    exec_mode: cluster

This means:

- the server script is `index.js`
- the name of the server cluster is `inazo`
- the number of instance in the cluster is just 1
- PM2 execution mode is `cluster`

### What does `rake stop` do?

task :stop do
  sh "pm2 stop inazo; pm2 delete inazo"
end

This stops the web server.

# Appendix: Technical specifications
## Related repositories
### DockerHub
- [unvt/inazo](https://hub.docker.com/r/unvt/inazo/tags)

### GitHub
- [un-vector-tile-toolkit/inazo](https://github.com/un-vector-tile-toolkit/inazo)
- [un-vector-tile-toolkit/inazo-produce](https://github.com/un-vector-tile-toolkit/inazo-produce)
- [un-vector-tile-toolkit/inazo-host](https://github.com/un-vector-tile-toolkit/inazo-host)
- [un-vector-tile-toolkit/rasv](https://github.com/un-vector-tile-toolkit/rasv)

## Author
Main contributors for `inazo` are:

### @smellman Taro Matsuzawa
- JICA Lecturer, Web Map Technology
- Senior Developer, Georepublic Japan

### @hfu Hidenori Fujimura
- Lead, United Nations Vector Tile Toolkit
- Lead, Scenario-based Exercise, WG-Disasters, UN-GGIM
- Vice-chair, Integrating Geospatial Information and Statistics, UN-GGIM-AP
- Executive Officer for Geospatial Information Policy, Geospatial Information Authority of Japan

## License
Unlicense

## Who is inazo?
[Nitobe, Inazo](https://en.wikipedia.org/wiki/Nitobe_Inaz%C5%8D) was a Japanese agricultural economist, author, educator, diplomat, and politician. He was one of the Under-Secretaries General of the League of Nations. His portrait was featured on the Series D of ¥5000 banknote, printed from 1984 to 2004.


Source: [National Printing Bureau](https://www.npb.go.jp/ja/kids/tishiki/shouzou.html)

The value of one inazo note was about the value of Raspberry Pi.

## History
- 2019-09-26: created to prepare for a JICA knowledge co-creation program.