Deploying TileServer GL

Introduction

TileServer GL is an open-source map tile server that serves vector and raster tiles using Mapbox GL styles. It allows you to host your own map tiles and styles, providing independence from commercial mapping services while delivering beautiful, customizable maps. TileServer GL supports MBTiles format, making it easy to deploy with OpenMapTiles or other vector tile providers.

Key features of TileServer GL include:

• Vector Tile Serving: Serve MVT (Mapbox Vector Tiles) from MBTiles files
• Raster Tile Rendering: Generate raster tiles from vector tiles on-the-fly
• Mapbox GL Styles: Full support for Mapbox GL JSON style specification
• Custom Fonts: Serve custom fonts for map labels
• Sprite Sheets: Support for map icons and patterns
• WMTS Support: Web Map Tile Service compatibility
• Preview Interface: Built-in viewer for testing maps
• High Performance: Optimized for serving tiles at scale
• Docker Ready: Easy deployment with official Docker images

This guide walks you through deploying TileServer GL on Klutch.sh, configuring map tiles and styles, and integrating with web mapping applications.

Why Deploy TileServer GL on Klutch.sh

Deploying TileServer GL on Klutch.sh provides several advantages:

Data Sovereignty: Host your own map tiles without depending on third-party services.

Cost Control: Serve unlimited map requests without per-tile pricing.

Simplified Deployment: Klutch.sh handles container orchestration and HTTPS automatically.

Persistent Storage: Store large MBTiles files reliably across deployments.

Scalable Resources: Adjust resources based on map traffic and rendering demands.

Custom Styling: Serve your own custom map styles without restrictions.

Prerequisites

Before deploying TileServer GL on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• MBTiles files (vector or raster tiles)
• Map styles in Mapbox GL JSON format (optional)
• Basic familiarity with Docker and web mapping

Understanding Map Tile Concepts

Vector Tiles: Contain geographic data as vectors, rendered client-side

Raster Tiles: Pre-rendered images served to clients

MBTiles: SQLite database format for storing map tiles

Mapbox GL Style: JSON specification for map appearance

Preparing Your Repository

Create a GitHub repository with the following structure:

tileserver-deploy/
├── Dockerfile
├── .dockerignore
├── config.json
├── styles/
│   └── osm-bright/
│       └── style.json
└── fonts/

Creating the Dockerfile

FROM maptiler/tileserver-gl:latest

# Create directories for data
RUN mkdir -p /data /data/fonts /data/sprites

# Copy configuration
COPY config.json /data/config.json
COPY styles/ /data/styles/

# Environment variables
ENV PORT=8080

EXPOSE 8080

# Run TileServer GL
CMD ["--config", "/data/config.json", "--verbose", "--port", "8080"]

Configuration File

Create config.json:

{
  "options": {
    "paths": {
      "root": "/data",
      "fonts": "/data/fonts",
      "sprites": "/data/sprites",
      "styles": "/data/styles",
      "mbtiles": "/data"
    }
  },
  "styles": {
    "osm-bright": {
      "style": "osm-bright/style.json",
      "tilejson": {
        "type": "overlay",
        "bounds": [-180, -85.05, 180, 85.05]
      }
    }
  },
  "data": {
    "planet": {
      "mbtiles": "planet.mbtiles"
    }
  }
}

Environment Variables Reference

Variable	Required	Default	Description
PORT	No	8080	HTTP server port

Deploying on Klutch.sh

Obtain Map Tiles

Download MBTiles files for your region:

• OpenMapTiles for vector tiles
• Natural Earth for base layers
• Or generate custom tiles with tippecanoe

Prepare Map Styles

Download or create Mapbox GL styles:

• OSM Bright, Positron, Dark Matter from OpenMapTiles
• Custom styles using Maputnik style editor

Push Your Repository to GitHub

Commit and push your Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “tileserver” or “maps”.

Create the TileServer GL App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set the traffic type to HTTP with the internal port set to 8080.

Attach Persistent Volumes

Add persistent storage for map data:

Mount Path	Size	Purpose
/data	50+ GB	MBTiles, styles, fonts (size depends on tile coverage)

Upload MBTiles Files

Transfer your MBTiles files to the persistent volume.

Deploy Your Application

