Atlas for Docker Compose
Introduction
Atlas supports Docker Compose, a tool for defining and running multi-container Docker applications. Atlas for Docker Compose lets you run Atlas on a single host. If you need scaling, fault tolerance, high availability, or other advanced features, you may be interested in Atlas for Kubernetes.
Atlas installer
The Atlas for Docker Compose installer is a command line interface (CLI) utility used to download and set up Atlas on a host server. The installer has many commands that can support different network topologies. The installer is available for both macOS and Linux.
Connectivity requirements
The Atlas installer has been specifically designed for situations in which the host server has no internet connectivity. You must run the installer's install
or download
command from a connected server to download required dependencies. Once the dependencies have been downloaded, they can be copied over to the host to complete the set up process.
Dependencies
To download and set up Atlas for Docker Compose, you need to download several dependencies first:
- Docker
- Docker Compose
wget
pv
unzip
- OpenSSL (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. OpenSSL is used by Atlas to create a self-signed certificate, and is optional. 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.
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.
Configuring Docker
Check disk space & context storage configuration before continuing!
The Atlas deployment will require about 25 GB of disk space within your Docker context. Depending on how your Docker storage is configured you may have increase the disk space available to Docker. Get details about your configuration with docker info
and visit the Docker storage driver documentation. We recommend configuring overlay2
and explicitly setting your data-root
to live on NVMe SSD storage:
{
"data-root": "/nvme/docker",
"storage-driver": "overlay2"
}
Supported operating systems
You can run Atlas for Docker Compose on the following operating systems:
- macOS*
- CentOS 7
- Ubuntu 14.04
- Ubuntu 16.04
- Ubuntu 18.04
- Ubuntu 20.04
- Red Hat Enterprise Linux 7
* Recommended for development only
macOS
- Download and install Docker and Docker Compose for macOS from the Docker website.
- Use Homebrew to install Wget and, optionally, OpenSSL:
$ brew update
$ brew install wget openssl unzip pv
- Docker needs at least 4 GB of RAM to run on macOS. Open the Docker control panel. Click Preferences > Advanced. Adjust the memory by sliding the tab to 4 GB.
CentOS 7
# Most of these commands need to be run by the root user
$ sudo su
$ yum check-update
$ yum install -y epel-release
$ yum install -y wget openssl python-pip unzip pv
# Install Docker
$ curl -fsSL https://get.docker.com/ | sh
# Add your user to the Docker group. i.e. centos
$ usermod -aG docker centos
# Enable the Docker daemon to start at system boot
$ systemctl enable docker.service
# Start the Docker daemon
$ systemctl start docker.service
# Install Docker Compose
$ pip install docker-compose
Ubuntu 14.04
# Update the package database
$ sudo apt-get update
# Install Docker and Atlas dependencies
$ sudo apt-get install \
linux-image-extra-$(uname -r) \
linux-image-extra-virtual \
apt-transport-https \
ca-certificates \
curl \
software-properties-common \
wget \
openssl \
unzip \
pv
# Add the Docker repository to APT sources
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) \
stable"
# Update the package database with the Docker packages
$ sudo apt-get update
# Install Docker
$ sudo apt-get install -y docker-ce
# Add your user to the Docker group
$ sudo usermod -aG docker ubuntu
# Check the current release and, if necessary, update it in the command below
$ sudo curl -L \
"https://github.com/docker/compose/releases/download/1.24.1/docker-compose-$(uname -s)-$(uname -m)" \
-o /usr/local/bin/docker-compose
# Set execute permissions on docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose
Ubuntu 16.04 and higher
# Update the package database
$ sudo apt-get update
# Install Docker and Atlas dependencies
$ sudo apt-get install -y wget openssl unzip pv
# Add the Docker repository to APT sources
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) \
stable"
# Update the package database with the Docker packages
$ sudo apt-get update
# Make sure you are about to install from the Docker repo
$ sudo apt-cache policy docker-ce
# Install Docker
$ sudo apt-get install -y docker-ce
# Add your user to the docker group
$ sudo usermod -aG docker ubuntu
# If necessary, log out and log back in to use the new group permissions
# Check the current release and, if necessary, update it in the command below
$ sudo curl -L \
"https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" \
-o /usr/local/bin/docker-compose
# Set execute permissions on docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose
# Link an available version of python
$ sudo ln -s /usr/bin/python3 /usr/local/bin/python
Red Hat Enterprise Linux 7
This guidance was tested with RHEL 7.6 3.10.0-957; per Docker documentation the OverlayFS driver requires a kernel version of at least 3.10.0-514. The OverlayFS storage driver must sit on top of an XFS file system. The following guidance assumes a storage disk is accessible at /dev/xvdf
.
# Red Hat Labs Registration
# SKIP IF: You have already registered your instance with Red Hat
$ subscription-manager register --username <username> --password <password> --auto-attach
# Initialize a disk w/ the XFS file system for OverlayFS & Docker
$ parted -a optimal /dev/xvdf mklabel gpt
$ parted -a optimal /dev/xvdf mkpart primary xfs 0% 100%
$ mkfs.xfs -n ftype=1 /dev/xvdf1
$ mkdir /docker
$ mount /dev/xvdf1 /docker
# Setup Docker users & groups:
$ useradd -M -r docker
$ usermod -aG docker ec2-user
# Enable Red Hat Subscription based repositories
$ subscription-manager repos --enable=rhel-7-server-rpms \
&& subscription-manager repos --enable=rhel-7-server-extras-rpms \
&& subscription-manager repos --enable=rhel-7-server-optional-rpms
# Update System
$ yum update -y
# Enable EPEL
yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
# Install Docker & Atlas dependencies
$ yum install -y docker device-mapper-libs device-mapper-event-libs \
wget openssl unzip pv
# Configure Docker to use disk space
$ echo '{"graph":"/docker"}' > /etc/docker/daemon.json
# Set SELinux file context type rules (https://success.docker.com/article/how-to-set-selinux-file-contexts-when-using-a-custom-docker-data-root)
$ semanage fcontext -a -e /var/lib/docker "/docker"
$ restorecon -R /docker
# Enable the Docker daemon to start at system boot
$ systemctl enable docker.service
# Start the Docker daemon
$ systemctl start docker.service
# Install Docker Compose
# Check the current release and, if necessary, update it in the command below
$ curl -L \
"https://github.com/docker/compose/releases/download/1.24.1/docker-compose-$(uname -s)-$(uname -m)" \
-o /usr/local/bin/docker-compose
# Set execute permissions on docker-compose
$ chmod +x /usr/local/bin/docker-compose
# Link docker-compose into the PATH
$ ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
Install Atlas
This guide will walk you through the following components of the Atlas installation:
- Downloading the installer.
- 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.
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.
Dataset | Dev | Production |
---|---|---|
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 |
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.
Download the installer
- Go to atlas.mapbox.com/install.
- Click the Download button for your operating system, either Linux or macOS.
- Unzip the downloaded zip file:
unzip atlas-installer.zip
. - Make sure the binary is executable:
chmod +x ./atlas-installer
.
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.
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:
- Your Mapbox access token with
atlas:read
scope. See Access Token for instructions on how to create this token. - 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
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 thedownload
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 withatlas: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
Command | Requires Internet | Description |
---|---|---|
download | Yes | Downloads Atlas resources. |
install | Yes | Configure your download and/or installation through a series of prompts. |
list | Yes | List downloadable Atlas versions. |
remove | No | Uninstall Atlas or parts of Atlas. |
setup | No | Install 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.
Configure Atlas
These instructions apply for Atlas version: 2.7.0
All configuration is contained within a single file found in the Atlas root: config
. This self documenting configuration file will be explained in this guide.
The default configuration
# Atlas username is atlas-user
# This is the password for atlas-user
atlasUserPassword=password
# This is the URL where users will be accessing Atlas
# This could be
# - the machine's local IP Address
# - the DNS name of your load balancer
# - etc
atlasURL=http://localhost:2999
# This is the port and protocol that the Atlas Docker
# container will listen on.
#
# If https is used, Atlas will expect SSL certificates to be placed
# in the $ATLAS_ROOT/ssl_cert folder with names:
# - cert.pem
# - key.pem
atlasPort=2999
atlasProtocol=http
# Sets the access keys for Minio s3 backend.
# These are the default access keys and they should be changed before starting Atlas the first time.
# Key rotation can be done following these instructions:
# https://github.com/minio/minio/blob/master/docs/config/README.md#rotating-encryption-with-new-credentials
# Uncomment and set the MINIO_ACCESS_KEY_OLD and MINIO_SECRET_KEY_OLD keys
# directly in the atlas-minio service in the docker-compose.yml
AWS_ACCESS_KEY_ID=EXAMPLE
AWS_SECRET_ACCESS_KEY=EXAMPLEKEY
Configuration reference
atlasUserPassword
should be changed and is generally only shared with Atlas administrators.atlasURL
also varies per installation and could be a local IP address or a public DNS hostname.atlasPort
is the port on which Atlas will bind to on the host machine.atlasProtocol
is the protocol Atlas will listen on using Nginx.AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
are access credentials for the internal S3 datastore.
Configure Atlas password
The password used to login to the Atlas Account page, Studio, and other resources should be changed from the default. To change this,
- Open the
config
file and set the desired password in theatlasUserPassword
field. - Restart Atlas:
./atlas.sh stop && ./atlas.sh start
.
Configure HTTPS
Atlas can be configured to communicate using HTTPS for increased security. In production use, the certificate file should be signed by a trusted Certificate Authority. For ease of testing, we also provide a script to generate a self-signed certificate.
- Edit the configuration:
- Open
./config
. - Change
atlasURL
to start with thehttps
protocol (e.g.,https://localhost:2999
). - Change
atlasProtocol
tohttps
. - Save and close the file.
- Open
- Save the certificate:
- If you have a signed certificate:
- Save the private key (in PEM format) to
./ssl_cert/key.pem
. - Save the certificate (in PEM format) to
./ssl_cert/cert.pem
.
- Save the private key (in PEM format) to
- If you want to create a self-signed certificate:
- cd to the Atlas root directory and run
./atlas.sh create-certificate
. This will store the necessary files in./ssl_cert
for you.
- cd to the Atlas root directory and run
- If you have a signed certificate:
- Restart Atlas:
./atlas.sh stop && ./atlas.sh start
For example, to configure HTTPS with a self-signed certificate, you would run:
sed -i .bak -e 's/atlasURL=http:/atlasURL=https:/;s/atlasProtocol=http$/atlasProtocol=https/' config
./atlas.sh create-certificate
./atlas.sh stop && ./atlas.sh start
Configure HTTP
Atlas can be configured to communicate by unencrypted HTTP if it has previously been configured with HTTPS.
- Edit the configuration:
- Open
./config
. - Change
atlasURL
to start with thehttp
protocol (e.g.,http://localhost:2999
). - Change
atlasProtocol
tohttp
. - Save and close the file.
- Open
- Restart Atlas:
./atlas.sh stop && ./atlas.sh start
For example, to configure HTTP, you would run:
sed -i .bak -e 's/atlasURL=https:/atlasURL=http:/;s/atlasProtocol=https$/atlasProtocol=http/' config
./atlas.sh stop && ./atlas.sh start
Run Atlas behind a reverse proxy
A common configuration is to have Atlas served over HTTP and behind an HTTPS reverse proxy. Because some services within Atlas advertise URIs to the client, you will need to configure Atlas to advertise the correct URI. These environment variables populate those URIs within the services.
- Stop Atlas:
./atlas.sh stop
- Edit
./config
- Update the
atlasURL
variable with your public hostname or load balancer address. - Update
atlasProtocol
&atlasPort
as needed. - Start Atlas:
./atlas.sh start
Run Atlas
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
as an install target. Change the install directory with that of your own configuration.
Atlas is started and stopped from the command line.
Start the server
To start Atlas, run the following commands:
$ cd atlas-server
$ ./atlas.sh start
- You will be able to follow startup progress in the console.
The start script will wait up to five minutes for all containers to report healthy. If you run into problems starting Atlas you can use these commands to troubleshoot:
docker-compose -f docker-compose.yml -f docker-compose.geocoding.yml ps
docker-compose -f docker-compose.yml -f docker-compose.geocoding.yml logs -f <unhealthy service>
Stop the server
To stop Atlas, run the following commands:
$ cd atlas-server
$ ./atlas.sh stop
- You will see a confirmation message once the Atlas server has stopped running.
Fix Redis THP and memory warnings
There are a few system requirements that Redis requires to run efficiently in a production environment. When you start Atlas, you may see the following Redis log warnings during startup:
redis | 1:C 18 Nov 2019 19:09:59.300 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
redis | 1:C 18 Nov 2019 19:09:59.301 # Redis version=5.0.5, bits=64, commit=00000000, modified=0, pid=1, just started
redis | 1:C 18 Nov 2019 19:09:59.301 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
redis | 1:M 18 Nov 2019 19:09:59.324 * Running mode=standalone, port=6379.
redis | 1:M 18 Nov 2019 19:09:59.324 # Server initialized
redis | 1:M 18 Nov 2019 19:09:59.324 # WARNING you have Transparent Huge Pages (THP) support enabled in your kernel. This will create latency and memory usage issues with Redis. To fix this issue run the command 'echo never > /sys/kernel/mm/transparent_hugepage/enabled' as root, and add it to your /etc/rc.local in order to retain the setting after a reboot. Redis must be restarted after THP is disabled.
You must make these changes on your Docker host, so the changes affect all processes running on the machine. Be sure to understand the implications for any other processes running on your host machine.
Enable vm.overcommit_memory (always)
To enable vm.overcommit_memory
without checks, run the following:
$ echo "vm.overcommit_memory = 1" | sudo tee -a /etc/sysctl.conf
Disable THP
Typically, THP can be disabled via a kernel option and the process for that depends on your specific system. Here are some examples that work well for us. Once reconfigured, you'll need to restart the system and verify the changes have persisted.
Making any changes to your boot configuration incorrectly could prevent your system from booting. Be careful!
To disable THP on CentOS 7 / RHEL 7
Add transparent_hugepage=never
to the GRUB_CMDLINE_LINUX
line in /etc/default/grub
. Then the file should look something like:
$ cat /etc/default/grub
GRUB_TIMEOUT=1
GRUB_DISTRIBUTOR="$(sed 's, release .*$,,g' /etc/system-release)"
GRUB_DEFAULT=saved
GRUB_DISABLE_SUBMENU=true
GRUB_TERMINAL="serial console"
GRUB_SERIAL_COMMAND="serial --speed=115200"
GRUB_CMDLINE_LINUX="transparent_hugepage=never console=tty0 crashkernel=auto console=ttyS0,115200"
GRUB_DISABLE_RECOVERY="true"
Then, rebuild grub.cfg
# Rebuild grub.cfg on a BIOS-based machine
$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
# Rebuild grub.cfg on a UEFI-based machine
$ sudo grub2-mkconfig -o /boot/efi/EFI/centos/grub.cfg
To disable THP on Ubuntu 18.04
Add transparent_hugepage=never
to the GRUB_CMDLINE_LINUX
line in /etc/default/grub
. Then the file should look something like:
$ cat /etc/default/grub
GRUB_TIMEOUT=1
GRUB_DISTRIBUTOR="$(sed 's, release .*$,,g' /etc/system-release)"
GRUB_DEFAULT=saved
GRUB_DISABLE_SUBMENU=true
GRUB_TERMINAL="serial console"
GRUB_SERIAL_COMMAND="serial --speed=115200"
GRUB_CMDLINE_LINUX="transparent_hugepage=never console=tty0 crashkernel=auto console=ttyS0,115200"
GRUB_DISABLE_RECOVERY="true"
Then, rebuild grub.cfg
$ sudo update-grub
To disable THP on Ubuntu 18.04 (Cloud Image)
$ sudo echo "GRUB_CMDLINE_LINUX_DEFAULT=\"\$GRUB_CMDLINE_LINUX_DEFAULT transparent_hugepage=never\"" > /etc/default/grub.d/99-transparent-hugepage.cfg'
$ update-grub
Reboot and verify
Reboot the machine to take effect. Next, verify the settings are correct:
$ sysctl vm.overcommit_memory
vm.overcommit_memory = 1
$ cat /sys/kernel/mm/transparent_hugepage/enabled
always madvise [never]
Troubleshoot your Atlas installation
If you have any issues while installing or running Atlas, the following troubleshooting strategies may help you diagnose and fix the problem.
Out-of-memory Docker errors
When developing locally with Atlas, you will sometimes get out-of-memory errors. Docker is conservative about garbage collection, meaning you will sometimes need to use the Docker prune
command to clean up unused Docker assets. To learn more about how to use the prune
command, visit the Docker documentation on pruning.
"No space left on device" errors
The Atlas installer setup command uses docker load
. You need enough disk space in both /var/lib/docker
and /tmp
to run setup. We recommend at least 20 GB of space for both directories. If you receive the error message Error processing tar file(exit status 1): ... no space left on device
, increase the disk space in either the /var/lib/docker
or /tmp
directories.
"Docker daemon is not running" errors
When the setup
command is running, you might see the error: The Docker daemon is not running. Please start Docker before proceeding.
If this occurs, reboot your instance with the command sudo reboot
. Then you can run the setup
command again.
View server logs
To view your Docker logs to diagnose issues, run the command docker-compose logs -f
and pipe the output of this command into a new log file. The -f
flag lets you follow the log output. To view other flag options for this command, see the docker-compose logs
documentation.
Expired license error message
Your Account page will display the expiration date of your Atlas user license so that you know when to get the renewal process started.
If your Atlas license has expired, you will see an expiration error when you try to start Atlas. If you see this message, contact us to discuss renewing your Atlas license.
Cannot verify certificate
On certain older systems Mapbox's certificate issued by DigiCert is not recognized. You can download a certificate authority bundle and configure wget
to trust the certificate by executing these commands:
$ mkdir ~/ca_certs
$ openssl s_client -showcerts -servername mapbox-atlas.s3.amazonaws.com \
-connect mapbox-atlas.s3.amazonaws.com:443 </dev/null > ~/ca_certs/mapbox.crt
$ echo ca_directory=~/ca_certs >> ~/.wgetrc
Submit feedback about Atlas
If you have any technical issues with installing or running Atlas, send an email to support@mapbox.com with the following information:
- Operating system name and version
- What were you doing when you ran into the problem? What specific commands did you run or actions did you take?
- What was the expected outcome?
- What was the actual outcome?
- Any relevant error logs in the browser console
- Any relevant application error logs
Upgrade Atlas
This guide assumes you are using at least v1.4.0 of the Atlas Installer. The installer can be downloaded here.
To upgrade to the latest version of Atlas, you will need access to the internet to download new data.
To upgrade when a new Atlas version is released, you will need to download new Docker images and data. Upgrading data (e.g., to add another tileset) will not require new Docker images. This guide applies to both scenarios.
Upgrade Atlas and data
Atlas can be upgraded in-place, in which case the existing installation is replaced, or as a fresh installation, in which case Atlas is installed and settings and data are copied. In case of a production Atlas installation, a fresh install may be more appropriate to reduce downtime.
Before running the install
or download
command, be sure the atlas-server-files
directory does not exist or is empty. Any extra files will be installed when you run the setup
command.
Fresh install
To do a fresh install, first we install Atlas with the latest data and then migrate custom data over.
Install the new Atlas using the guides to Install Atlas and Configure Atlas. Copy any custom configuration to the new
config
file.Copy over your custom data:
<atlas-server-new>/atlas.sh stop cp <atlas-server-old>/mbtiles/atlas-user.*.mbtiles <atlas-server-new>/mbtiles rm -rf <atlas-server-new>/dynalite-data/ cp <atlas-server-old>/dynalite-data <atlas-server-new>/dynalite-data
Start the new Atlas installation:
cd <atlas-server-old> ./atlas.sh stop cd <atlas-server-new> ./atlas.sh start
Connect to Atlas in your browser and verify the listed version is correct. Use Studio to verify expected data is correct.
Once you are satisfied the new installation is complete, you can uninstall the previous version of Atlas:
./atlas-installer remove <atlas-server-old> rm -rf <atlas-server-old>
Upgrade in-place
To upgrade in-place, we'll uninstall parts of the existing installation and install to the existing directory.
First, you need to clean out existing data. Run the following commands before downloading any new data:
# Stop all docker containers, remove mounted volumes, networks, and purge all images
# Keeps all tilesets and Studio styles
$ ./atlas-installer remove atlas-server/
Upgrade using the installer wizard
Choose whether to use the installer wizard. If you are connected to the Internet and want to use the wizard, run:
$ ./atlas-installer install
The install
command will guide you through the upgrade process. If you want to upgrade to a new version of Atlas without downloading new map data, make sure you deselect everything except Docker Images
when the installer prompts you about downloading data. If you have Atlas Search, include Geocoding data
when downloading to get the correct data package.
Upgrade manually
Or, if you prefer to run the download
and setup
commands manually, run:
# Download new images
$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --docker
# Set up Atlas with new images
$ ./atlas-installer setup atlas-server-files/ atlas-server/
If you have Atlas Search, be sure to include --geocoding
data when downloading.
Test the upgrade
Once the upgrade is complete, test it:
- Verify the
atlas-server/config
file is correct and migrate any settings to it if necessary. Run./atlas.sh stop && ./atlas.sh start
to apply any changes. - Connect to Atlas in your browser and verify the listed version is correct. Use Studio to verify expected data is correct.
Upgrading to a specific version of Atlas
If you want to upgrade to a specific version of Atlas, provide the version number when downloading the files. Use the atlas-installer list
command to list the available Atlas versions. You may need to download a different version of the installer if the Atlas version you need is not displayed.
$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --docker --version <your-version>
# Set up Atlas with new images and tilesets
$ ./atlas-installer setup atlas-server-files/ atlas-server/
Upgrade data only
To upgrade the data used by your Atlas installation, follow these instructions. For example, this will be useful if you want to replace development tilesets with production tilesets or have an update for a tileset.
Before running the install
or download
command, be sure the atlas-server-files
directory does not exist or is empty. Any extra files will be installed when you run the setup
command.
Updating Boundaries data
Periodically, Boundaries data receives updates with additional and improved information. To upgrade Atlas with these updates, you will re-run the download
and setup
commands.
First verify that your download destination directory does not include previous Boundary data. Specifically, the atlas-server-files/tilesets
directory, if it exists, shouldn't have any files with a name starting with mapbox.enterprise-boundaries
. Once confirmed, run the following commands to update Boundaries data:
# Download updated Boundaries data
$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --boundaries
# Overwrite the previous Boundaries data with the updated Boundaries data
$ ./atlas-installer setup atlas-server-files/ atlas-server/
Upgrade from development to production tilesets
If you initially installed Atlas with low-res development tilesets, at some point you may want to upgrade to full-zoom production tilesets. To do this, you will re-run the download
command with the --tilesets
flag.
Run the following commands to upgrade from development tilesets to production tilesets:
# Download production tilesets
$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --tilesets all
# Overwrite the dev tilesets with the downloaded production tilesets
$ ./atlas-installer setup atlas-server-files/ atlas-server/
You can select which tilesets to download and update:
Argument | Tilesets |
---|---|
--tilesets all | All |
--tilesets streets | Mapbox Streets |
--tilesets terrain | Mapbox Terrain |
--tilesets satellite | Satellite |
Upgrade from development to production geocoding data
Like upgrading from development to production tilesets, to fully experience Atlas Search, you should use production search data. To do this, you will re-run the download
command with the --geocoding
flag.
Run the following commands to upgrade from development geocoding data to production geocoding data:
# Download production geocoding data
$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --geocoding
# Overwrite the dev geocoding data with the downloaded production geocoding data
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --config <config.json>
Upgrade to a specific version of Atlas
If you want to upgrade to a specific version of Atlas, provide the version number when downloading the files.
$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --docker --version <your-version>
# Set up Atlas with new images and tilesets
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --config <config.json>
Update your Atlas license
To update your Atlas license, you will need to update the license.json
file, located in the same folder as atlas.sh
. You can do this while Atlas is up and running.
First, grab your license from https://atlas.mapbox.com/install (make sure you're logged in as the account with the Atlas license) and copy your license key.
Next, open up license.json
, and drop in your updated license string:
{
"license": "your-old-license-string-will-be-here----replace-it-with-your-new-one"
}
Save the file, and the Atlas instance will pick up the changes automatically and update itself. Once this succeeds, you should be able to see your new license expiration date under the License heading on the right side of the main Atlas landing page (localhost:2999, or wherever your instance is deployed to).
Release notes
2.7.0
Added
- Added geocoding data for Belarus, Cambodia, Canada, and France
- Added support for Atlas Navigation for preview customers
- Improved SELinux support for Docker volumes
Changed
- Replaced
fake-s3
with MinIO for scalability improvements - Bypass default proxy settings when generating public access token
Fixed
- Fixed
set-user-limits
command to allow authorized users to configure rate limits create-cert.sh
utility script uses 4096 bits instead of 4086
2.6.0
Added
- Kepler.gl, a web application for visual exploration of large-scale geolocation data sets, added to dashboard
- Mapbox Boundaries v2 demos now accessible from the main landing page
- Maps cleared from Redis cache when associated MBTiles is changed
- Atlas start script includes
create-certificate
command to generate self-signed certificate for development use - Atlas start script provides help text
- Atlas start script can disable starting
api-geocoder
with command./atlas.sh start --disable-geocoding
- Atlas start script has improved status handling while starting containers and terminates with helpful messages if containers reach a state other than
healthy
orstarting
Changed
- Updated Mapbox APIs to the latest versions
- Atlas configuration now documented inline and accessible at
$ATLAS_ROOT/config
- Includes up to
Mapbox GL JS v1.6.1
- Includes up to
Mapbox.js v3.2.1
- Simplified environment variable-based configurations
- Renames
atlas-redis
andatlas-memcached
toredis
andmemcached
- Docker container health checks are faster
Fixed
- CORS support added on
/static/
for local development - Permissions on
pk_token.txt
explicitly set - Improved resiliency of start-up health checks
2.5.4
Added
- Mapbox Boundaries v2 support
- Upgraded Maps APIs to latest state as of 5/16/2019
- Upgraded Accounts API to latest state as of 5/29/2019
- Display current Atlas version on account dashboard
- Upgraded Mapbox GL JS up to v0.54.0 changelog
- Upgraded Mapbox GL Geocoder up to v4.3.0 changelog
- Large MBTiles file (> 25 GB) support
Changed
- Removed
docker-compose.https.yml
— HTTPS is now configured by environment variable - Consolidated
.env
files inconfig
Security
- Upgraded images to use node 8/10 and Ubuntu 18.04