This guide will walk you through the following components of the Atlas installation:
- Downloading the installer.
- Creating a Mapbox access token with an
- Using the installer to download and install Atlas.
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.
Learn how to install and run Atlas on your local computer.
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.
Below are approximate sizes for each tileset. Exact tileset file sizes are subject to change with new data from weekly updates.
|Terrain-v2||1 GB||40 GB|
|Streets-v7||300 MB||125 GB|
|Satellite||1 GB||275 GB|
|Boundaries||Not Available||15 GB|
|Search||5 GB||90 GB|
|Total||8 GB||545 GB|
In total, Docker images are about 10 GB.
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.
Before proceeding, make sure your machine has all the necessary dependencies:
- Docker Compose
- OpenSSL (optional)
- Go to atlas.mapbox.com/install.
- Click the Download button for your operating system, either Linux or macOS.
- Unzip the downloaded zip file:
- Make sure the binary is executable:
chmod +x ./atlas-installer.
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.
- Go to the Mapbox access token page.
- Click on + Create a token.
- Give the new token a name like "Atlas Server".
- Uncheck all the default public scopes.
- Under Secret scopes, check the Atlas:Read scope.
- Click Create token.
- 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.
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.
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
- 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
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.
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
The following outlines the steps to manually install Atlas using the
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
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.
$ ./atlas-installer download <destination> --token <your-atlas-token> [options]
<destination>(required): The directory where the downloaded files will be saved.
--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
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
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
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
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
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 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.
$ ./atlas-installer setup <source> <target>
<source>(required): The directory that contains all the files downloaded with the
<target>(required): The directory where Atlas will be installed on the host.
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 version
$ ./atlas-installer list --token <your-atlas-token>
--token <token>(required): A Mapbox access token with
Once you have found the version of Atlas you would like to install, run the download command and specify the
$ ./atlas-installer download atlas-server-files/ --version <your-atlas-version> --token <your-atlas-token> --dev
|Yes||Downloads Atlas resources.|
|Yes||Configure your download and/or installation through a series of prompts.|
|Yes||List downloadable Atlas versions.|
|No||Uninstall Atlas or parts of Atlas.|
|No||Install Atlas using cached resources.|
Do you plan to run Atlas on this machine?
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
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?
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?
yes if you want to download development datasets.
Where do you plan to install Atlas?
Only asked if installing Atlas on the same machine.
atlas-server. Enter the name of the directory you wish to install Atlas. The installer will create this directory for you.