DOCSEARCHbyAlgolia
Submit Docs

OpenFreeMap Documentation

repository·main·Indexed 26 days ago

https://github.com/hyperknot/openfreemap

Open-source, production-quality vector-tile hosting using OpenStreetMap data. Supports a free public instance and self-hosting on Ubuntu servers via a specialized Btrfs-based file system. Includes guides for deploying http-host and tile-gen modules, performing HTTP benchmarks with wrk, downloading full planet tiles in Btrfs and MBTiles formats, and debugging international name display issues.

Tokens
4.9K
Snippets
14
Records
31
Agent score
90%

What's inside OpenFreeMap

  1. Overview of OpenFreeMap usage models

    main

    OpenFreeMap provides a way to display custom maps on websites and applications using OpenStreetMap data. You can use the service in two ways:

    1. Public Instance: Completely free to use with no limits on map views or requests. It requires no registration, no user database, no API keys, and no cookies.
    2. Self-hosting: Since the project is fully open-source (not 'open-core'), you can host the entire production setup yourself.

    Weekly full planet downloads are available in both Btrfs and MBTiles formats for those managing their own data.

  2. Overview of OpenFreeMap capabilities and limitations

    main

    OpenFreeMap provides free, production-quality vector-tile hosting using OpenStreetMap data.

    Supported Features:

    • Vector-tile hosting (via Btrfs partition images and nginx).
    • Weekly full planet updates.
    • Open-source production setup.

    Unsupported Features (By Design):

    • Search or geocoding.
    • Route calculation, navigation, or directions.
    • Static image generation.
    • Raster tile hosting.
    • Satellite image hosting.
    • Elevation lookup.
    • Custom tile or dataset hosting.

  4. Use OpenFreeMap with OpenLayers via ol-mapbox-style

    main

    To use OpenFreeMap tiles in an OpenLayers application, use the ol-mapbox-style add-on to create a layer group from an OpenFreeMap style URL.

    1. Include the OpenLayers and ol-mapbox-style scripts and CSS in your HTML.
    2. Create an ol.layer.Group instance.
    3. Initialize an ol.Map using that group as a layer.
    4. Use olms.apply() to apply the OpenFreeMap style to the layer group.
    <!-- OpenLayers -->
<script src="https://unpkg.com/ol/dist/ol.js"></script>
<link rel="stylesheet" href="https://unpkg.com/ol/ol.css" />

<!-- ol-mapbox-style -->
<script src="https://unpkg.com/ol-mapbox-style/dist/olms.js"></script>

<div id="map" style="width: 100%; height: 500px"></div>
<script>
  const openfreemap = new ol.layer.Group()
  const map = new ol.Map({
    layers: [openfreemap],
    view: new ol.View({ center: ol.proj.fromLonLat([13.388, 52.517]), zoom: 9.5 }),
    target: 'map',
  })
  olms.apply(openfreemap, 'https://tiles.openfreemap.org/styles/liberty')
</script>

  5. Self-host OpenFreeMap

    main

    OpenFreeMap can be self-hosted on clean Ubuntu servers or virtual machines. The project is not designed for local installation; instead, it provides a deploy script that uses Fabric to set up production-ready servers via SSH.

    Important Limitations:

    • The repository is Docker-free by design.
    • It is a deploy script for Ubuntu, not a local package.
    • Only use the http-host-autoupdate version if you monitor the repository closely, as automatic updates are not guaranteed to be worry-free.

    For detailed instructions, refer to the self hosting docs.

  6. Run HTTP hosts benchmarks with wrk

    main

    Benchmarks are performed using the wrk HTTP benchmarking tool.

    Critical Requirement: Always run benchmarks against localhost. Running benchmarks over the internet will measure your internet connection speed rather than the host performance.

    To run a basic benchmark, use the following command structure:

    wrk -c10 -t4 -d10s -s /data/ofm/benchmark/wrk_custom_list.lua http://localhost

  9. Migrate from Mapbox to MapLibre GL JS

    main

    If you are using Mapbox and want to use OpenFreeMap, you should migrate your libraries to MapLibre GL JS. MapLibre is an open-source fork based on the last open-source version of Mapbox GL JS.

    Migration is typically achieved by replacing the Mapbox libraries with MapLibre libraries. This is straightforward provided your implementation does not rely on features specific to Mapbox GL JS version 2.x or later.

  10. Deploy http-host to a remote server

    main

    The deployment process is managed by a Python script that runs locally and deploys to a remote server via SSH.

    Prerequisites

    1. DNS: Configure an A record for your subdomain pointing to your server IP.
    2. Python: Ensure python3-pip is installed (on Ubuntu: sudo apt install python3-pip).
    3. Local Setup: Clone the repository and install the package in editable mode:
    git clone https://github.com/hyperknot/openfreemap
cd openfreemap
pip install -e .

    Step 1: Quick Test Deployment

    Set SKIP_PLANET=true in your .env file, then run the deployment script using your server's hostname:

    ./init-server.py http-host-static HOSTNAME

    Step 2: Full Planet Deployment

    Once the quick test is verified, set SKIP_PLANET=false in your .env file and run the same command again:

    ./init-server.py http-host-static HOSTNAME

    Note: If your server does not use an SSD, the download and decompression process may take several hours.

  11. Self-host OpenFreeMap via http-host

    main

    You can self-host OpenFreeMap using two modules: http-host (recommended for most users) and tile-gen (for generating your own tiles).

    System Requirements for http-host

    • Disk Space: At least 300 GB SSD recommended.
    • OS: Ubuntu 22 or newer.

    Deployment Warning

    This project is designed to run on clean servers or dedicated virtual machines. The deployment scripts require sudo permissions because they mount/unmount disk images and will modify your nginx configuration. Do not run these scripts on your local development machine unless you are using a virtual machine and understand the implications.

  12. Use the OpenFreeMap public instance

    main

    You can use the OpenFreeMap public instance for free to display custom maps on your website or apps. There are no limits on map views or requests, no registration required, no API keys, and no cookies.

    Note on Attribution: If you are using MapLibre, attribution is added automatically. For other clients or printed/video media, you must include:

    <a href="https://openfreemap.org" target="_blank">OpenFreeMap</a> <a href="https://www.openmaptiles.org/" target="_blank">&copy; OpenMapTiles</a> Data from <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a>