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 multiple commands that can support different deployment environments. 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 an internet-connected server to download Atlas data. Once the data has been downloaded, copy it to the Atlas host to complete the setup process.
Architecture
The diagram below shows how Atlas operates with external and internal services via ports, protocols, and data flows. Atlas listens on a single port and protocol for data requests. Internally, Atlas runs on a single host with routing, Mapbox APIs, data, and caching running in Docker containers.
Download PDFDependencies
To download and set up Atlas for Docker Compose, you need to download several dependencies first:
- Docker
- Docker Compose
wget
unzip
coreutils
pv
(optional)- 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. 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.
Configuring Docker
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 to 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*
- Ubuntu 16.04
- Ubuntu 18.04
- Ubuntu 20.04
- CentOS 7
- Red Hat Enterprise Linux 7
- Red Hat Enterprise Linux 8
* Recommended for development only
macOS
- Download and install Docker and Docker Compose for macOS from the Docker website.
- Use Homebrew to install Wget, unzip, pv, coreutils, and, optionally, OpenSSL:
$ brew update
$ brew install wget unzip pv coreutils openssl
- Docker needs at least 4 GB of RAM to run on macOS. Open the Docker control panel. Click Preferences (⚙) > Resources. Adjust the memory by sliding the tab to 4 GB.
Ubuntu
# 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
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
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
Red Hat Enterprise Linux 8
The OverlayFS storage driver must sit on top of an XFS file system. The following guidance assumes a storage volume is accessible at /dev/nvme1n1
.
# 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
$ mkfs -t xfs -n ftype=1 /dev/nvme1n1
$ mkdir /data
$ mount /dev/nvme1n1 /data
$ chown ec2-user /data # Replace "ec2-user" with the Atlas service account name
# Add the new volume to /etc/fstab to mount on reboot
# Update System
$ yum update -y
# Enable EPEL and Docker repository
$ rpm --import https://download.docker.com/linux/centos/gpg
$ rpm --import http://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-8
$ yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
$ yum install -y yum-utils
$ yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
$ yum makecache
# Install Docker & Atlas dependencies
$ yum remove -y podman
$ yum install -y docker-ce wget openssl unzip pv python36
# Configure Docker to use allocated volume
$ mkdir -p /etc/docker
$ mkdir /data/docker
$ echo '{"graph":"/data/docker"}' > /etc/docker/daemon.json
# Setup Docker group
$ usermod -aG docker ec2-user
# 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 "/data/docker"
$ restorecon -R /data/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.28.0/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
# Link an available version of python
$ ln -s /usr/bin/python3 /usr/local/bin/python
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.
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.
Tileset size
Below are approximate sizes for each tileset. Exact tileset file sizes are subject to change with new data from periodic updates.
Dataset | Dev | Production | High-Resolution |
---|---|---|---|
Terrain-v2 | 1 GB | 40 GB | 820 GB |
Streets-v7 | 325 MB | 125 GB | Not Available |
Streets-v8 | 325 MB | 350 GB | Not Available |
Countries-v1 | 1 MB | 1.5 GB | Not Available |
Satellite | 1 GB | 225 GB | 2 TB |
Terrain-RGB | 1.5 GB | 450 GB | 3.2 TB |
Boundaries | Not Available | 15 GB | Not Available |
Search | 5 GB | 75 GB | Not Available |
Navigation | 100 MB | 85 GB | Not Available |
Total | 10 GB | 1.4 TB | 6.7 TB |
Docker images
In total, Docker images are about 15 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 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.
1.6.1
of the Atlas installer. If you have an older version of the installer, you need to download a more recent 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 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 install.sh
script and configure your installation based on the information passed in to the wizard. Once complete, you can skip to the configure Atlas section.
Install Atlas on a different machine
If you are planning to install Atlas on a different machine (for example, a machine without an internet connection), you should only run install
to download Atlas. You will then need to run the install.sh
script 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 you answered no
to the first prompt, the installer wizard will only ask you the questions needed to download data. Once the installer has finished downloading data, you will need to copy the downloaded files and run the install.sh
script.
Manual installation method
We recommend using the installer wizard for a better install experience.
install
command but are installing Atlas on a different machine (for example, an offline server), you should copy the downloaded files in your atlas-server-files
directory to the new location and run the install.sh
script.Download Docker images, tilesets, and data
The download
command will download the files required to a directory to be used by the install.sh
script. 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.com secret access token with "atlas:read" scope, for example, "sk.abc123"
--version, -v Version of Atlas to download
--docker Download Docker images
--dev Download development versions when combined with the tilesets, geocoding, or navigation options
--tilesets Download specific tilesets
--geocoding Download geocoding data
--boundaries Download Mapbox Boundaries tilesets
--navigation Download navigation data
--tileset-checksums Calculate checksums for tileset and data 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 install.sh
script.
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
–z8
) 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 streets --tilesets satellite --tilesets terrain
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.8.1
of Atlas, you would run:
$ ./atlas-installer download ./atlas-server-files/ --token <your-atlas-token> --version v2.8.1 --docker