From f9611b4cd8d6a039f6f38f64613aa7efd29e2a9b Mon Sep 17 00:00:00 2001
From: Alexander Overvoorde <overv161@gmail.com>
Date: Wed, 19 Jun 2019 21:40:52 +0200
Subject: [PATCH] Improve clarity of the automatic updating process in the
 README

---
 README.md | 36 +++++++++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 5821777..a49fc6c 100644
--- a/README.md
+++ b/README.md
@@ -9,17 +9,20 @@ First create a Docker volume to hold the PostgreSQL database that will contain t
     docker volume create openstreetmap-data
 
 Next, download an .osm.pbf extract from geofabrik.de for the region that you're interested in. You can then start importing it into PostgreSQL by running a container and mounting the file as `/data.osm.pbf`. For example:
+
 ```
     docker run -v /absolute/path/to/luxembourg.osm.pbf:/data.osm.pbf \
                -v openstreetmap-data:/var/lib/postgresql/10/main \
                overv/openstreetmap-tile-server \
                import
 ```
+
 If the container exits without errors, then your data has been successfully imported and you are now ready to run the tile server.
 
-### optional step to allow consecutive updates of osm extracts
+### Automatic updates (optional)
+
+If your import is an extract of the planet and has polygonal bounds associated with it, like those from geofabrik.de, then it is possible to set your server up for automatic updates. Make sure to reference both the OSM file and the polygon file during the import process to facilitate this:
 
-if your import is a extract of planet and is based on polygon then you should download this polynom data and use follwing command for the import procedure:
 ```
     docker run -v /absolute/path/to/luxembourg.osm.pbf:/data.osm.pbf \
                -v /absolute/path/to/luxembourg.poly:/data.poly \
@@ -27,33 +30,39 @@ if your import is a extract of planet and is based on polygon then you should do
                overv/openstreetmap-tile-server \
                import
 ```
+
+Refer to the section *Automatic updating and tile expiry* to actually enable the updates.
+
 ## Running the server
 
 Run the server like this:
+
 ```
     docker run -p 80:80 \
                -v openstreetmap-data:/var/lib/postgresql/10/main \
                -d overv/openstreetmap-tile-server \
                run
 ```
-Your tiles will now be available at `http://localhost:80/tile/{z}/{x}/{y}.png`. The demo map in `leaflet-demo.html` will then be available on `http://localhost:80`. Note that it will initially quite a bit of time to render the larger tiles for the first time.
 
-## Preserving rendered tiles
+Your tiles will now be available at `http://localhost:80/tile/{z}/{x}/{y}.png`. The demo map in `leaflet-demo.html` will then be available on `http://localhost:80`. Note that it will initially take quite a bit of time to render the larger tiles for the first time.
+
+### Preserving rendered tiles
 
 Tiles that have already been rendered will be stored in `/var/lib/mod_tile`. To make sure that this data survives container restarts, you should create another volume for it:
+
 ```
     docker volume create openstreetmap-rendered-tiles
-    docker run -p 80:80
-               -v openstreetmap-data:/var/lib/postgresql/10/main
-               -v openstreetmap-rendered-tiles:/var/lib/mod_tile
+    docker run -p 80:80 \
+               -v openstreetmap-data:/var/lib/postgresql/10/main \
+               -v openstreetmap-rendered-tiles:/var/lib/mod_tile \
                -d overv/openstreetmap-tile-server \
                run
 ```
-## Performance tuning and tweaking
 
-### update and tile expire procedure
+### Enabling automatic updating (optional)
+
+Given that you've specified both the OSM data and polygon as specified in the *Automatic updates* section during server setup, you can enable the updating process by setting the variable `UPDATES` to `enabled`:
 
-The environment variable "UPDATES" (default value =disabled) allows you to run the container with consecutive updates.
 ```
 docker run -p 80:80 \
            -v openstreetmap-data:/var/lib/postgresql/10/main \
@@ -62,7 +71,12 @@ docker run -p 80:80 \
            -e UPDATES=enabled \
            run
 ```
-Details for update procedure and invoked scripts can you find here [link](https://ircama.github.io/osm-carto-tutorials/updating-data/)
+
+This will enable a background process that automatically downloads changes from the OpenStreetMap server, filters them for the relevant region polygon you specified, updates the database and finally marks the affected tiles for rerendering.
+
+## Performance tuning and tweaking
+
+Details for update procedure and invoked scripts can be found here [link](https://ircama.github.io/osm-carto-tutorials/updating-data/).
 
 ### THREADS