User:Davide sd/OSM Analytic Tracker

From OpenStreetMap Wiki
Jump to: navigation, search

OSM Analytic Tracker is a powerful tool to analyze all the OSM edits done into a specific region. While other services provides RSS feeds of rectangular bounding boxes, OSM Analytic Tracker is able to consider much wider and more shape-complex regions. In this page you'll learn how to setup a basic installation on the Raspberry Pi. I've tested this tool with Raspberry Pi 2 Model B and Raspbian Jessie.

Docker Installation

The fastest way to get OSM Analytical Tracker up and running is by using Docker. The following steps are based on this tutorial.

Open the terminal, type the following command:

curl -sSL https://get.docker.com | sh

Docker in now installed into /usr/bin/. At this point, the Docker client can only be used by root or members of the docker group. Add pi or your equivalent user to the docker group:

sudo usermod -aG docker pi

Obviously, we want OSM Analytical Tracker to automatically start at boot. To do that, Docker needs to start first:

sudo systemctl enable docker

You can now reboot the Pi, or start the Docker daemon with:

sudo systemctl start docker


Geometry files

OSM Analytic Tracker uses poly files that describes the extend of the region to observe. If you need to observe a large region or maybe an entire country, chances are you'll find the geometry files at this website (look for poly files). If you find what you are looking for, just copy the link of the poly file. In the unfortunate case you don't find it, you can always create it. This wiki page explain what poly files are, and several ways to create them. I've followed the QGIS tutorial to get the geometry of my region of interest, with some slight adaptations:

  1. I had to install the QuickOSM plugin for QGIS: this plugin let the user download OSM data using Overpass queries.
  2. I had to play with the buffer distance and simplify geometry parameters. Because my region of interest was a lot smaller of the one in the tutorial, I had to use a lot smaller parameter values.
  3. Because my case didn't involve multipolygon geometries, I skipped step 4.

OSM Analytic Tracker setup

Open the terminal, and move your position to your home folder (in my case, I'm logged with user pi):

cd /home/pi

Clone the OSM Analytical Tracker repository:

git clone https://github.com/MichaelVL/osm-analytic-tracker.git

Enter the repository directory:

cd osm-analytic-tracker

Copy the file docker/Docker-all-in-one into the main repository folder and rename it to Docker:

cp docker/Docker-all-in-one .

mv Docker-all-in-one Dockerfile

Open Dockerfile file with your editor of choice. Add the hash character # at the beginning of the first line, and remove the hash character from the beginning of the second line. The first two lines of codes should look like:

# FROM debian:jessie

FROM resin/rpi-raspbian

Look for the following line of code:

ADD http://download.geofabrik.de/europe/denmark.poly region.poly

At this point, there are two cases:

CASE 1: If you've previously found the link to the poly file, you can change the line to:

ADD YOUR-LINK-HERE region.poly

CASE 2: If you had to create your file, then you need to create a new folder:

mkdir regions

And move that file into this folder:

mv PATH-TO-YOUR-POLY-FILE regions

Finally, change that line of code to:

ADD regions/YOUR-FILE-NAME.poly region.poly

At this point the Docker file is ready to be saved.


One last thing to edit: open the html/index.html file and look for the following line of code:

var map = new L.Map('map', {'dragging' : true, 'zoomControl': false, 'doubleClickZoom': false,}).setView(new L.LatLng(56.0, 11.4),6);

This specific code setView(new L.LatLng(56.0, 11.4),6) set the center point of the view (in this case, Lat=56.0, Long=11.4) with a zoom level of 6. You need to change these numbers, and it might be a bit tricky: you can find the center point of the region you are interested by centering the map view to your interested region and looking at the numbers in the address bar of your browser. If you are looking at a "medium" size country, you can leave the zoom level at 6. If you are looking at smaller regions, increase it to 7 or 8.

Final Steps

Now the configuration is done, all we need to do is to build the Docker image and run it.

To build the Docker image, open the terminal and move yourselft into the osm-analytic-tracker folder. Then run:

sudo docker build -t osm-analytic-tracker .

It will take a few minutes to build the image, so grab yourself a cup of coffee and relax. When the build is done, all you have to do is run the following command:

docker run -d --restart=always --name=osmat-container -p 8080:80 osm-analytic-tracker

This command create a container based on the image previously built. The option --restart=always indicates this service will be automatically restarted at every boot. The option --name=osmat-container assign a name to the container. The option -d run the container detached from the terminal window. The option -p 8080:80 map the port 8080 of the host (your Raspberry Pi) to the port 80 of the container.

To test your installation, open the Raspberry Pi browser and use the following address: 127.0.0.1:8080. If everything went well, the server is up and running and you should see the main page. To connect to this server from your local network, open your local browser and type: YOUR-RASPBERRY-IP-ADDRESS:8080.

Read the logs

OSM Analytic Tracker is controlled by Supervisor, which is configured to print log files. In the unfortunate case you should have any problems while running this service, you can access the container file system with the following command:

docker exec -it osmat-container /bin/bash

To see which log file has been created:

ls | grep "\.log$"

In this folder there should be the following logs: supervisord.log and osmtracker.log. To find the other logs, enter the command cd .. to move yourself on the parent folder, and again run ls | grep "\.log$". In this folder there should be the following logs: osmtracker.log, backends.log, worker0.log, worker1.log.

At this point you can exit from the container file system with the command exit. If you want to read the log files, you have to copy them from the container file system to the raspberry file system (choose your target directory):

docker cp osmat-container:osmtracker/osm-analytic-tracker/COMPLETE-NAME-OF-THE-LOG-FILE /home/pi/TARGET-DIRECTORY

Please, bear in mind the location of the log files in the container file system and adjust the above command accordingly.

Stop the container

This command will completely stop, remove and prevent the OSM Analytic Tracker container to start again:

docker rm -f osmat-container


Further improvements

At the moment, for every change in the configuration files we need to re-build the image from scratch. This is quite time consuming. I'm working to better dockerize this service, in order to re-build only the interested part.