DEV Community: bolo

MapTiler Server on Raspberry Pi - A Geeks' Guide to Self-Hosted Maps

bolo — Tue, 23 Sep 2025 11:34:46 +0000

Unleash Your Inner Cartographer (and Powerful Maps!)

Why Build Your Own Map Server?

Tired of relying on Google Maps? With MapTiler Server on a Raspberry Pi, you’ll get:

✅ Privacy and offline: Maps stay on your device.
✅ Control: Add custom styles, overlays, or data.
✅ Experience: Master Linux, APIs, and geospatial tech with ease.
✅ Fun: Build a sample "Explore Zurich" dashboard with beautiful offline maps!

What You’ll Build

By the end of this guide, your Raspberry Pi will:

Serve maps like a pro (even with a free tier license).
Run a demo dashboard app on your display or a full-screen dashboard directly on the Pi.
Handle basic tasks like configuring Pi, uploading sample data, and deploying a simple web app.

What You’ll Need

Item	Why You Need It
Raspberry Pi (4/5) Raspberry 3 A+ too … wait until the end	The brain of your map server
MicroSD card (32GB+)	Storage for your OS and maps
Power supply	Keep your Pi alive!
Monitor/keyboard/mouse	For setup (you can unplug later)

Flashing the OS – Breathing Life into Your Pi

Step 1: Install Raspberry Pi Imager

Download Raspberry Pi Imager from the official website.
Install it on your computer (available for Windows, macOS, and Linux).

Step 2: Choose the OS

Choose Pi version based on your model.
Select Choose OS and pick Raspberry Pi OS (64-bit) or another compatible image.
Select your MicroSD card under Choose Storage.

Step 3: Use Edit Settings for Pre-Configuration

Configure the following settings:
- Hostname: Set a custom name (e.g., pi-maps).
- Username and Password: Create a username you like and a secure password for the admin user.
- Wi-Fi: Enter your SSID and password to connect automatically.
- Locale: Set your language and country code.
- SSH (under Services): Enable SSH for remote access.
Click Save to return to the main menu.

Step 4: Finish the SD card and boot your Pi

Click Write, confirm, and wait for the process to complete.
Insert the MicroSD card into your Raspberry Pi and power it on.
The pre-configured settings will automatically apply, saving you time during setup!

Installing MapTiler Server on a Raspberry Pi via CLI

Step 1: Download and Install MapTiler Server

Download the ARM64 .deb package for MapTiler Server from the official website.
Transfer the file to your Raspberry Pi (if downloaded on another machine).

💡 Tip

You can drag and drop the installer on to your SD card after flashing it. The installer will be located in /boot/firmware/ path.
Open the terminal on your Raspberry Pi and run:

  sudo dpkg -i maptiler-server-4.6.1-linux-arm64.deb

(use correct installer filename and path like /boot/firmware/maptiler-server-4.6.1-linux-arm64.deb)

Step 2: Start the Server

Launch MapTiler Server with the following command:
```
maptiler-server
```
The server will start, and you can access it in your browser at:

http://:3650/admin/

If you run the server without options, Server automatically generates the initial config and password. Keep it for login to Server Admin interface.

💡 Tip

Run maptiler-server --help to explore more options like how to set password, home dir, and other options.

Step 3: Enable Auto-Start (Optional)

To ensure MapTiler Server starts automatically on boot as a service:

sudo maptiler-server-servicify

This command starts a script that guides you through setting up MapTiler Server’s working directory (use absolute path), port, and administration password. Then it creates the systemd service file and starts the service.

Adding Free Sample Data to MapTiler Server

Step 1: Download the Free Sample Data

Go to MapTiler Data and log in (you have an account created from server installer download).
Click on "MY DATA" in the top right corner.
Navigate to the Server tab and download the free sample data package (a ZIP file). This package includes map styles and data for the Zurich area.

Step 2: Upload the Sample Data to MapTiler Server

Open the MapTiler Server admin interface in your browser:
http://:3650/admin/
Log in with your admin credentials.
In the admin interface, click "New Map" or drag and drop the downloaded ZIP file directly into the interface.
Wait for MapTiler Server to process and upload the sample data.

Step 3: Explore the Sample Data

Once uploaded, navigate to the Tiles tab to preview the raw OpenStreetMap dataset for Zurich.
Switch to the Maps tab to view different map styles (e.g., Streets, Outdoor, Satellite Hybrid).
- These styles are pre-configured and ready to use with the Zurich dataset.

Step 4: Test Your Setup

Open any map style in your browser by clicking on it in the Maps tab.
Use zoom levels up to 14 for full details in Zurich or experiment with over-zooming for higher levels.

