This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Using the self-host maps server

The self-host maps server for OpenSearch Dashboards allows users to access the default maps service in air-gapped environments. OpenSearch-compatible map URLs include a map manifest with map tiles and vectors, the map tiles, and the map vectors.

The following sections provide steps for setting up and using the self-host maps server with OpenSearch Dashboards.

You can access the maps-server image via the official OpenSearch Docker Hub repository.

Pulling the Docker image

Open your terminal and run the following command:

docker pull opensearch/opensearch-maps-server

Setting up the server

You must set up the map tiles before running the server. You have two setup options: Use the OpenSearch-provided maps service tiles set, or generate the raster tiles set.

Option 1: Use the OpenSearch-provided maps service tiles set

Create a Docker volume to hold the tiles set:

docker volume create tiles-data

Download the tiles set from the OpenSearch maps service. Two planet tiles sets are available based on the desired zoom level:

Zoom Level 8 (https://maps.opensearch.org/offline/planet-osm-default-z0-z8.tar.gz)
Zoom level 10 (https://maps.opensearch.org/offline/planet-osm-default-z0-z10.tar.gz)

The planet tiles set for zoom level 10 (2 GB compressed/6.8 GB uncompressed) is approximately 10 times larger than the set for zoom level 8 (225 MB compressed/519 MB uncompressed).

docker run \
    -e DOWNLOAD_TILES=https://maps.opensearch.org/offline/planet-osm-default-z0-z8.tar.gz \
    -v tiles-data:/usr/src/app/public/tiles/data/ \
    opensearch/opensearch-maps-server \
    import

Option 2: Generate the raster tiles set

To generate the raster tiles set, use the raster tile generation pipeline and then use the tiles set absolute path to create a volume to start the server.

Starting the server

Use the following command to start the server using the Docker volume tiles-data. The following command is an example using host URL “localhost” and port “8080”:

docker run \
    -v tiles-data:/usr/src/app/public/tiles/data/ \
    -e HOST_URL='http://localhost' \
    -p 8080:8080 \
    opensearch/opensearch-maps-server \
    run

Or, if you generated the raster tiles set, run the server using that tiles set:

docker run \
    -v /absolute/path/to/tiles/:/usr/src/app/dist/public/tiles/data/ \
    -p 8080:8080 \
    opensearch/opensearch-maps-server \
    run

To access the tiles set, open the URLs in a browser on the host or use the curl command curl http://localhost:8080/manifest.json.

Confirm the server is running by opening each of the following links in a browser on your host or with a curl command (for example, curl http://localhost:8080/manifest.json).

Map manifest URL: http://localhost:8080/manifest.json
Map tiles URL: http://localhost:8080/tiles/data/{z}/{x}/{y}.png
Map tiles demo URL: http://localhost:8080/