HOWTO: Install OpenTopoMap on Ubuntu 24.04 LTS (Part 2)

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.

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:
    '&copy; 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.