⚠️ Warning
On low-memory or lightweight Pi versions (such as my Pi 3 A+), STOP here. Running MapTiler Server and a browser on the same board is not a great idea. However, you can use these versions to serve tiles to a browser running on another device.

Create a Dashboard on Raspberry Pi

An auto-rotating map display for exploring Zurich using Raspberry Pi's power

Step 1: Create the HTML File

On your Raspberry Pi, create a new file:
```
nano ~/explore-zurich.html
```

Paste this complete code:

<!DOCTYPE html>
<html>
<head>
<title>Explore Zurich</title>
<script src="https://cdn.maptiler.com/maptiler-sdk-js/v3.0.1/maptiler-sdk.umd.min.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v3.0.1/maptiler-sdk.css" rel="stylesheet" />
<style>
    body { margin: 0; padding: 0; }
    #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    .map-title { 
        position: absolute; 
        top: 10px; 
        left: 10px; 
        z-index: 1; 
        background: white; 
        padding: 5px 10px; 
        border-radius: 5px;
        font-family: Arial;
    }
</style>
</head>
<body>
<div class="map-title" id="styleName">Zurich Explorer 🗺️</div>
<div id="map"></div>

<script>
    // Initialize with MapTiler SDK
    maptilersdk.config.apiKey = '';  // No API key needed for local server

    // Zurich bounding box coordinates
    const ZURICH_BBOX = {
        minLon: 8.4476, 
        maxLon: 8.5926,
        minLat: 47.3362,
        maxLat: 47.4145
    };

    // Available styles from your sample data
    const styles = [
        { id: "basic", name: "Basic Style" },
        { id: "outdoor", name: "Outdoor Style" },
        { id: "streets", name: "Streets Style" },
        { id: "satellite-hybrid", name: "Satellite Hybrid" }
    ];

    let currentStyleIndex = 0;

    // Initialize map with the first style
    const map = new maptilersdk.Map({
        container: 'map',
        style: `http://localhost:3650/api/maps/basic/style.json`,
        center: [8.5417, 47.3769], // Zurich center
        zoom: 12
    });

    // Random position generator within Zurich
    function getRandomZurichPosition() {
        const lon = ZURICH_BBOX.minLon + 
            Math.random() * (ZURICH_BBOX.maxLon - ZURICH_BBOX.minLon);

        const lat = ZURICH_BBOX.minLat + 
            Math.random() * (ZURICH_BBOX.maxLat - ZURICH_BBOX.minLat);

        return [lon, lat];
    }

    // Update map every minute
    function updateMap() {
        // Cycle through styles
        currentStyleIndex = (currentStyleIndex + 1) % styles.length;
        const style = styles[currentStyleIndex];

        map.setStyle(`http://localhost:3650/api/maps/${style.id}/style.json`);
        document.getElementById('styleName').textContent = style.name;

        // Fly to random position
        map.flyTo({
            center: getRandomZurichPosition(),
            zoom: 14 + Math.random() * 4, // Random zoom between 14-18
            duration: 3000
        });
    }

    // Initial update and set interval
    map.on('load', function() {
        updateMap();
        setInterval(updateMap, 10000);
    });
</script>
</body>
</html>

Step 2: Access the Dashboard

Open Chromium browser on your Pi:
```
chromium-browser ~/explore-zurich.html
```

For kiosk mode (fullscreen):

chromium-browser --kiosk ~/explore-zurich.html

What You'll See

✅ Automatic style rotation every 10secs
✅ Smooth transitions between random Zurich locations
✅ Four different map perspectives from your sample data

Pi 3 A+ serving tiles to map dashboard running from desktop.

Lessons learned

Raspberry Pi 3 A+ is fine for hosting and serving tiles (especially with disabled GUI), but can't be used to render a web map dashboard to a display at the same time. Use recent Pi version (4/5) to get smooth map experience, pick >8GB memory board for hi-resolution displays.
For some scenarios, get the Pi IP address and connect to the console via SSH.
For a fully offline solution, put MapTiler SDK JS and CSS directly on the Pi and refer locally

Beyond the Basics

Adding custom data.
Try switching to 3D / Globe view
More SDK features - e.g., store locations in your lobby
Add a daily fact about the randomly selected location using a geocoding API.
Implement a simple weather overlay for the chosen location.
Configure your Pi to run Chromium.

From zero to web mapping hero in 60 days

bolo — Thu, 03 Oct 2024 09:46:06 +0000

Over the past two years, I’ve focused on creating the documentation for the MapTiler SDK, an open-source JavaScript library designed to extend the functionality of the MapLibre SDK and simplify its use. I aimed to create a comprehensive resource with practical examples for building web maps.

