This comprehensive guide explains how to serve OpenTopoMap tiles through Apache and the renderd daemon, add a browsable Leaflet map, and enable HTTPS. It assumes that the server is already set up for OpenTopoMap tile rendering.
The commands were tested on Ubuntu 24.04 LTS with Apache 2.4, Mapnik 3.1 and the official mod_tile 0.8.1 release. The renderer account is gis; substitute another account consistently if required.
Contents
- 1 Install the build dependencies
- 2 Compile and install mod_tile
- 3 Create the renderd configuration
- 4 Create the renderd systemd service
- 5 Configure Apache to load mod_tile
- 6 Test renderd directly
- 7 Test tile delivery through Apache
- 8 Add a Leaflet front end
- 9 Enable HTTPS with Certbot
- 10 Verify automatic startup after a reboot
- 11 Done
Install the build dependencies
sudo apt update
sudo apt install \
git \
cmake \
build-essential \
apache2 \
apache2-dev \
libmapnik-dev \
libcairo2-dev \
libiniparser-dev \
libcurl4-openssl-dev \
libglib2.0-dev \
curl \
unzip
The standalone curl package is required by the mod_tile test suite. Installing the libcurl development package alone is not sufficient.
Compile and install mod_tile
Use the official openstreetmap/mod_tile repository. The old SomeoneElseOSM/mod_tile switch2osm branch, Autotools build and manual source patches are no longer needed.
mkdir -p ~/src
git clone \
--branch v0.8.1 \
--depth 1 \
https://github.com/openstreetmap/mod_tile.git \
~/src/mod_tile
Git reports detached-HEAD state because v0.8.1 is a release tag. That is expected.
Use a logged screen session for the build:
screen -L \
-Logfile /home/gis/mod-tile-build.log \
-S mod-tile-build
Run inside the screen session:
set -euo pipefail
cmake \
-S /home/gis/src/mod_tile \
-B /home/gis/src/mod_tile-build \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCMAKE_INSTALL_LOCALSTATEDIR=/var \
-DCMAKE_INSTALL_RUNSTATEDIR=/run \
-DCMAKE_INSTALL_SYSCONFDIR=/etc \
-DUSE_MEMCACHED=OFF \
-DUSE_RADOS=OFF \
-DENABLE_TESTS=ON
cmake \
--build /home/gis/src/mod_tile-build \
--parallel "$(nproc)"
ctest \
--test-dir /home/gis/src/mod_tile-build \
--output-on-failure
sudo cmake \
--install /home/gis/src/mod_tile-build \
--strip
Detach with Ctrl-A, then D. On the tested server all 145 tests passed. The installation places the programs in /usr/bin, the Apache module in /usr/lib/apache2/modules, and the configuration in /etc.
renderd --version
command -v renderd
command -v render_list
ls -l \
/usr/bin/renderd \
/usr/bin/render_list \
/usr/lib/apache2/modules/mod_tile.so \
/etc/renderd.conf \
/etc/apache2/mods-available/tile.load
Create the renderd configuration
Back up the generated default and replace it:
sudo cp -a /etc/renderd.conf /etc/renderd.conf.install-default
sudo tee /etc/renderd.conf >/dev/null <<'EOF'
[renderd]
num_threads=4
pid_file=/run/renderd/renderd.pid
socketname=/run/renderd/renderd.sock
stats_file=/run/renderd/renderd.stats
tile_dir=/var/cache/renderd/tiles
[mapnik]
font_dir=/usr/share/fonts
font_dir_recurse=1
plugins_dir=/usr/lib/mapnik/3.1/input
[opentopomap]
URI=/tile/
TILEDIR=/var/cache/renderd/tiles
XML=/home/gis/OpenTopoMap/mapnik/opentopomap.xml
HOST=localhost
TILESIZE=256
MINZOOM=0
MAXZOOM=17
TYPE=png image/png png256
EOF
Important: TYPE contains three fields: filename extension, MIME type and Mapnik output format. With mod_tile 0.8.1, the incomplete line TYPE=png image/png caused Apache child processes to segfault. Use the complete line above, or omit TYPE and use the default.
Prepare the persistent cache. The runtime directory is also created here for the initial start; systemd recreates it after every reboot.
sudo install \
-d \
-o gis \
-g www-data \
-m 2775 \
/var/cache/renderd \
/var/cache/renderd/tiles
sudo install \
-d \
-o gis \
-g www-data \
-m 0775 \
/run/renderd
Create the renderd systemd service
The CMake installation does not install a systemd unit. Create one explicitly:
sudo tee /etc/systemd/system/renderd.service >/dev/null <<'EOF'
[Unit]
Description=OpenTopoMap tile rendering daemon
After=network.target postgresql.service
Wants=postgresql.service
[Service]
Type=simple
User=gis
Group=www-data
WorkingDirectory=/home/gis/OpenTopoMap/mapnik
Environment=HOME=/home/gis
ExecStart=/usr/bin/renderd --foreground --config=/etc/renderd.conf
Restart=on-failure
RestartSec=5
RuntimeDirectory=renderd
RuntimeDirectoryMode=0775
UMask=0002
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
EOF
sudo systemd-analyze verify /etc/systemd/system/renderd.service
sudo systemctl daemon-reload
sudo systemctl enable --now renderd
Verify the service, socket and cache permissions:
sudo systemctl status renderd --no-pager -l
sudo journalctl \
-u renderd \
--since '5 minutes ago' \
--no-pager
ls -la /run/renderd
ls -ld /var/cache/renderd/tiles
A healthy installation reports renderd 0.8.1, Mapnik 3.1, four rendering threads and the opentopomap map. The socket /run/renderd/renderd.sock must be accessible to Apache.
Configure Apache to load mod_tile
The installation already provides /etc/apache2/mods-available/tile.load. Do not create a second LoadModule directive.
sudo tee /etc/apache2/conf-available/opentopomap-tiles.conf >/dev/null <<'EOF'
<IfModule tile_module>
ModTileTileDir /var/cache/renderd/tiles
LoadTileConfigFile /etc/renderd.conf
ModTileRenderdSocketName /run/renderd/renderd.sock
ModTileEnableStats On
ModTileBulkMode Off
ModTileRequestTimeout 10
ModTileMissingRequestTimeout 120
ModTileMaxLoadOld 16
ModTileMaxLoadMissing 50
ModTileCacheDurationMax 604800
ModTileCacheDurationDirty 900
ModTileCacheDurationMinimum 10800
ModTileCacheDurationMediumZoom 13 86400
ModTileCacheDurationLowZoom 9 518400
ModTileCacheLastModifiedFactor 0.20
ModTileEnableTileThrottling On
ModTileEnableTileThrottlingXForward 0
ModTileThrottlingTiles 10000 1
ModTileThrottlingRenders 128 0.2
ModTileEnableStatusURL On
ModTileEnableDirtyURL Off
</IfModule>
EOF
sudo a2enmod tile
sudo a2enconf opentopomap-tiles
sudo apache2ctl configtest
sudo systemctl restart apache2
A single full restart is sufficient. The old workaround that reloaded Apache twice is no longer required.
sudo systemctl status apache2 renderd --no-pager -l
apache2ctl -M 2>/dev/null | grep tile
Recover from an Apache crash loop
If Apache child processes start segfaulting after enabling mod_tile, stop testing requests and restore Apache first:
sudo a2disconf opentopomap-tiles
sudo a2dismod tile
sudo apache2ctl configtest
sudo systemctl restart apache2
Then verify the three-field TYPE setting in /etc/renderd.conf before re-enabling the module.
Test renderd directly
Render the known Zugspitze tile through renderd. This produces one 8×8 metatile containing 64 individual tiles.
screen -L \
-Logfile /home/gis/render-test-zugspitze.log \
-S render-test-zugspitze
Run inside screen:
set -euo pipefail
SECONDS=0
printf '8691 5734 14\n' |
render_list \
--config=/etc/renderd.conf \
--map=opentopomap \
--force \
--num-threads=1
printf 'Elapsed: %d seconds\n' "$SECONDS"
Do not place Bash’s time keyword directly after the pipe. In that position Bash tries to run an external time command. On the tested server the metatile rendered in 6.38 seconds.
sudo journalctl -u renderd -f
Mapnik messages about unsupported SVG attributes such as overflow and enable-background are nonfatal.
Test tile delivery through Apache
curl \
--max-time 30 \
--fail \
--show-error \
--silent \
--dump-header /tmp/opentopomap-tile.headers \
--output /tmp/opentopomap-zugspitze-z14.png \
http://127.0.0.1/tile/14/8691/5734.png
cat /tmp/opentopomap-tile.headers
file /tmp/opentopomap-zugspitze-z14.png
ls -l /tmp/opentopomap-zugspitze-z14.png
The tested request returned a valid 51,732-byte PNG. Tiles use /tile/{z}/{x}/{y}.png. Inspect cached metatiles and the optional status endpoint with:
find /var/cache/renderd/tiles/opentopomap \
-type f \
-printf '%s bytes %p\n' |
sort -nr |
head -20
curl --max-time 10 --fail --show-error \
http://127.0.0.1/tile/14/8691/5734.png/status
Add a Leaflet front end
Install Leaflet 1.9.4 locally so the map does not depend on a third-party CDN:
cd /tmp
curl -fLO https://leafletjs-cdn.s3.amazonaws.com/content/leaflet/v1.9.4/leaflet.zip
rm -rf /tmp/leaflet-1.9.4
mkdir /tmp/leaflet-1.9.4
unzip -q leaflet.zip -d /tmp/leaflet-1.9.4
sudo install -d -m 0755 /var/www/html/leaflet/images
sudo install -m 0644 /tmp/leaflet-1.9.4/leaflet.css /var/www/html/leaflet/
sudo install -m 0644 /tmp/leaflet-1.9.4/leaflet.js /var/www/html/leaflet/
sudo install -m 0644 /tmp/leaflet-1.9.4/images/* /var/www/html/leaflet/images/
Create /var/www/html/index.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta http-equiv="Content-Security-Policy"
content="default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'">
<title>OpenTopoMap Europe</title>
<link rel="stylesheet" href="/leaflet/leaflet.css">
<link rel="stylesheet" href="/map.css">
</head>
<body>
<div id="map" aria-label="OpenTopoMap Europe"></div>
<script src="/leaflet/leaflet.js"></script>
<script src="/map.js"></script>
</body>
</html>
Create /var/www/html/map.css:
html, body, #map {
width: 100%;
height: 100%;
margin: 0;
}
.map-title {
padding: 6px 10px;
background: rgba(255, 255, 255, 0.9);
border-radius: 4px;
font: 600 15px/1.2 sans-serif;
box-shadow: 0 1px 5px rgba(0, 0, 0, 0.35);
}
Create /var/www/html/map.js:
const map = L.map('map', {
minZoom: 3,
maxZoom: 17
}).setView([51.7893, 6.1386], 12);
const europeBounds = L.latLngBounds(
[28.0, -19.0],
[72.0, 60.0]
);
L.tileLayer('/tile/{z}/{x}/{y}.png', {
minZoom: 0,
maxZoom: 17,
bounds: europeBounds,
noWrap: true,
attribution:
'© OpenStreetMap contributors | OpenTopoMap rendering | SRTM elevation data'
}).addTo(map);
L.control.scale({ imperial: false }).addTo(map);
const title = L.control({ position: 'topright' });
title.onAdd = function () {
const element = L.DomUtil.create('div', 'map-title');
element.textContent = 'OpenTopoMap Europe';
return element;
};
title.addTo(map);
Validate the static files:
curl -I http://127.0.0.1/
curl -I http://127.0.0.1/leaflet/leaflet.js
curl -I http://127.0.0.1/map.js
Cold-cache behaviour
A new browser view can request several uncached metatiles simultaneously. The first requests may reach ModTileMissingRequestTimeout and temporarily return 404 while renderd continues working. Refresh after the metatiles finish; subsequent requests are served quickly from the persistent cache. Monitor activity with:
sudo journalctl -u renderd -f
sudo tail -f /var/log/apache2/access.log
Enable HTTPS with Certbot
Make sure the public DNS record points to the server and add the hostname to the port-80 virtual host:
<VirtualHost *:80>
ServerName opentopomap.nitri.org
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
sudo apache2ctl configtest
sudo systemctl reload apache2
sudo apt update
sudo apt install certbot python3-certbot-apache
sudo certbot --apache \
--redirect \
-d opentopomap.nitri.org
Certbot creates the TLS virtual host, deploys the certificate and redirects HTTP to HTTPS. The root-relative Leaflet tile URL /tile/... automatically uses HTTPS and does not create mixed-content warnings.
Optionally define the hostname globally as well. This prevents mod_tile’s harmless TileJSON notice about falling back to http://localhost:
echo 'ServerName opentopomap.nitri.org' |
sudo tee /etc/apache2/conf-available/servername.conf
sudo a2enconf servername
sudo apache2ctl configtest
sudo systemctl reload apache2
Validate HTTPS and automatic renewal:
sudo ss -ltnp | grep -E ':(80|443)\b'
curl -I http://opentopomap.nitri.org/
curl -I https://opentopomap.nitri.org/
curl -I https://opentopomap.nitri.org/tile/14/8691/5734.png
sudo certbot certificates
sudo certbot renew --dry-run
systemctl list-timers --all | grep -i certbot
HTTP should redirect to HTTPS, HTTPS should return 200 OK, and the renewal simulation must succeed.
Verify automatic startup after a reboot
PostgreSQL, Apache, renderd and the Certbot renewal timer must all be enabled:
systemctl is-enabled \
postgresql.service \
apache2.service \
renderd.service \
certbot.timer
All four should report enabled. Reboot and verify the complete stack:
sudo reboot
After reconnecting:
sudo systemctl status \
postgresql \
apache2 \
renderd \
certbot.timer \
--no-pager -l
pg_lsclusters
sudo ss -ltnp | grep -E ':(80|443)\b'
ls -l /run/renderd/renderd.sock
curl -I https://opentopomap.nitri.org/
curl -I https://opentopomap.nitri.org/tile/14/8691/5734.png
The PostgreSQL umbrella service can show active (exited); this is normal when pg_lsclusters reports cluster 16 main as online. Detached screen sessions do not survive a reboot, but the completed installation and preprocessing work does not depend on them.
Done
Apache now serves a secure, browsable OpenTopoMap of Europe. Tiles are generated on demand by renderd, cached persistently below /var/cache/renderd/tiles/opentopomap, and exposed at https://opentopomap.nitri.org/tile/{z}/{x}/{y}.png. PostgreSQL, Apache and renderd start automatically, while Certbot renews the certificate in the background.