Skip to content

Colota - Android GPS Location tracker

docs: add self-hosting guide for tileserver-gl with local styles and fonts

Max Dietrich46973819ef05
diff --git a/apps/docs/docs/guides/tile-server.md b/apps/docs/docs/guides/tile-server.md
index eb848025..167b9e98 100644
--- a/apps/docs/docs/guides/tile-server.md
+++ b/apps/docs/docs/guides/tile-server.md
@@ -43,17 +43,6 @@ Offline map packs are downloaded from whichever tile server is configured at the
Any [MapLibre GL style](https://maplibre.org/maplibre-style-spec/) endpoint works. If you only have one style, use the same URL in both fields.
-:::note Attribution
-
-When using the default server, the map shows **© OpenMapTiles · © OpenStreetMap contributors · © maps.mxd.codes** attribution. When a custom server is configured, attribution is read automatically from the style JSON served by your tile server.
-
-:::
-
-**Self-hosting options**
-
-- [tileserver-gl](https://tileserver.readthedocs.io) - serves MapLibre styles from `.mbtiles` files.
-- [PMTiles](https://docs.protomaps.com/pmtiles/) - a single static file format that can be served from any object storage (S3, Cloudflare R2, etc.) with no server process required.
-
**Free hosted alternatives**
[OpenFreeMap](https://openfreemap.org) is a good free alternative. Available styles:
@@ -65,3 +54,249 @@ When using the default server, the map shows **© OpenMapTiles · © OpenStreetM
| fiord (dark) | `https://tiles.openfreemap.org/styles/fiord` |
For a light/dark pair, use `bright` or `liberty` for light mode and `fiord` for dark mode.
+
+:::note Attribution
+
+When using the default server, the map shows **© OpenMapTiles · © OpenStreetMap contributors · © maps.mxd.codes** attribution. When a custom server is configured, attribution is read automatically from the style JSON served by your tile server.
+
+:::
+
+## Self-hosting tileserver-gl
+
+Setting up your own map tile server is straightforward. You need a server, an `.mbtiles` file and Docker.
+
+### Requirements
+
+- A Linux server (VPS or bare metal) with Docker installed
+- At least 4 GB RAM and 250+ GB disk space (planet-wide mbtiles are ~80-100 GB)
+- A domain name (optional but recommended for HTTPS)
+
+### 1. Download map tiles
+
+[OpenFreeMap](https://openfreemap.org) provides free planet-wide `.mbtiles` files updated weekly. Check their [index file](https://btrfs.openfreemap.com/files.txt) for the latest version, then download:
+
+```bash
+mkdir -p /opt/tileserver/data
+cd /opt/tileserver/data
+
+# Replace VERSION with the latest from the index file (e.g. 20260320_6)
+wget https://btrfs.openfreemap.com/areas/planet/VERSION/tiles.mbtiles
+# e.g. wget https://btrfs.openfreemap.com/areas/monaco/20260324_231001_pt/tiles.mbtiles
+```
+
+The planet mbtiles file is ~80-100 GB and may take a while depending on your connection.
+
+### 2. Add map styles
+
+tileserver-gl needs style JSON files, fonts and sprites to render tiles. The [OpenFreeMap styles](https://github.com/hyperknot/openfreemap-styles) are actively maintained forks of the original [OpenMapTiles](https://openmaptiles.org/) styles:
+
+- **Bright** - clean, bright style (light mode)
+- **Dark** - dark style (dark mode)
+- **Liberty** - community-maintained style (light mode)
+- **Positron** - minimal light style
+- **Fiord** - muted dark style
+
+#### Download styles
+
+```bash
+cd /opt/tileserver
+git clone https://github.com/hyperknot/openfreemap-styles.git
+
+# Copy the styles you want into a clean structure
+mkdir -p styles/bright styles/dark
+cp openfreemap-styles/styles/bright/style.json styles/bright/
+cp openfreemap-styles/styles/dark/style.json styles/dark/
+```
+
+#### Download fonts
+
+The styles use Noto Sans fonts. Download pre-built PBF font files from [openmaptiles/fonts](https://github.com/openmaptiles/fonts):
+
+```bash
+apt install -y unzip
+cd /opt/tileserver
+wget https://github.com/openmaptiles/fonts/releases/download/v2.0/noto-sans.zip
+unzip noto-sans.zip -d fonts
+rm noto-sans.zip
+```
+
+This creates the font directories tileserver-gl expects (e.g. `fonts/Noto Sans Regular/`, `fonts/Noto Sans Bold/`).
+
+#### Download sprites
+
+Sprites (map icons like parks, restaurants, etc.) are included in the OpenFreeMap styles repo:
+
+```bash
+cp -r openfreemap-styles/sprites/sprites/ofm_f384 sprites
+```
+
+You can remove the cloned repo afterwards:
+
+```bash
+rm -rf openfreemap-styles
+```
+
+Your directory structure should now look like this:
+
+```
+/opt/tileserver/
+ config.json
+ data/
+ tiles.mbtiles
+ styles/
+ bright/
+ style.json
+ dark/
+ style.json
+ fonts/
+ Noto Sans Bold/
+ Noto Sans Italic/
+ Noto Sans Regular/
+ sprites/
+ ofm_f384/
+ ofm.json
+ ofm.png
+```
+
+#### Edit the style JSON files
+
+The styles use `__TILEJSON_DOMAIN__` placeholders that need to be replaced with local paths. Run these commands from `/opt/tileserver/` to update all references at once:
+
+```bash
+cd /opt/tileserver
+
+# Point tile source to local mbtiles
+sed -i 's|"url": "https://__TILEJSON_DOMAIN__/planet"|"url": "mbtiles://{planet}"|g' \
+ styles/bright/style.json styles/dark/style.json
+
+# Point glyphs to local fonts
+sed -i 's|"glyphs": "https://__TILEJSON_DOMAIN__/fonts/{fontstack}/{range}.pbf"|"glyphs": "{fontstack}/{range}.pbf"|g' \
+ styles/bright/style.json styles/dark/style.json
+
+# Point sprites to local files
+sed -i 's|"sprite": "https://__TILEJSON_DOMAIN__/sprites/ofm_f384/ofm"|"sprite": "sprites/ofm_f384/ofm"|g' \
+ styles/bright/style.json styles/dark/style.json
+
+# Remove unused ne2_shaded raster source
+python3 -c "
+import json
+for f in ['styles/bright/style.json', 'styles/dark/style.json']:
+ with open(f) as fh: d = json.load(fh)
+ d['sources'].pop('ne2_shaded', None)
+ with open(f, 'w') as fh: json.dump(d, fh, indent=2)
+"
+```
+
+The `{planet}` name in the tile source must match the key in the `data` section of `config.json` (see below). After these changes, all styles reference local files only - you can customize the style JSONs freely without depending on any remote service.
+
+#### Create the tileserver-gl config
+
+Create the `config.json`:
+
+```bash
+cat > /opt/tileserver/config.json << 'EOF'
+{
+ "options": {
+ "paths": {
+ "styles": "/styles",
+ "fonts": "/fonts",
+ "sprites": "/sprites",
+ "mbtiles": "/data"
+ }
+ },
+ "data": {
+ "planet": {
+ "mbtiles": "tiles.mbtiles"
+ }
+ },
+ "styles": {
+ "bright": {
+ "style": "/styles/bright/style.json"
+ },
+ "dark": {
+ "style": "/styles/dark/style.json"
+ }
+ }
+}
+EOF
+```
+
+### 3. Start tileserver-gl
+
+```bash
+docker run -d \
+ --name tileserver \
+ --restart unless-stopped \
+ -p 8080:8080 \
+ -v /opt/tileserver/data:/data \
+ -v /opt/tileserver/styles:/styles \
+ -v /opt/tileserver/fonts:/fonts \
+ -v /opt/tileserver/sprites:/sprites \
+ -v /opt/tileserver/config.json:/config.json \
+ maptiler/tileserver-gl \
+ --config /config.json
+```
+
+Your tile server is now running at `http://your-server:8080`. Open it in a browser to see the available styles and a preview map.
+
+### 3. Set up a reverse proxy (recommended)
+
+Use nginx to add HTTPS, caching and rate limiting. Install nginx and create a config:
+
+```nginx
+proxy_cache_path /var/cache/nginx/tiles levels=1:2 keys_zone=tiles:100m
+ max_size=10g inactive=7d use_temp_path=off;
+
+server {
+ listen 443 ssl http2;
+ server_name tiles.example.com;
+
+ ssl_certificate /etc/letsencrypt/live/tiles.example.com/fullchain.pem;
+ ssl_certificate_key /etc/letsencrypt/live/tiles.example.com/privkey.pem;
+
+ location / {
+ proxy_pass http://127.0.0.1:8080;
+ proxy_cache tiles;
+ proxy_cache_valid 200 7d;
+ proxy_cache_use_stale error timeout updating;
+ add_header X-Cache-Status $upstream_cache_status;
+ }
+}
+```
+
+With caching enabled, most tile requests are served directly from nginx without hitting tileserver-gl.
+
+### 4. Connect Colota
+
+1. Open **Settings** in Colota
+2. Scroll to **Appearance** and tap **Map Tile Server**
+3. Enter your style URLs:
+ - Light: `https://tiles.example.com/styles/bright/style.json`
+ - Dark: `https://tiles.example.com/styles/dark/style.json`
+
+The available style names depend on your tileserver-gl configuration. Visit your server's root URL to see which styles are served.
+
+### Updating tiles
+
+To update your map tiles, find the latest version from the [index file](https://btrfs.openfreemap.com/files.txt), then download and swap:
+
+```bash
+cd /opt/tileserver/data
+
+# Find the latest planet version
+LATEST=$(curl -s https://btrfs.openfreemap.com/files.txt | grep 'areas/planet' | grep '.mbtiles' | tail -1 | sed 's|.*areas/planet/||;s|/tiles.mbtiles||')
+
+# Download and replace
+wget -O tiles-new.mbtiles "https://btrfs.openfreemap.com/areas/planet/${LATEST}/tiles.mbtiles"
+mv tiles-new.mbtiles tiles.mbtiles
+docker restart tileserver
+```
+
+You can automate this with a weekly cron job.
+
+### Other self-hosting options
+
+- [OpenFreeMap self-hosting](https://github.com/hyperknot/openfreemap/blob/main/docs/self_hosting.md) - serves tiles directly from Btrfs partition images via nginx, no tile server process needed. Higher performance than tileserver-gl but requires a dedicated clean Ubuntu server and more setup.
+- [PMTiles](https://docs.protomaps.com/pmtiles/) - a single static file format that can be served from any object storage (S3, Cloudflare R2, etc.) with no server process required.