Connect to Elastic Maps Service

Elastic Maps Service (EMS) is a service that hosts tile layers and vector shapes of administrative boundaries. If you are using Kibana’s out-of-the-box settings, Maps is already configured to use EMS.

EMS requests are made to the following domains:

Maps makes requests directly from the browser to EMS.

You might experience EMS connection issues if your Kibana server or browser are on a private network or behind a firewall. If this happens, you can disable the EMS connection to avoid unnecessary EMS requests.

To disable EMS, change your kibana.yml file.

If you cannot connect to Elastic Maps Service from the Kibana server or browser clients, and your cluster has the appropriate license level, you can opt to host the service on your own infrastructure.

Elastic Maps Server is a self-managed version of Elastic Maps Service offered as a Docker image that provides both the EMS basemaps and EMS boundaries. The image is bundled with basemaps up to zoom level 8. After connecting it to your Elasticsearch cluster for license validation, you have the option to download and configure a more detailed basemaps database.

You can use docker pull to download the Elastic Maps Server image from the Elastic Docker registry.

docker pull docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8:8.7.1

Start Elastic Maps Server and expose the default port 8080:

docker run --rm --init --publish 8080:8080 \
  docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8:8.7.1

Once Elastic Maps Server is running, follow instructions from the webpage at localhost:8080 to define a configuration file and optionally download a more detailed basemaps database.

Elastic Maps Server reads properties from a configuration file in YAML format that is validated on startup. The location of this file is provided by the EMS_PATH_CONF container environment variable and defaults to /usr/src/app/server/config/elastic-maps-server.yml. This environment variable can be changed by making use of the -e docker flag of the start command.

General settings

Elasticsearch connection and security settings

Server security settings

One way to configure Elastic Maps Server is to provide elastic-maps-server.yml via bind-mounting. With docker-compose, the bind-mount can be specified like this:

version: '2'
services:
  Elastic Maps Server:
    image: docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8:8.7.1
    volumes:
      - ./elastic-maps-server.yml:/usr/src/app/server/config/elastic-maps-server.yml

All configuration settings can be overridden by environment variables that are named with all uppercase letters and by replacing YAML periods with underscores. For example elasticsearch.ssl.certificate could be overridden by the environment variable ELASTICSEARCH_SSL_CERTIFICATE. Boolean variables must use the true or false strings.

These variables can be set with docker-compose like this:

version: '2'
services:
  Elastic Maps Server:
    image: docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8:8.7.1
    environment:
      ELASTICSEARCH_HOST: http://elasticsearch.example.org
      ELASTICSEARCH_USERNAME: 'ems'
      ELASTICSEARCH_PASSWORD: 'changeme'

Elastic Maps Server hosts vector layer boundaries and vector tile basemaps for the entire planet. Boundaries include world countries, global administrative regions, and specific country regions. Basemaps up to zoom level 8 are bundled in the Docker image. These basemaps are sufficient for maps and dashboards at the country level. To present maps with higher detail, follow the instructions of the front page to download and configure the appropriate basemaps database. The most detailed basemaps at zoom level 14 are good for street level maps, but require ~90GB of disk space.

With Elastic Maps Server running, add the map.emsUrl configuration key in your kibana.yml file pointing to the root of the service. This setting will point Kibana to request EMS basemaps and boundaries from Elastic Maps Server. Typically this will be the URL to the host and port of Elastic Maps Server. For example, map.emsUrl: https://my-ems-server:8080.

Elastic Maps Server periodically runs a status check that is exposed in three different forms:

Logs are generated in ECS JSON format and emitted to the standard output and to /var/log/elastic-maps-server/elastic-maps-server.log. The server won’t rotate the logs automatically but the logrotate tool is installed in the image. Mount /dev/null to the default log path if you want to disable the output to that file.