[DOC] New documentation: Self-host maps server (#1625)
* Add new page self-host maps server Signed-off-by: vagimeli <vagimeli@amazon.com> * Added new content Signed-off-by: vagimeli <vagimeli@amazon.com> * Copy edit Signed-off-by: vagimeli <vagimeli@amazon.com> * Tech review edits Signed-off-by: vagimeli <vagimeli@amazon.com> * Doc review edits Signed-off-by: vagimeli <vagimeli@amazon.com> * Editorial review changes Signed-off-by: vagimeli <vagimeli@amazon.com> * Final edits Signed-off-by: vagimeli <vagimeli@amazon.com> Signed-off-by: vagimeli <vagimeli@amazon.com>
This commit is contained in:
Melissa Vagi
GitHub
parent
f9d7758ab3
commit
45b199cbc7
|
|
@ -0,0 +1,106 @@
|
|||
---
|
||||
layout: default
|
||||
title: Self-host maps server
|
||||
nav_order: 6
|
||||
---
|
||||
|
||||
# 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](https://hub.docker.com/u/opensearchproject).
|
||||
{: .note}
|
||||
|
||||
## Pull Docker image
|
||||
|
||||
Open your terminal and run the following command:
|
||||
|
||||
`docker pull opensearch/opensearch-maps-server`
|
||||
|
||||
## Set 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).
|
||||
{: .note}
|
||||
|
||||
```
|
||||
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](https://github.com/opensearch-project/maps/tree/main/tiles-generation/cdk) and then use the tiles set absolute path to create a volume to start the server.
|
||||
|
||||
## Start 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/`
|
||||
|
||||
## Use the self-host maps server with OpenSearch Dashboards
|
||||
|
||||
You can use the self-host maps server with OpenSearch Dashboards by either adding the parameter to `opensearch_dashboards.yml` or configuring the default WMS properties in OpenSearch Dashboards.
|
||||
|
||||
### Option 1: Configure opensearch_dashboards.yml
|
||||
|
||||
Configure the manifest URL in `opensearch_dashboards.yml`:
|
||||
|
||||
`map.opensearchManifestServiceUrl: "http://localhost:8080/manifest.json"`
|
||||
|
||||
### Option 2: Configure Default WMS properties in OpenSearch Dashboards
|
||||
|
||||
1. On the OpenSearch Dashboards console, select **Stack Management > Advanced Settings**.
|
||||
2. Locate `visualization:tileMap:WMSdefaults` under **Default WMS properties**.
|
||||
3. Change `"enabled": false` to `"enabled": true` and add the URL for the valid map server.
|
||||
|
||||
## Licenses
|
||||
|
||||
Tiles are generated per [Terms of Use for Natural Earth vector map data](https://www.naturalearthdata.com/about/terms-of-use/) and [Copyright and License for OpenStreetMap](https://www.openstreetmap.org/copyright).
|
||||
|
||||
## Related links
|
||||
|
||||
* [Configure WMS map server]({{site.url}}{{site.baseurl}}/dashboards/maptiles/)
|
||||
* [Region map visualizations]({{site.url}}{{site.baseurl}}/dashboards/geojson-regionmaps/)
|
||||
Loading…
Reference in New Issue