> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ja/atlas/llms.txt)

# 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](#docker-compose) or [Kubernetes](#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

> **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 Atlas Search and Atlas Navigation

Download Atlas Search and Atlas Navigation Docker images and data.

```bash
$ ./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:

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

### Configure Atlas Search and Atlas Navigation

Edit the [`config` file](https://docs.mapbox.com/ja/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

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.

```bash
$ ./atlas-v3.sh start --disable-geocoding
$ ./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

### 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/ja/atlas/guides/#access-token) for instructions on how to create this token.

```bash
# 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

> **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/ja/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 <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

> **Note (warning): 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
$ ./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.

```bash
$ helm upgrade <your-release-name> .
```

### Renew license

First, get your updated license by running:

```bash
$ eval $(./atlas export_license)
```

Then run the following upgrade command:

```bash
$ helm upgrade <your-release-name> . --reuse-values --set atlasLicense=$ATLAS_LICENSE
```