Mapforge

Create individual maps for your places, tracks and events. Share your maps in real-time. Try it now on mapforge.org.

Mapforge is an open source, easy to use GIS software. It's a web application that lets you create and share your places, tracks and events as GeoJSON layers on top of different base maps. It uses MapLibre GL JS as map library and supports both desktop and mobile.

Your browser connects to the server via WebSockets, so that changes are immediately synced to all clients. This enables collaborative editing and sharing real-time maps.

The main instance is running at mapforge.org, see self-hosting how to run your own. Check the changelog for recent changes. Contributions are welcome, see CONTRIBUTING.md.

Features

• Create maps with your own data on top of various available base maps.
• Self-host via container image, needs only Redis and MongoDB
• Draw shapes and style them: Add pictures, customize colors, symbols, labels, (3D) polygons and more
• Import and export GeoJSON, GPX and KML
• Real-time collaborative editing, changes sync to every connected client over WebSockets
• Share maps and embed on your own web page
• Desktop and mobile UI
• Integration with Overpass API for custom OpenStreetMap queries
• Login with Google, GitHub or OSM OAuth, no auth system to maintain
• PWA support by default, ships as an Android app via Bubblewrap
• Record GPS tracks with the built in µlogger API

Styling & Data Sources

GeoJSON layers can be styled using an extended version of the GeoJSON / Mapbox simplestyle spec. See docs/tutorials/geojson_style_spec.md for supported attributes.

Overpass API layers can be added to a map, allowing custom queries and display of OpenStreetMap data. See docs/tutorials/overpass_layers.md for details.

Android App / PWA

Mapforge is built as a Progressive Web App (PWA), see docs/tutorials/app.md.

An Android app that wraps the PWA is available in the Play Store: Mapforge Android App

---

Self‑Hosting

Container Image

The latest image is available from ghcr.io/mapforge-org/mapforge:main.

You can also build your own image locally from the repository with: podman build -t mapforge .

Required Services

Before running the application container, make sure MongoDB and Redis are running. For example with Podman:

podman run -d --name mongo \
  -v <local_dir>:/data/db:U,z \
  -p 27017:27017 \
  mongo:8.2

podman run -d --name redis \
  -p 6379:6379 \
  redis

Running Mapforge

A minimal example using the GitHub Container Registry image:

podman run \
  --name mapforge
  -e SECRET_KEY_BASE=e3c9f2... \
  -e DEVELOPER_LOGIN_ENABLED=true \
  --network=host \
  ghcr.io/mapforge-org/mapforge:main

To persist data like uploaded images in your storage, mount these to the container by adding to the podman command:

-v /path/on/host/maps:/rails/public/previews
-v /path/on/host/rails_storage:/rails/storage
-v /path/on/host/rack_cache:/rails/tmp/cache/rack

To enable geolocation-based centering of maps, mount the MaxMind GeoLite2 database:

podman run ... -v /path/on/host/GeoLite2-City.mmdb:/rails/db/GeoLite2-City.mmdb ...

Environment Variables

• SECRET_KEY_BASE — Rails secret key (must be set in production)
• DEVELOPER_LOGIN_ENABLED — optional local developer login (only enable this in test instances)
• HTTP_PORT — HTTP port inside the container (default: 3001 for thruster, 3000 for puma)
• SSL — set to true if your container is running behind a TLS terminating reverse proxy (default: true)
• MONGO_URL — MongoDB connection string (default: localhost:27017)
• MONGO_DB — MongoDB database name (default: 'mapforge_production')
• MONGO_USER, MONGO_PASSWORD — MongoDB credentials (optional; leave unset to connect without authentication)
• REDIS_URL — Redis URL for Action Cable (default: redis://localhost:6379/1)
• OPENROUTESERVICE_KEY — API key for routing features with openrouteservice.org
• INDOOREQUAL_KEY — API key for Indoorequal
• THUNDERFOREST_KEY — API key for Thunderforest maps
• PROTOMAPS_KEY — API key for Protomaps maps
• GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET — GitHub OAuth credentials
• GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET — Google OAuth credentials
• OSM_CLIENT_ID, OSM_CLIENT_SECRET — OSM OAuth credentials
• DEFAULT_MAP — default base map identifier (default: versatilesColorful)