Click Deploy to build and launch TileServer GL.

Access the Map Preview

Visit https://your-app-name.klutch.sh to see the built-in tile viewer.

Configuring Map Styles

Style Structure

Mapbox GL style JSON structure:

{
  "version": 8,
  "name": "My Style",
  "sources": {
    "openmaptiles": {
      "type": "vector",
      "url": "mbtiles://{planet}"
    }
  },
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {
        "background-color": "#f8f4f0"
      }
    }
  ]
}

Adding Custom Fonts

Include fonts for map labels:

1. Download font glyphs in PBF format
2. Place in /data/fonts/fontname/ directory
3. Reference in your style’s glyphs property

Adding Sprites

Include icons and patterns:

1. Create sprite images and JSON
2. Place in /data/sprites/ directory
3. Reference in style’s sprite property

Using the Tile Server

Tile Endpoints

Access tiles through standard URLs:

Vector Tiles (MVT):

https://your-server/data/planet/{z}/{x}/{y}.pbf

Raster Tiles (PNG):

https://your-server/styles/osm-bright/{z}/{x}/{y}.png

TileJSON:

https://your-server/data/planet.json
https://your-server/styles/osm-bright.json

Integration with Mapbox GL JS

mapboxgl.accessToken = '';  // Not needed for self-hosted

const map = new mapboxgl.Map({
    container: 'map',
    style: 'https://your-server/styles/osm-bright/style.json',
    center: [0, 0],
    zoom: 2
});

Integration with Leaflet

Using leaflet-mapbox-gl plugin:

const map = L.map('map').setView([0, 0], 2);

L.mapboxGL({
    style: 'https://your-server/styles/osm-bright/style.json'
}).addTo(map);

Integration with OpenLayers

import Map from 'ol/Map';
import View from 'ol/View';
import VectorTileLayer from 'ol/layer/VectorTile';

const map = new Map({
    target: 'map',
    layers: [
        new VectorTileLayer({
            source: new VectorTileSource({
                url: 'https://your-server/data/planet/{z}/{x}/{y}.pbf'
            })
        })
    ],
    view: new View({
        center: [0, 0],
        zoom: 2
    })
});

WMTS Support

TileServer GL provides WMTS endpoints:

https://your-server/styles/osm-bright/wmts.xml

Use with GIS applications:

• QGIS
• ArcGIS
• MapInfo

Production Best Practices

Performance Optimization

• Tile Caching: Use a CDN for cached tile delivery
• Raster Cache: Enable caching for server-side rendered tiles
• Resource Allocation: Allocate adequate memory for rendering
• Tile Size: Optimize vector tile size during generation

Storage Considerations

MBTiles files can be large:

Coverage	Approximate Size
Single city	50-200 MB
Country	1-10 GB
Continent	20-50 GB
Global	50-100+ GB

Security Recommendations

• CORS Configuration: Configure appropriate CORS headers
• Rate Limiting: Implement rate limiting for public access
• Access Control: Add authentication if needed
• HTTPS Only: Use Klutch.sh’s automatic SSL

Monitoring

Track tile server health:

• Monitor request rates
• Track tile generation times
• Watch memory usage during rendering
• Log error rates by zoom level

Troubleshooting

Tiles Not Loading

• Verify MBTiles file path in configuration
• Check file permissions
• Validate MBTiles with sqlite3 command
• Review server logs for errors

Style Errors

• Validate JSON syntax
• Check source references match data names
• Verify font and sprite paths
• Use Maputnik for style debugging

Slow Rendering

• Increase container memory
• Enable tile caching
• Use pre-rendered raster tiles for high traffic
• Consider CDN caching

CORS Issues

Add CORS headers in nginx or proxy:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET

Additional Resources

• TileServer GL Documentation
• TileServer GL GitHub Repository
• OpenMapTiles
• Maputnik Style Editor
• Mapbox GL Style Specification
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying TileServer GL on Klutch.sh gives you complete control over your map infrastructure. With support for vector and raster tiles, Mapbox GL styles, and standard protocols, TileServer GL provides everything needed to serve beautiful maps from your own platform. The combination of self-hosted tiles and Klutch.sh’s reliable infrastructure ensures your mapping applications remain fast, customizable, and independent of third-party services.