Skip to main content

Search and navigation

Mapbox Atlas Search and Atlas Navigation allows you to deploy commercial-grade search and navigation on private, air gapped networks. It uses seven Docker containers, which can be deployed via either Docker Compose or Kubernetes.

  • atlas-router
  • atlas-core
  • atlas-backend
  • api-geocoder
  • atlas-navigation
  • atlas-memcached
  • atlas-redis

Docker Compose​

Dependencies​

To download and set up Atlas for Docker Compose, you need to download several dependencies first:

  • Docker
  • Docker Compose
  • wget
  • unzip
  • coreutils
  • pv (optional)

wget, pv, OpenSSL, and unzip are all dependencies of the Atlas installer. wget is used as the download manager for the installer's download command. pv provides user feedback during file operations. Docker and Docker Compose are used as the primary distribution and containerization strategy for Atlas. unzip extracts the installer download package. Mac users will need to install coreutils, which contains the realpath utility used by the Atlas installer for obtaining the pathname of the installation directory.

The installation process for these dependencies will vary depending on which operating system you are using. You may need to reboot after installing the dependencies.

Download the installer​

Documentation conventions
In this guide, we used atlas-installer as the installer name. Depending on which target OS you selected the installer will be named differently. To simplify the documentation, we will use atlas-installer for the rest of the documentation.
  1. Go to atlas.mapbox.com/install.
  2. Click the Download button for your operating system, either Linux or macOS.
  3. Unzip the downloaded zip file: unzip atlas-installer.zip.
  4. Make sure the binary is executable: chmod +x ./atlas-installer.

Download Atlas Search and Atlas Navigation​

Download Atlas Search and Atlas Navigation Docker images and data.

$./atlas-installer download <dir> \
    --token <your-atlas-token> \
    --version <v3-version> \
    --docker \
    --geocoding --navigation

Install Atlas Search and Atlas Navigation​

Run install.sh on the target host to set up Atlas Search and Atlas Navigation:

$./<dir>/install.sh <target>

Configure Atlas Search and Atlas Navigation​

Edit the config file in the installation directory. At a minimum, edit the following settings:

  • atlasLicense — your Atlas license
  • atlasURL — the URL where you will host Atlas Search and Navigation

Start and stop servers​

To start the servers:

$./atlas-v3.sh start

To stop the servers:

$./atlas-v3.sh stop

Disable unused services​

Both search (geocoding) and navigation are enabled by default. If you have only purchased Atlas Search or only purchased Atlas Navigation, you can disable the service you are not using.

$./atlas-v3.sh start --disable-geocoding
$./atlas-v3.sh start --disable-navigation

Check the current version​

To check the current version:

$./atlas-v3.sh version

Uninstall​

First, stop containers and drop Docker volumes:

$./atlas-v3.sh clean

Second, fully uninstall:

$./remove-v3.sh

Kubernetes​

Dependencies​

To download and set up Atlas for Kubernetes, you need to download several dependencies first:

  • Helm 3
  • jq
  • tar
  • If downloading data to transfer to an air-gapped network: curl, unzip, and docker

Add the Mapbox Helm repository​

You will need a Mapbox token with atlas:read scope to add the Mapbox Helm repository. See Access Token for instructions on how to create this token.

# Add the Mapbox Helm repository
$export MAPBOX_ACCESS_TOKEN=<your-atlas-sk-token>
$helm repo add mapbox "https://api.mapbox.com/v2/software/charts?access_token=$MAPBOX_ACCESS_TOKEN"

Get the Helm chart​

Atlas v3
For Atlas Search and Atlas Navigation, you should use v3.0.0 or higher of the mapbox/mapbox-atlas helm chart. For more information on earlier versions of Atlas, see Atlas v2 for Kubernetes.
# Pre-fetch the latest version of the chart
$helm fetch mapbox/mapbox-atlas

# or pre-fetch a specific version of the chart
$helm repo update
$helm search repo mapbox --versions --devel
$helm fetch mapbox/mapbox-atlas --version <chart version>

# Extract archived files
$tar -xvzf mapbox-atlas-<version>.tgz
$cd mapbox-atlas

# Fetch docker auth token (valid for 12 hours) and create regcred docker-registry secret
$chmod u+x ./atlas
$./atlas create_docker_secret

# Export your Atlas license to your environment
$eval $(./atlas export_license)

# Set password 
$./atlas set_redis_password <your-redis-password>

# Install the chart
$helm install atlas . \
    --set "atlasLicense=$ATLAS_LICENSE" \
    --set "global.atlasURL=<http[s]://external-hostname-for-Atlas>" \
    --set "global.platform=<minikube|eks|openshift|aks|other>"

Get the Helm chart and images for offline use​

Disabling unused services
Both search (geocoding) and navigation are enabled by default. If you have only purchased Atlas Search or only purchased Atlas Navigation, you should set geocoding=false or navigation=false before pulling or pushing images.

Atlas Search and Atlas Navigation​

# Pulls images into local Docker context
$./atlas pull_images

# Pushes images to custom Docker registry
$./atlas push_images <your-custom-registry.com>

# Pulls images and saves them to a tarball in the downloads/docker directory
$./atlas save_images

Atlas Search only​

# Pulls images into local Docker context
$navigation=false ./atlas pull_images

# Pushes images to custom Docker registry
$navigation=false ./atlas push_images <your-custom-registry.com>

# Pulls images and saves them to a tarball in the downloads/docker directory
$navigation=false ./atlas save_images

Atlas Navigation only​

# Pulls images into local Docker context
$geocoding=false ./atlas pull_images

# Pushes images to custom Docker registry
$geocoding=false ./atlas push_images <your-custom-registry.com>

# Pulls images and saves them to a tarball in the downloads/docker directory
$geocoding=false ./atlas save_images

For deployments on networks without internet access​

For deployments on networks without internet access, also download the geocoding and navigation data on the internet-connected machine before transferring to your air gapped environment:

$./atlas download_search_data
$./atlas download_navigation_data

Upgrade Atlas​

When a new version of Atlas for Kubernetes is available, download an updated Helm chart and pull new container images from the registry. Use Helm to automatically update the existing deployment. With Kubernetes, often you can apply rolling updates of Atlas without taking downtime. We always recommend that administrators create and test backups of their Atlas data, as well as running in a test environment, before deploying an upgrade to production.

$helm upgrade <your-release-name> .

Renew license​

First, get your updated license by running:

$eval $(./atlas export_license)

Then run the following upgrade command:

$helm upgrade <your-release-name> . --reuse-values --set atlasLicense=$ATLAS_LICENSE
Was this page helpful?