Install Atlas

You'll need four parts to install Atlas on your machine. This guide will walk you through each of the following pieces:

  • Make sure your machine meets all prerequisites.
  • The installer, which can be downloaded from studio.mapbox.com/atlas.
  • A Mapbox access token with an atlas:read scope.
  • An installation method for downloading, installing, and configuring 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.

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:

DataDevelopment tilesetsProduction tilesets
Maps2 GB410 GB
Geocoding245 MB70 GB

Tileset size

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

TilesetDevProduction
mapbox.mapbox-terrain-v2450 MB40 GB
mapbox.mapbox-streets-v7300 MB100 GB
mapbox.satellite-full850 MB260 GB
mapbox.satellite-watermark140 MB7 GB
Total1.75 GB407 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 1000 GB of disk space.

Check dependencies

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

  • wget
  • OpenSSL (optional)
  • Docker
  • Docker Compose
  • unzip (Atlas Search)
  • pv

Download the installer

  1. Go to studio.mapbox.com/atlas.
  2. Click the Download button for your operating system, either Linux or macOS.
  3. Unzip the downloaded zip file: unzip atlas-installer.zip.
  4. Give execute permission on the installer 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.

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.3.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 or not you plan to run Atlas on the same machine you are running the install command on.
  • Which version of Atlas you want to download (defaults to the most recent version).
  • 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 dependencies (Docker images, tilesets, geocoding data) 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 proceed with the setup command.

Download Docker images, tilesets, and data

If you do not want to use the installer wizard, you can download Atlas data manually using the download command. You will need to be connected to the internet to run this command.

Usage

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

Arguments

  • <destination> (required): The directory where the downloaded files will be saved. Must be on the same computer as the Atlas installer.

Options

  • --token, -t <token> (required): A Mapbox access token with atlas:read scope.
  • --dev (optional): Download only development tilesets. Recommended if you are testing or evaluating Atlas.
  • --version, -v (optional): Version of Atlas to download. Default is the latest version.
  • --tilesets <streets | terrain | satellite | all | none> (optional): Specify which production tilesets to download. Defaults to all.
  • --dev-tilesets <streets | terrain | satellite | all | none> (optional): Specify which development tilesets to download. Defaults to none.
  • --no-geocoding (optional): Do not download geocoding data.
  • --dev-geocoding (optional): Download development geocoding data (includes country-level data).
  • --enterprise-boundaries <all | admin | postal | stats | none> (optional): Download enterprise boundaries tilesets. Defaults to all.
  • --no-progress (optional): Disable progress bar indicator.

Deprecated:

  • --data, -d <tilesets | docker | geocoding | all> (optional): Choose to download only tilesets, only Docker images, only geocoding data, or all data. Defaults to all. You will only be able to download geocoding data if you purchased Atlas Search.

If no flags are passed in to the Installer, the latest Atlas version along with production tilesets, production geocoding data (if purchased), and Enterprise Boundaries data (if purchased) will be downloaded.

This command will take a while to complete. You will see the message "Tilesets downloads completed" once the download is finished. You will not be able to move on to the setup step until the download command is finished.

Downloading development data

If you are testing or evaluating Atlas, we recommend that you download the development tilesets using --dev 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, Satellites, and Terrain tilesets that you can use for testing. Once you have confirmed that the development tilesets work on your system, you can download the full set of production tilesets.

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

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.

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

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

Downloading specific tilesets

Version 1.3.0 of the Installer allows you to specify which tilesets to download. For example, if you would like to download production streets data, but development terrain and satellite, you would do:

$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --dev-tilesets satellite,terrain

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> --tilesets none --no-geocoding --enterprise-boundaries none

Setup Atlas

Once the download command has completed, you will run the setup command. When the setup command runs, all the files from the source directory are moved into the target directory, then the source directory will be deleted. The setup command also loads each downloaded Docker image tarball and unzips geocoding data, if applicable.

You can run the setup command offline and you must run it from the Docker host where Atlas will be installed. If you ran the download command from another computer than the host you will need to copy over the download command destination directory in its entirety. The directory should contain two subdirectories, /docker and /tilesets, as well as a license.json file. If you have Atlas Search, you will have an additional directory called /search.

Usage

$ ./atlas-installer setup <source> <target> [options]

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.

Options

Note