This summer, I shared the documentation through a series of tutorials on social media under the #SummerOfMaps hashtag. Each week, I covered a new topic with seven examples.

Following the series from start to finish provides a solid foundation for building web maps, even if you have no prior experience, so I have gathered them all here in one place for you to work through!

Warm-up: What are web maps and how do they work

The week before the launch, I shared a few articles and videos created by my colleagues. These resources cover the theoretical foundations of web maps, explaining what they are, how they function, and the underlying mathematics that makes them work.

How to add a map to the web; the basics

In the first week, I covered the basics of adding a map to a webpage. The only prerequisites were a basic understanding of JavaScript and HTML—no prior experience with web maps or map libraries was necessary.

Pinpoint locations with markers

A common feature of web maps is the marker, which indicates the location of specific elements. It could be a basic pin, a custom icon, an image, or something that reveals additional data when clicked. Markers can also connect to external data sources to load information dynamically. Throughout the tutorials, you'll learn how to implement each of these options.

Present data as points on a map

Points in web maps are used to represent individual data elements. You'll learn how to display points on a map, apply styling based on their attributes, and group them into clusters for easier visualization of large datasets. Additionally, you’ll explore how to convert point data into heatmaps, making it easier to spot density patterns and trends at a glance.

Add lines to your web map

Lines are another key element for displaying geographic information. You’ll learn how to add basic lines from GeoJSON, apply gradients, create lines that indicate progress (e.g., tracking a moving object), explore different line types, and style them for better visualization.

Add polygons to your web map

Polygons are another common way to represent geospatial data, often used to show area boundaries or the density of features within a region. You’ll learn how to add basic polygons, fill them with patterns or color gradients based on data intensity, integrate pop-ups, and combine them with points and lines for complex visualizations.

How to adjust map controls

To enhance usability, you'll want to provide your users with intuitive control options. You'll learn how to add basic controls like zoom buttons and tilt & shift controls, as well as more advanced features such as location tracking, a scale bar, a minimap, geocoding search, and even an AR button that allows users to view the map in augmented reality on compatible devices.

Adding additional data sources to a web map

Even though MapTiler provides various data sources, there may be times when you need to incorporate your own data. You'll learn how to add custom layers, including raster layers, hillshade, vector tiles, local GeoJSON files, and even video, giving you full control over the map's content.

Create a weather map

While often viewed as niche, weather maps are surprisingly easy to integrate into your website and are worth experimenting with. In the examples, you’ll learn how to add layers for precipitation, radar data, pressure, temperature, and wind direction. We'll also dive into more advanced use cases where you can combine multiple layers to create richer visualizations.

Complex examples

In the final week, I shifted focus to more complex examples, combining the concepts from earlier tutorials with new techniques. These examples demonstrated how to build tools that could function as a minimal viable product for your future applications.

Do you still want more?

You can find all posts about the #SummerOfMaps series on Twitter/X, LinkedIn, and Facebook. Our documentation and API reference provide even more examples.

If you prefer using Leaflet, OpenLayers, or other map libraries, you’ll find examples for them in the documentation as well.

How to use Vector Tiles in Leaflet

bolo — Fri, 17 Nov 2023 16:39:00 +0000

Leaflet is a lightweight open-source library for creating online maps. It works efficiently across all major desktop and mobile platforms and can be extended with many plugins.

Leaflet doesn’t support vector tiles by default, but you can use one of the available plugins to display them. We will use the Basemaps with Vector Tiles plugin in this example. You’ll need a MapTiler account to use the plugin, but these are free for non-commercial use and give you access to a lot of great map styles. You can create a free account here.

If you want to know the differences between Raster and Vector data and when you should use vector tiles, we’ve added a handy guide to the end of this tutorial: Vector vs. Raster tiles.

Create a map and display it on a web page

Simple web technologies like HTML, CSS, and JavaScript are required to add a map to our web page. We’ve included all the code you need to create the page below.

HTML Boilerplate

Create a basic HTML file.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Display a map</title>
  <style>
    body {
      margin: 0;
      padding: 0;
    }
  </style>
</head>
<body>

</body>
<script>

</script>
</html>

Include the Leaflet JavaScript and CSS files in the head of your HTML file.

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY=" crossorigin="" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js" integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>

Create a Map container and create a Map object

Create a <div> element with a certain id where you want your map to be.

Add <div> tag to your page. This div will be the container where the map will be loaded.

<body>
  <div id="map"></div>
</body>

The div must have a non-zero height. Create a rule for the style of the map in the CSS of the page. In this example, we are going to make a full-screen map.

#map {
    position: absolute;
    top: 0;
    bottom: 0;
    width: 100%;
}

