[OSM-dev] Beginner questions about mod_tile

[Jon Burgess]

On Fri, 2008-08-08 at 12:26 +0200, Jaume Figueras wrote:
> Hi,
> 
> I'm trying to set up a map server using mod_tile, when editing the 
> render_config.h file to fit my directory hierarchy there are some 
> parameters I don't success to understand:
> 
> 1.- IMG_PATH: 'grep'-ing all mod_tile files lead that IMG_PATH is only 
> defined in render_config.h and is never used. But in the definitions it 
> says that must contain blank.png and other files. Advice please.

Right, it isn't used any more and can be removed.

> 2.- In the readme.txt file it says that the file osm-jb-merc.xml define 
> the Mapnik rules. This is 'my' osm.xml file? and defined in OSM_XML in 
> render_config.h. The different names cause me a bit of confusion.

Correct, at one point it was hard coded as osm-jb-merc.xml but later got
converted into a #define. 

> 3.-I don't fully understant how PLANET_TIMESTAMP and PLANET_INTERVAL 
> work. PLANET_TIMESTAMP is used in the render daemon, so if the file is 
> missing the daemon will rerender when a tile is 3 days old of its expiry 
> (line 68 render_list.c -> planet_timestamp = 3 * 24 * 60 * 60;) if the 
> file exists only rerender when the date of the file changes. I 
> understood it well?  For PLANET_TIMESTAMP used in mod_tiles.c is the 
> same that in render_list.c and PLANET_INTERVAL is the interval added to 
> calculate the expiry date of a tile. Correct?

PLANET_TIMESTAMP should be present and should be touch'd when you update
the data in the database. The render daemon compares the timestamp of
the tile to this to see if it needs rendering. Don't worry too much
about the behaviour if the file is missing, that is just a fallback
which should not normally take effect.

The PLANET_INTERVAL is a guesstimate of when the next import is likely
to occur. This is used to set the expiry time in the HTTP headers when
the tiles are served. If you want to update the underlying data base
more than once a week then you should reduce this. It doesn't matter
much if this is inaccurate, it will just cause clients to either
re-request tiles which have not changed or cause them to cache them for
some time after they have been updated.

> 3b.- I suppose the I don't understand it because rerender should happen 
> only if the PLANET_TIMESTAMP file is touched or the render_all script is 
> executed.

The purpose is to give the browser a hint on how long to cache the file.
It does not effect when it actually gets rendered.

> 3c.- While writing, I think I do not understand nothing about when 
> rerender happens.... :(

I need to update the docs. It was deployed in a little bit of a hurry
because the previous rendering system could not keep up with the demand.
Unfortunately I've not been back to update the documentation to match
the latest changes in the code.

The re-render happens on-demand when someone tries to access a tile
which is older than the PLANET_TIMESTAMP file. The tile serving code
only checks for updates to this timestamp every 5 minutes so there may
be a small delay before this starts happening. 

There are some tools which I run to force the re-rendering of all the
existing tiles. render_old is the main one. This walks the directories
that contain the rendered tiles and any which are older than the
timestamp get requested to be rendered. The render_all is a small script
which spawns off multiple render_old instances, one for each zoom level.
This ensures that all the CPU cores get something to do. There is an
automatic throttle to slow things down if the load average gets too
high.

> 
> 4.- The update script has to be called manually (or croned). The 
> mod_tile nor the render daemon will try to update the planet file.

I normally set the script going on Tuesday night after I check that the
machine isn't likely to run out of disk space and I apply any recent
style updates. The script could easily be run by cron once a week.

	Jon