If neither --self-signed or --ssl is specified, Atlas will be configured to run on HTTP.

  • --config (optional): Pass in a JSON configuration file to configure the Atlas password, port, and hostname. If a configuration file isn't passed, Atlas will be configured with the defaults shown below. You can also configure the Atlas password, port, and hostname by using the command line options rather than passing in a config.

  • --ssl, -s <path> (optional): The path to a directory that contains SSL certificate files, cert.pem (a certificate file) and key.pem (a private key for the certificate). These will be copied into your Atlas installation. Use this option if you need to use your own certificate. Cannot be used with --self-signed.

  • --self-signed, -l (optional): This will tell the installer to create self-signed SSL certificates and configure Atlas to run over HTTPS. Cannot be used with --ssl.

  • --hostname, -t (optional): Public hostname of the server running Atlas. Should match the host the end users will use in their browsers.

  • --password, -p (optional): Password administrators will use to access Atlas account dashboard & Studio. If no password is passed in, a secure password will be generated for you.

  • --port, -r (optional): Port the Atlas Server will listen on.

  • --upgrade (optional): Used to indicate that you are upgrading Atlas versions. If passed, setup will skip re-configuring settings.

--config format

Here is an example config.json showing defaults that will be applied if no config is passed. We highly recommend changing the default password at the minimum.

{
  "AtlasServerPassword": "password",
  "AtlasServerPort": 2999,
  "AtlasServerHostName": "localhost"
}

Examples

# Configure to run on HTTP
$ ./atlas-installer setup atlas-server-files/ atlas-server/

# Configure to run on HTTPS with self-signed certificates
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --self-signed

# Configure to run on HTTPS with custom certificates
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --ssl ~/sslcert-directory

Change configuration (post-setup)

If you want to change the config file or the Atlas protocol (HTTP/HTTPS) after you set up Atlas, use the settings command.

Usage

$ ./atlas-installer settings <target> --config <path to JSON file>

Options

  • --config (optional): Pass in a JSON configuration file to configure the Atlas password, port, and hostname. The config.json file takes the same format as for the --config option in the setup command. The config file will automatically be backed up to a config.json file in the Atlas target directory.
  • --http (optional): Configure Atlas to use HTTP. Cannot be used with --ssl or --self-signed.
  • --self-signed, -l (optional) : This will tell the installer to create self-signed SSL certificates and configure Atlas to run over HTTPS. Cannot be used with --ssl or --http.
  • --ssl, -s <path> (optional): The path to a directory that contains SSL certificate files, cert.pem (a certificate file) and key.pem (a private key for the certificate). These will be copied into your Atlas target directory. Use this option if you need to use your own certificate. Cannot be used with --http or --self-signed.

Examples

# Stop Atlas
$ (cd atlas-server && ./atlas.sh stop)

# Update the atlas config
$ ./atlas-installer settings atlas-server/ --config path/to/config.json

# Switch to HTTP
$ ./atlas-installer settings atlas-server/ --http

# Switch to HTTPS (custom certificate)
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --ssl path/to/certs

# Switch to HTTPS (self-signed certificate)
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --self-signed

# Start Atlas
$ (cd atlas-server && ./atlas.sh start)

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 <install-target>/docker directory. You will find the version of Atlas in the docker tarballs. This will help you know if you should upgrade.

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

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

Installer command reference

The recommended installation method above uses the following commands. If you used the recommended method, you do not need to use any of these commands directly, they are provided only for reference.

CommandRequires InternetDescription
installYesConfigure your installation through a series of prompts.
downloadYesDownloads Atlas.
setupNoInstall Atlas.
settingsNoChange Atlas settings.
listYesList downloadable Atlas versions.
removeNoUninstall Atlas or parts of Atlas.

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 for any of the following?

Select which development data you would like to download. For testing out or evaluating Atlas, we recommend downloading all development data. Use your arrow keys to navigate the options and <space> to make selections. Press <enter> to continue.

Are you upgrading an existing Atlas installation?

Only asked if installing Atlas on the same machine.

Defaults to no. Type in yes if you already have a previous version of Atlas v2 installed. This will skip re-configuring settings.

Do you plan to run Atlas on HTTPS?

Only asked if installing Atlas on the same machine.

Defaults to no (HTTP). If you plan to run Atlas on HTTPS, type yes and press <enter>.

Do you have an SSL certificate?

Only asked if running Atlas on HTTPS.

Defaults to yes. Type no if you do not have an SSL certificate, and the installer will generate one for you with OpenSSL.

Where is your cert located?

Only asked if answered yes to having an SSL certificate.

Enter the full path of the location of your SSL certificate.

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.

What is your Atlas server hostname?

Only asked if installing Atlas on the same machine.

Enter the public hostname of the server running Atlas. This should match the hostname your end users will use in their browsers. Defaults to localhost.

What port will you be running Atlas on?

Only asked if installing Atlas on the same machine.

Enter the port that Atlas will listen on. Defaults to 2999.

Enter a password for your Atlas server instance

Only asked if installing Atlas on the same machine.

Enter a password for administrators to use to access the Atlas account dashboard and Studio. Alternatively, you can press <enter> without entering a password, and the installer will generate a secure password for you. Your password must be at least 8 characters.

Was this page helpful?