DEV Community

Cover image for MapTiler Server on Raspberry Pi - A Geeks' Guide to Self-Hosted Maps
bolo
bolo

Posted on

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

#raspberrypi #map #programming #maptiler

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:

  1. Serve maps like a pro (even with a free tier license).

  2. Run a demo dashboard app on your display or a full-screen dashboard directly on the Pi.

  3. 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)

Raspberry Pi board

Flashing the OS – Breathing Life into Your Pi

Step 1: Install Raspberry Pi Imager

  1. Download Raspberry Pi Imager from the official website.

  2. Install it on your computer (available for Windows, macOS, and Linux).

Step 2: Choose the OS

  1. Choose Pi version based on your model.

  2. Select Choose OS and pick Raspberry Pi OS (64-bit) or another compatible image.

  3. Select your MicroSD card under Choose Storage.

Step 3: Use Edit Settings for Pre-Configuration

  1. 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.

  2. Click Save to return to the main menu.

Raspberry Pi OS customisation settings

Step 4: Finish the SD card and boot your Pi

  1. Click Write, confirm, and wait for the process to complete.

  2. Insert the MicroSD card into your Raspberry Pi and power it on.

  3. 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

  1. Download the ARM64 .deb package for MapTiler Server from the official website.

  2. 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.

  3. Open the terminal on your Raspberry Pi and run:

  sudo dpkg -i maptiler-server-4.6.1-linux-arm64.deb
Enter fullscreen mode Exit fullscreen mode

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

Step 2: Start the Server

  1. Launch MapTiler Server with the following command:

    maptiler-server

  2. The server will start, and you can access it in your browser at:

    http://:3650/admin/

    MapTiler server sign-in screen

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
Enter fullscreen mode Exit fullscreen mode

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

  1. Go to MapTiler Data and log in (you have an account created from server installer download).

  2. Click on "MY DATA" in the top right corner.

  3. 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

  1. Open the MapTiler Server admin interface in your browser:
    http://:3650/admin/

  2. Log in with your admin credentials.

  3. In the admin interface, click "New Map" or drag and drop the downloaded ZIP file directly into the interface.

  4. Wait for MapTiler Server to process and upload the sample data.
    Download MapTiler sample data package progress

Step 3: Explore the Sample Data

  1. Once uploaded, navigate to the Tiles tab to preview the raw OpenStreetMap dataset for Zurich.

  2. 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. MapTiler Server satellite hybrid map

Step 4: Test Your Setup

  1. Open any map style in your browser by clicking on it in the Maps tab.

  2. 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

  1. On your Raspberry Pi, create a new file:

    nano ~/explore-zurich.html

  2. 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

  1. Open Chromium browser on your Pi:

    chromium-browser ~/explore-zurich.html

  2. 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


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

Top comments (0)