Atlas Search
Mapbox Atlas Search lets you run Mapbox's location search technology — the same capabilities behind the Geocoding and Search Box APIs — entirely within your own private, air-gapped network. With Atlas Search, you can use forward and reverse geocoding, power address and place autocomplete, and search for points of interest, all without your location data ever leaving your infrastructure. This guide walks you through installing Atlas Search in your project so you can deploy commercial-grade location search infrastructure on infrastructure you control.
Install Atlas Search
You can install Atlas Search with Docker Compose or Kubernetes:
Docker Compose
Dependencies
To download and set up Atlas for Docker Compose, you need to download several dependencies first:
- Docker
- Docker Compose
wgetunzipcoreutilspv(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
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.- Go to atlas.mapbox.com/install.
- Click the Download button for your operating system, either Linux or macOS.
- Unzip the downloaded zip file:
unzip atlas-installer.zip. - Make sure the binary is executable:
chmod +x ./atlas-installer.
Download the installer
Download the installer for Docker images and data.
$./atlas-installer download <dir> --token <your-atlas-token> --version <v3-version> --docker --search
Install dependencies
Run install.sh on the target host to set up Atlas Search and/or Atlas Navigation:
$./<dir>/install.sh <target>
Configure dependencies
Edit the config file in the installation directory. At a minimum, edit the following settings:
atlasLicense— your Atlas licenseatlasURL— 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
If you are not planning to use Atlas Navigation in your implementation, disable the service by calling this command:
bash
$./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
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
Both search (geocoding) and navigation are enabled by default. If you have only purchased Atlas Search, you should set navigation=false before pulling or pushing images.
# 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
For deployments on networks without internet access
For deployments on networks without internet access, also download the $geocoding data on the internet-connected machine before transferring to your air gapped environment:
$./atlas download_search_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