Install Atlas

This guide will walk you through the following components of the Atlas installation:

  • Downloading the installer.
  • Creating a Mapbox access token with an atlas:read scope.
  • Using the installer to download and install Atlas.
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.

Some examples use <angle-brackets> as a convention to show places where you will need to specify your own details. The examples in this guide also use atlas-server-files for the download destination and atlas-server as an install target. Change the destination and target directory name with the ones you choose to use.

Play
video
How to install Mapbox Atlas

Learn how to install and run Atlas on your local computer.

Check prerequisites

To download Atlas, your system must have at least enough disk space for the Docker images and tilesets. The disk space requirements will be different depending on whether you download the development or production tilesets.

Tileset size

Below are approximate sizes for each tileset. Exact tileset file sizes are subject to change with new data from weekly updates.

DatasetDevProduction
Terrain-v21 GB40 GB
Streets-v7300 MB125 GB
Satellite1 GB275 GB
BoundariesNot Available15 GB
Search5 GB90 GB
Total8 GB545 GB

Docker images

In total, Docker images are about 10 GB.

Total disk space recommendations

Because installation maintains two copies of your data, we recommend hosting Atlas on a server with double the disk space that the data will require. If you are downloading full production tilesets and geocoding data, our recommendation is to host Atlas on a server with at least 1.5 TB of disk space.

Dependencies

Before proceeding, make sure your machine has all the necessary dependencies:

  • Docker
  • Docker Compose
  • OpenSSL (optional)
  • pv
  • python
  • unzip
  • wget

Download the installer

  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.

Create a Mapbox access token

Once you have downloaded the Atlas installer, the next step is to create a Mapbox token with atlas:read scope. This token will be required by the download command. You will create this token using the Mapbox account with which your Atlas license is associated.

  1. Go to the Mapbox access token page.
  2. Click on + Create a token.
  3. Give the new token a name like "Atlas Server".
  4. Uncheck all the default public scopes.
  5. Under Secret scopes, check the Atlas:Read scope.
  6. Click Create token.
  7. Save your new Atlas token in a secure place. Once you leave the Access Tokens page, you will not have access to this token again. Do not commit the Atlas token to GitHub or share it with anyone outside of your organization.

Wizard installation method

The Atlas installer is a command line interface (CLI) utility used to download and setup Atlas. The installer has been specifically designed for air-gapped environments where the host computer does not have access to the internet.

Note

This documentation refers to version 1.5.0 of the Atlas installer. If you have an older version of the installer, you need to download the latest version before continuing.

We recommend using the install command. This command will prompt you through a series of questions to configure your setup, execute download to download your Atlas data, then run setup if you've specified that you're installing Atlas on the same machine. To start the installation process run:

$ ./atlas-installer install

Before starting the installation process, be prepared with the following information:

  • Whether you plan to run Atlas on the same machine you are running the install command on.
  • Which version of Atlas you want to download.
  • What data you would like to download including development data.

For a full reference of the prompts you will see when running install, see Installer prompts reference

Install Atlas on the same machine

If you are running this command on the machine you will be installing Atlas on, you should also be prepared with the following information:

  • If you are upgrading an existing Atlas installation.
  • If you plan to run Atlas on HTTPS.
  • If you have an SSL certificate. If yes, where it is located.
  • The path where you would like to install Atlas.
  • Your Atlas server hostname, port, and a password.

After you have answered all the prompts, the installer will download all the Atlas files you specified and put them in a directory named atlas-server-files. If you are installing Atlas on the same machine (answered yes to the first prompt), the installer will run the setup command and configure your installation based on the information passed in to the wizard. Once complete, you can skip to the run Atlas section.

Install Atlas on a different machine

If you are planning to install Atlas on a different machine (for example, a machine without internet connection), you should only run install to download Atlas. You will then need to run setup on the machine you plan to use Atlas on.

To do this, answer no to the first prompt if you plan to run Atlas on a different machine, or if you are running Atlas in an air-gapped environment. If answered no to the first prompt, the installer wizard will only ask you the questions needed to downloaded data. Once the installer has finished downloading data, you will need to copy the downloaded files along with the installer and run the setup command.

Manual installation method

The following outlines the steps to manually install Atlas using the download and setup commands.

We recommend using the installer wizard for a better install experience. If you ran the install command but are installing Atlas on a different machine (for example, an offline server), you should copy the atlas-installer along with the downloaded files in your atlas-server-files directory to the new location and run the setup command.

Download Docker images, tilesets, and data

The download command will download the files required to a directory to be used by the setup command. These two steps are separated to enable an offline installation.

