CoMaps Map Distributor

1. Use cases
   • Places with limited connectivity
   • Long-term archival
2. Installing this tool
3. Usage
4. Development

🗺️A small CLI tool to download and then serve map files for CoMaps via a local network.

There's also a small video showing how it works

Use cases

Since the v2025.12.19-11 Android release of CoMaps, the app allow specifying a remote-server to download maps that is not the default, CoMaps-run Content Delivery Network (CDN). So far, [the maps still need to be the "original" maps as created by the CoMaps team, as the apps validate the checksums, but there are already some interesting use cases.

Places with limited connectivity

A big class of use cases is getting people to install & use CoMaps when they are having a very limited or even no internet connection. As the Android APK file can be transferred to devices locally, so can now be the maps. For example, this can be useful if…

• …you are living in a household with multiple devices that use CoMaps and for which you want to download/update maps. So far, each device needed to download the maps from the internet, wasting bandwidth, time and potentially money if you're on metered connections. By using a custom, local map delivery server you just need to download the maps from the internet once.
• …you have friends, family or communities living in remote places with limited or even no connectivity to the internet. You can now deliver the app and all necessary maps from any laptop by opening a WiFi-hot spot to let folks download the maps.
• …you are being deployed in humanitarian situations in places that are disconnected from the internet. By bringing the APK and local maps, a single laptop can be used to rapidly deploy CoMaps & the maps to local teams.

Long-term archival

So far, older versions of CoMaps could no longer install the maps published along-side them, due to limited space on the CoMaps CDN. Which made long-term archival of older versions, e.g. for academic interest like in national archives or libraries problematic. Now you can archive older maps alongside the APK, and even still install it on devices.

Installing this tool

This tool is now on PyPI

To install it, you can run pip install comaps-map-distributor, once done the comaps-map-distributor will be available.

Alternatively, you can use uv or pipx:

• run pipx install comaps-map-distributor, then it'll be available as comaps-map-distributor as well, or…
• …run it directly via uvx comaps-map-distributor if you use uv

Usage

The main comaps-map-distributor has three main commands: download-maps, update-maps and serve-maps. While all have some optional parameters, you do not have to set-up anything, the map-download part can be used interactively and walks you through the process of downloading the maps you are interested in.

And the map-serving part doesn't need user input if started from the same current working directly that the download was initiated. It will automatically display the IP addresses that should be used in the CoMaps app, assuming the devices share a local network (e.g. Wifi)

• comaps-map-distributor download-maps does allow specifying map versions, allows selecting which maps to download, from which remote CoMaps CDN server and where to save them. If no parameters are given, the latest map version is downloaded from one of the existing CoMaps servers and saved in a default place.
• comaps-map-distributor update-maps tries to download the latest versions of all the maps that are locally present in the latest local version
• comaps-map-distributor serve-maps allows serving them over the local network with a very basic HTTP server, so that the CoMaps Android app can find and download them without requiring internet connectivity. If a non-standard folder is used for storing the maps, you can specify the correct map folder. Note: All files under that root folder will be served via the server, make sure to not include private files here.

All commands can be run with --help for further help.

Development

To develop locally, use uv for managing dependencies etc locally, e.g.:

git clone ssh://git@codeberg.org/gedankenstuecke/comaps-map-distributor.git && cd comaps-map-distributor
uv sync
uv run comaps-map-distributor

Docker

docker folder contains docker-compose.yml and dockerfile to run comaps-map-distributor in docker environment.

When run for first time, do not forget to enter the docker with command docker exec -it comaps-maps-updater bash then exex comaps-map-distributor download-maps to download the desired maps.

From there you don't have to do anything and the maps will be updated automatically every day (or according to the cron configuration you indicate in the docker compose file)

The docker compose file defines 2 containers, the one in charge of serving the maps and the one in charge of periodic updating (note that, for space efficiency, only the latest version of the maps is saved). You can delete this last container if you prefer to update manually.