uMap Review: Self-Hosted OpenStreetMap Map Publishing

What uMap Solves

uMap addresses a specific publishing problem: creating a map that uses OpenStreetMap layers and making that map available on another website. It is intended for people and organizations that need an interactive map without assembling a complete geospatial publishing system from separate components. The repository description names OpenStreetMap layers, website embedding, and quick map creation as the central use cases.

The project is not presented as a replacement for OpenStreetMap itself. OpenStreetMap supplies the map ecosystem and layer data, while uMap supplies an application for composing and publishing a map. That distinction matters when selecting the tool. A user who only needs a tile viewer may not need uMap's editing and backend storage features. A site that needs to maintain its own points, lines, polygons, and map settings is a more relevant user.

The repository topics include `cartography`, `geojson`, `gpx`, `map`, and `openstreetmap`. Those topics support a workflow that combines geographic data formats with interactive web mapping. The README does not document a complete list of supported import and export operations, so the exact data workflow should be confirmed in the technical documentation before choosing uMap for a production publishing pipeline.

Django and Leaflet Architecture

The README states that uMap is built on top of Django and Leaflet. Django provides the server-side application structure, while Leaflet supplies browser-based mapping components. The JavaScript package metadata describes the package as managing maps and features with Leaflet and exposing them for backend storage through an API.

The repository layout supports that division. The `umap/` directory contains the application, `manage.py` follows Django's management-command convention, and `package.json` defines JavaScript dependencies and scripts. The package includes Leaflet 1.9.4 and several plugins used for editing, measurement, clustering, map controls, and geographic data handling. It also includes libraries connected with GeoJSON, GPX, KML, and CSV conversion.

This structure indicates that uMap is more than a static map template. A browser session presents the map and its feature editing interface, while the Django application stores map information and exposes it for retrieval. The repository files do not include the complete URL or API documentation, so the precise public endpoints, authentication behavior, and embed syntax remain unconfirmed. The technical documentation linked by the README is the correct place to verify those details.

Docker and PostGIS Deployment

The repository provides a container-oriented deployment example. Its `docker-compose.yml` defines an `app` service, a PostgreSQL PostGIS database, a Redis service, and an Nginx proxy. The proxy publishes port `8000` to port `80`, while the application receives storage, database, authentication, realtime, and site URL settings through environment variables.

The Compose file is useful for understanding the intended service boundaries. The database service uses `postgis/postgis:14-3.3-alpine`, and the application environment includes `DATABASE_URL`, `SECRET_KEY`, `SITE_URL`, `UMAP_ALLOW_ANONYMOUS`, `DEBUG`, `REALTIME_ENABLED`, and `REDIS_URL`. Uploads and static files are stored in named volumes. Redis is marked as useful for real-time collaboration in the file comments, so it is part of the example deployment even though the README does not describe the collaboration feature in detail.

The Compose file references `docker.io/umap/umap:3.6.1`, while recent releases include 3.8.1, 3.8.0, and 3.7.3. That difference is a concrete configuration issue for adopters. The file should be reviewed before use, especially when selecting an image tag that matches the application version being deployed.

Installing uMap for a First Map

The repository contains a Docker installation path, but the README does not give a short standalone installation command. For a first local deployment, the documented repository assets are the `Dockerfile` and `docker-compose.yml`. The Compose example is not presented as a complete production guide, so its sample secret, `DEBUG` setting, anonymous access setting, and image tag should not be carried into production unchanged.

After placing the repository locally, a developer can inspect the Compose file before starting the services. The file exposes the proxy on host port `8000`, so the intended local entry point is the configured proxy rather than a direct application port. The README directs users to `https://umap-project.org` for an introduction and `https://docs.umap-project.org/` for technical information.

A first real use would involve starting the deployment described by the repository, creating a map through the uMap interface, and using the publication or embedding control that the interface provides. The README does not document the exact button labels, generated iframe snippet, or default permissions. Those details should be taken from the linked documentation and checked against the target website.

JavaScript Dependencies and Data Handling

The JavaScript package includes several packages that indicate the kinds of map operations uMap is designed to support. `@tmcw/togeojson` is listed for geographic data conversion, while `@zumer/snapdom` is present for capturing rendered page content. `@turf/turf`, `csv2geojson`, `georsstogeojson`, and `dompurify` are also listed. The dependency list includes Leaflet plugins for editing, fullscreen display, locating, measurement, minimaps, and marker clustering.

This package set suggests that uMap can handle more than plain marker placement. It includes capabilities associated with importing or converting geographic formats, editing features on a map, and managing display behavior. However, dependency names alone do not establish which formats are exposed in the current user interface, whether every conversion is supported for import or only export, or what validation rules apply.

The JavaScript package version is `1.0.0-alpha.1`, although the Python project uses a dynamic version and the repository has application releases such as 3.8.1. The two version numbers appear to describe different package layers rather than a single release coordinate. Engineers should avoid assuming that the JavaScript package version and the uMap application release are interchangeable.

Maintenance, Upgrades, and License

The repository is not archived, and the last push was on 2026-10-03. Recent releases include 3.8.1 on 2026-08-19, 3.8.0 on 2026-08-18, and 3.7.3 on 2026-04-08. This indicates recent project activity, but the README does not provide a detailed upgrade procedure. The actual migration steps, compatibility requirements, and release notes should be checked for the specific version being adopted.

The Python project metadata requires Python `>=3.12`. The Dockerfile uses `python:3.12-slim`, and the project dependencies include Django `>=5.1`, Pillow, psycopg, requests, and several Django integrations. Upgrading affects both the Python environment and services such as PostgreSQL/PostGIS, Redis, static assets, uploads, and the reverse proxy. Database migrations and configuration compatibility are not explained in the README excerpt.

The repository license is reported as a custom license that GitHub cannot classify, and the project includes a `LICENSE` file. The `package.json` metadata separately contains `"license": "AGPLv3"`. This discrepancy requires direct review of the license texts and packaging metadata before adoption. The repository description does not provide enough information to determine how the custom license applies to every deployment or embedded component.

Alternatives and Trade-offs

The direct alternative approach is to publish a static web map with Leaflet and an OpenStreetMap layer, then place the map markup directly on a site. That approach can reduce server-side complexity because the page does not need a Django-backed map management service. It is different from uMap's application model: static Leaflet code makes the page and its feature data part of the site's own build, while uMap provides a backend for creating and storing maps.

Another alternative is to use a hosted mapping or content platform that handles map publishing outside the operator's infrastructure. The tradeoff is ownership and operational control. A self-hosted uMap deployment uses the repository's Django, database, storage, and proxy components, which increases the number of moving parts. A hosted service can reduce infrastructure work, but the repository does not establish its features, licensing, or data-handling terms.

uMap is the wrong choice when the requirement is only a fixed map embedded in one page, especially if the project has no need for editable features or a shared map-management interface. It is also a poor fit for teams unwilling to maintain Python, PostGIS, Redis when realtime features are enabled, and web server configuration.

Editorial conclusion

uMap is a practical choice for organizations that need an editable OpenStreetMap map service with self-hosted deployment and website embedding. It is less suitable for teams requiring a documented, minimal installation command or a clearly aligned license record across repository metadata. Before adoption, inspect the `LICENSE` file, verify the deployment configuration, and confirm that the generated map URL and embedding behavior meet the target site's requirements.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. umap-project/umap on GitHub