Usage

$ ./atlas-installer download <destination> --token <your-atlas-token> [options]

Positional Arguments

  • <destination> (required): The directory where the downloaded files will be saved.

Options

  --token, -t    Mapbox secret access token with "atlas:read" scope, e.g "sk.abc123"
  --version, -v  Version of Atlas to download.
  --docker       Download docker images.
  --dev          Download development data where possible.
  --tilesets     Specify which production tilesets to download

  --geocoding    Download geocoding data.
  --boundaries   Download boundaries tilesets.
  --no-tileset-checksums, -s  Skip checksum calculation for tileset downloads.
  --help         Show help

If no flags are passed in to the download command nothing will be downloaded. Depending on your selections, geographic region, and available bandwidth this step can be time consuming. All files must be downloaded before proceeding to the setup command.

Downloading development data

If you are testing or evaluating Atlas, we recommend that you execute the download command with the --dev flag to test your Atlas configuration without committing to downloading the full set of production tilesets. These are low-zoom (z0-8) versions of the Mapbox Streets, Satellite, and Terrain tilesets that you can use for testing.

$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --dev --docker --tilesets

Downloading a specific version of Atlas

By default, the download command will download the latest release of Atlas. You can use the list command to see the list of Atlas versions that are available to download. For more information on the list command, see the List available Atlas versions section. If you require an Atlas version older than 2.6.0, contact Mapbox support for help.

For example, to download v2.6.0 of Atlas, you would run:

$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --version v2.6.0 --docker

Downloading specific tilesets

If you only need to download a single tileset, you can limit the tilesets downloaded with the --tilesets flag. In this example only the development version of streets is downloaded:

$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --dev --tilesets streets

Downloading only Docker images

To only download Docker images (e.g., to upgrade Atlas without replacing data), you would run:

$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --docker
Atlas Upgrades

The setup command cannot execute with multiple versions of Atlas docker images in the download cache. In an upgrade scenario remove any existing docker images from <atlas-server-files>/docker/ before executing download to get a newer version of Atlas.

Setup Atlas

Execute the setup command on the server where Atlas will be hosted. The files downloaded from the download command and the installer should be moved to the Atlas host machine. When the setup command runs all the files from the source directory are copied into the target directory and Docker images are loaded into the Docker context. The setup command does not change the downloaded data, enabling the setup command to be executed repeatedly.

Usage

$ ./atlas-installer setup <source> <target>

Positional Arguments

  • <source> (required): The directory that contains all the files downloaded with the download command.
  • <target> (required): The directory where Atlas will be installed on the host.

List available Atlas versions

The list command lists of all downloadable Atlas versions.

You can determine the version of Atlas you have installed by listing the files in <atlas-server>/docker directory. You will find the version of Atlas in the docker tarballs.

api-accounts-e06eaabc6c743f6d4d2810342eccef1c097f6a2d-v2.4.0.tar.gz --> Atlas version 2.4.0

You can also get your version from the atlas.sh script:

$ ./atlas.sh version

Usage

$ ./atlas-installer list --token <your-atlas-token>

Options

  • --token <token> (required): A Mapbox access token with atlas:read scope.

Once you have found the version of Atlas you would like to install, run the download command and specify the --version.

$ ./atlas-installer download atlas-server-files/ --version <your-atlas-version> --token <your-atlas-token> --dev

Reference

Commands

CommandRequires InternetDescription
downloadYesDownloads Atlas resources.
installYesConfigure your download and/or installation through a series of prompts.
listYesList downloadable Atlas versions.
removeNoUninstall Atlas or parts of Atlas.
setupNoInstall Atlas using cached resources.

Installer prompts reference

Do you plan to run Atlas on this machine?

Defaults to yes. Select no if you only want to download dependencies.

Enter your sk token with atlas:read scope

Copy and paste your secret token you created on mapbox.com with atlas:read scope.

Which Atlas version would you like to download?

You will be presented with a drop down menu of available versions to download. The first version listed is the latest stable version. Use your arrow keys to select a different version, and press <enter> to continue.

What data would you like to download?

By default, Docker images, mapbox-streets-v7, and Geocoding data are selected as options. Use your arrow keys to navigate the options. You can press <space> to select, <a> to toggle all, or <i> to invert selection.

Would you like to download development data where possible?

Defaults to no. Select yes if you want to download development datasets.

Where do you plan to install Atlas?

Only asked if installing Atlas on the same machine.

Defaults to atlas-server. Enter the name of the directory you wish to install Atlas. The installer will create this directory for you.

Was this page helpful?