> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/atlas/llms.txt) # 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** ### 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 > **Note: 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](https://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 the installer Download the installer for Docker images and data. ```text $ ./atlas-installer download --token --version --docker --search ``` #### Install dependencies Run `install.sh` on the target host to set up Atlas Search and/or Atlas Navigation: ```bash $ .//install.sh ``` #### Configure dependencies Edit the [`config` file](https://docs.mapbox.com/atlas/v2/guides/docker-compose/#configure-atlas) 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: ```bash $ ./atlas-v3.sh start ``` To stop the servers: ```bash $ ./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: ```text bash $ ./atlas-v3.sh start --disable-navigation ``` #### Check the current version To check the current version: ```bash $ ./atlas-v3.sh version ``` #### Uninstall First, stop containers and drop Docker volumes: ```bash $ ./atlas-v3.sh clean ``` Second, fully uninstall: ```bash $ ./remove-v3.sh ``` **Kubernetes** ### 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](https://docs.mapbox.com/atlas/guides/#access-token) for instructions on how to create this token. ```bash # Add the Mapbox Helm repository $ export MAPBOX_ACCESS_TOKEN= $ helm repo add mapbox "https://api.mapbox.com/v2/software/charts?access_token=$MAPBOX_ACCESS_TOKEN" ``` #### Get the Helm chart > **Note (warning): 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](https://docs.mapbox.com/atlas/v2/guides/kubernetes/). ```bash # 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 # Extract archived files $ tar -xvzf mapbox-atlas-.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 # Install the chart $ helm install atlas . \ --set "atlasLicense=$ATLAS_LICENSE" \ --set "global.atlasURL=" \ --set "global.platform=" ``` #### 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. ```text # Pulls images into local Docker context $ navigation=false ./atlas pull_images # Pushes images to custom Docker registry $ navigation=false ./atlas push_images # 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: ```text $ ./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. ```bash $ helm upgrade . ``` #### Renew license First, get your updated license by running: ```bash $ eval $(./atlas export_license) ``` Then run the following upgrade command: ```bash $ helm upgrade . --reuse-values --set atlasLicense=$ATLAS_LICENSE ```