Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



58 Commits

Repository files navigation


Light docker for ksomtik This docker is an alternative to the other kosmtik docker which is 2 times bigger. This image contains almost all kosmtik plugins.

Image name Image Size
joxit/kosmtik Image Size
kosmtik/kosmtik Image Size
nathancahill/kosmtik Image Size


Very lite but extendable mapping framework to create Mapnik ready maps with OpenStreetMap data (and more).

For now, only Carto based projects are supported (with .mml or .yml config), but in the future we hope to plug in MapCSS too.

Alpha version, installable only from source


Only the core needs:

  • project loading
  • local configuration management
  • tiles server for live feedback when coding
  • exports to common formats (Mapnik XML, PNG…)
  • hooks everywhere to make easy to extend it with plugins


Get the docker image

There are two versions, one image latest based on debian:stretch (testing) and the other jessie based on node:5-slim (debian jessie). The latest tag contains the latest version of kosmtik and jessie the latest mapnik version compatible with debian jessie.

You can get the image in three ways

From sources with this command :

git clone
docker build -t joxit/kosmtik docker-kosmtik
docker build -t joxit/kosmtik:jessie -f docker-kosmtik/Dockerfile.jessie docker-kosmtik

Or build with the url :

docker build -t joxit/kosmtik
docker build -t joxit/kosmtik -f Dockerfile.jessie

Or pull the image from docker hub :

docker pull joxit/kosmtik
docker pull joxit/kosmtik:jessie



First of all, you need a database with OSM datas. You can use a postgres database in a docker or on a computer. If you want your database to be in a docker, I suggest you to use openfirmware/postgres-osm docker.

In order to fill this database, you can use openfirmware/osm2pgsql. You can download a continent or country on or the whole planet on

Warning: in the case of a connection to a database on the host computer, you should not use in your style/localconfig but your private IP. In a docker corresponds to the container itself and not to your computer (unless you used --net host).


To run a Carto project (or .yml, .yaml):

docker run -d \
    -p 6789:6789 \
    -v /path/to/your/project:/opt/project \
    --link postgres-osm:postgres-osm \
    -e USER_ID=1000 \
    joxit/kosmtik \
    kosmtik serve </opt/project/project.(mml|yml)> --host

The env USER_ID is your user ID on your host. The shell kosmtik will perform a chown -R $USER_ID:$USER_ID /opt/project at the end of the import. Then open your browser at

Try it

You can try kosmtik with HDM CartoCSS project.

You can add an alias in your .bashrc or .bash_aliases for kosmtik serve. You can use KOSMTIK_OPTS env to add your own docker options for kosmtik (such as --link postgres-osm:postgres-osm or --net postgres-osm for networks).

alias kosmtik="docker run -ti --rm -p 6789:6789 -v $(pwd):/opt/project -e USER_ID=1000 $KOSMTIK_OPTS joxit/kosmtik kosmtik serve --host"

Or use the shell in tools (add the folder in your PATH var). If you are using serve command, the shell will add --host as arg.


This image has been designed to be as light as possible. Therefore, it contains no fonts. If you want to add custom fonts to your project, you can use Map { font-directory: url(./fonts); }. Otherwise, you can link all fonts from your host computer to the container using the -v /usr/share/fonts:/usr/share/fonts:ro option.

docker run -ti --rm -p 6789:6789 -v $(pwd):/opt/project -v /usr/share/fonts:/usr/share/fonts:ro -e USER_ID=1000 $KOSMTIK_OPTS joxit/kosmtik kosmtik serve --host


Tiles export

To export tiles from your project (see kosmtik-tiles-export plugin):

docker run -d \
    -v /path/to/your/project:/opt/project \
    --link postgres-osm:postgres-osm \
    -e USER_ID=1000 \
    joxit/kosmtik \
    kosmtik export /opt/project/project.(mml|yml) \
    --format tiles --output /opt/project/tiles --minZoom 1 --maxZoom 13

The env USER_ID is your user ID on your host. The shell kosmtik will perform a chown -R $USER_ID:$USER_ID /opt/project at the end of the import.

Fetch remote

Download the remote files referenced in your layers and update their name to use them automatically (see kosmtik-fetch-remote plugin). Kosmtik is launched as root in the docker, so fetched datas and tmp tiles will be owned by root. This is why you should use kosmtik cmd which will chown the curent directory (/opt/project) with your user id.


You can add an overlay key to your project.mml or your kosmtik config.yml files to override the behaviour (see kosmtik-overlay plugin). For example:

    url: 'http://{s}{z}/{x}/{y}.png'
    active: true
    opacity: 1
    position: -1
"overlay": {
    "url": "http://{s}{z}/{x}/{y}.png",
    "active": true,
    "opacity": 1,
    "position": -1

Overpass layer

Just add "type": "overpass" and a request key with your overpass query in your Carto layer. The plugin will run the queries, cache them on disk, and transform the layers in normal geojson layers (see kosmtik-overpass-layer pugin).

Map compare

You can add compareUrl key to your project.mml or your kosmtik config.yml files to set the default URL used (see kosmtik-map-compare plugin). Fallback to OSM default style. For example:

compareUrl: 'http://{s}{z}/{x}/{y}.png'
"compareUrl": "http://{s}{z}/{x}/{y}.png"

Place search

Add a search control (base on Photon) to your Kosmtik instance, you can use CTRL + F shortcut (see kosmtik-place-search plugin).

GeoJSON overlay

Show a geojson overlay on top of your Kosmtik map (see kosmtik-geojson-overlay).

Local config

Because you often need to change the project config to match your local env, for example to adapt the database connection credentials, kosmtik comes with an internal plugin to manage that. You have two options: with a json file named localconfig.json, or with a js module name localconfig.js.

Place your localconfig.js or localconfig.json file in the same directory as your carto project (or .yml, .yaml).

In both cases, the behaviour is the same, you create some rules to target the configuration and changes the values. Those rules are started by the keyword where, and you define which changes to apply using then keyword. You can also filter the targeted objects by using the if clause. See the examples below to get it working right now.

Example of a json file

        "where": "center",
        "then": [29.9377, -3.4216, 9]
        "where": "Layer",
        "if": {
            "Datasource.type": "postgis"
        "then": {
            "Datasource.dbname": "gis",
            "Datasource.password": "",
            "Datasource.user": "osm",
            "": "postgres-osm"
        "where": "Layer",
        "if": {
            "id": "hillshade"
        "then": {
            "Datasource.file": "/data/layers/hillshade.vrt"

Example of a js module

exports.LocalConfig = function (localizer, project) {
    localizer.where('center').then([29.9377, -3.4216, 9]);
    localizer.where('Layer').if({'Datasource.type': 'postgis'}).then({
        "Datasource.dbname": "gis",
        "Datasource.password": "",
        "Datasource.user": "osm",
        "": "postgres-osm"
    // You can also do it in pure JS
    project.mml.bounds = [1, 2, 3, 4];