Now, in your JavaScript, create a map object. We’ll initialize the map with the id of the container element created before i.e. “map” and set its view to our chosen geographical coordinates [lat, lng] and a zoom level.

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

Add the Vector Tiles basemap

Leaflet is a JavaScript map API that does not provide any data. Leaflet depends on third parties to provide the basemap. Generally, Leaflet is used with Raster Tiles basemaps like OpenStreetMap, Esri, Bing Maps, MapTiler, etc.

As previously explained, using a vector basemap has multiple advantages over raster maps. That is why we are going to use the Basemaps with Vector Tiles plugin.

Include the plugin JavaScript and CSS files in the head of your HTML file.

All leaflet plugin libraries must be loaded after Leaflet JavaScript

<script src="https://cdn.maptiler.com/maptiler-sdk-js/v1.1.2/maptiler-sdk.umd.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v1.1.2/maptiler-sdk.css" rel="stylesheet" />
<script src="https://cdn.maptiler.com/leaflet-maptilersdk/v1.0.0/leaflet-maptilersdk.js"></script>

We use the L.maptilerLayer class to create a layer to load and display our map. In your JS code, after the map object creation, write the following line:

const mtLayer = L.maptilerLayer({ apiKey: `YOUR_MAPTILER_API_KEY_HERE` }).addTo(map);

Replace YOUR_MAPTILER_API_KEY_HERE with your actual MapTiler API key.

Using the L.maptilerLayer you have:

All the power of MapTiler SDK JS to use vector tile layers (for data overlays) in your applications without any kind of limitation (show millions of geometries, choropleth maps, etc.).
Multi-lingual vector tiles basemaps for Leaflet using the MapTiler SDK.
Use any of the many professional-looking basemaps created by MapTiler, or use a map with your own custom basemap.
Easily change the language of your map without having to create a new basemap.
Locate the user and center the map accordingly.

Complete Code and Result

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
    <title>Vector Tiles in Leaflet JS</title>
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
    <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
    <script src="https://cdn.maptiler.com/maptiler-sdk-js/v1.1.2/maptiler-sdk.umd.js"></script>
    <link href="https://cdn.maptiler.com/maptiler-sdk-js/v1.1.2/maptiler-sdk.css" rel="stylesheet" />
    <script src="https://cdn.maptiler.com/leaflet-maptilersdk/v1.0.0/leaflet-maptilersdk.js"></script>
    <style>
      #map {position: absolute; top: 0; right: 0; bottom: 0; left: 0;}
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      const map = L.map('map').setView([0, 0], 1);
      const mtLayer = L.maptilerLayer({ apiKey: 'YOUR_MAPTILER_API_KEY_HERE' }).addTo(map);
    </script>
  </body>
</html>

Extra features of using the Vector Tiles plugin

Change the map language

If nothing is specified by default, the plugin uses the language defined in the browser. To change the map language, use the setLanguage function of the maptilerLayer layer.

mtLayer.setLanguage(ja); //change the language to Japanese

Use the built-in basemap styles.

The plugin comes with a list of built-in basemap styles. It shows the street map by default, but you can easily change the styles using the setStyle function.

mtLayer.setStyle(L.MaptilerStyle.DATAVIZ.DARK); //change to dark style map for data visualization

Check out the plugin API reference for all options and methods.

Conclusions

Using a vector basemap has advantages over traditional raster basemaps. You can easily replace your raster basemap with a vector one. The rest of your application and layers will continue to work normally. Just replace the L.TileLayer layer with the L.maptilerLayer.

Example: replace the OpenStreetMap basemap (L.tileLayer)

 const rasterLayer = L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
    attribution: '© OpenStreetMap contributors'
}).addTo(map);

with the vector tiles basemap (L.maptilerLayer)

const mtLayer = L.maptilerLayer({ apiKey: 'YOUR_MAPTILER_API_KEY_HERE' }).addTo(map);

Raster vs Vector Map Tiles: What Is the Difference Between the Two Data Types?

Web maps based on raster tiles technology are older but still widely used approach by many.

Raster map tiles are actually nothing else than raster images. Zoomable raster maps consist of many raster map tiles (in the .png or .jpg format) placed next to each other, ordered in a pyramid scheme.

Vector tiles also deliver data divided into roughly squared tiles, but they were introduced later. However, these tiles do not consist of raster images; they are made of geometric features such as points, curves, or polygons. Vector tiles are rendered on the client’s side with a style. This is a small text file that defines how certain map elements look and how they are displayed (e.g., a road can be defined as a solid red line placed on top of all map elements).

It is possible to mix raster with vector tiles and get the best out of both, e.g., a satellite map (raster tiles) with an overlay of streets and labels available in different languages (vector tiles).