Atlas Installation and Configuration for Docker Compose and Legacy Environments

Atlas is a powerful geospatial data rendering and management platform developed by Mapbox. It enables users to render custom maps using Mapbox's APIs and data, and supports multiple deployment environments, including Docker Compose and legacy setups. This article provides a detailed overview of the installation, configuration, and maintenance processes for Atlas, focusing on best practices, system requirements, and troubleshooting steps.

Overview of Atlas Installation Methods

Atlas supports two primary installation methods: the modern Docker Compose deployment and the legacy installation for environments requiring specific compatibility with older operating systems or configurations. The Docker Compose method is designed for flexibility and scalability, allowing Atlas to run on a single host with support for multi-container Docker applications. The legacy method, on the other hand, is tailored for environments where Docker Compose is not an option, such as systems running Ubuntu 14.04, CentOS 7, or Red Hat Enterprise Linux 7.

Both installation methods require a Mapbox access token with the atlas:read scope, as well as a license key for accessing the full range of Atlas features. Users must also decide whether Atlas will be installed on the same machine where the installation is initiated or a different machine, such as in air-gapped environments.

Preparing for Atlas Installation

Before beginning the installation, it is essential to gather the necessary prerequisites and understand the system requirements. The following sections outline the key considerations for both Docker Compose and legacy installations.

System Requirements

For Docker Compose deployments, the system must support Docker and have sufficient disk space to store Docker images and tilesets. The exact disk space required depends on whether development or production tilesets are used. For example, the production version of the Terrain-v2 dataset requires approximately 40 GB of disk space, while the development version is only 1 GB.

Legacy installations have more specific requirements. They are supported on Ubuntu 14.04, CentOS 7, and Red Hat Enterprise Linux 7. The recommended hardware configuration includes at least 16 CPU cores, 32 GB of RAM, and 512 GB of SSD storage. A developer version is also available for macOS users.

Required Information

Regardless of the installation method, users must prepare the following:

• A Mapbox access token with the atlas:read scope
• An Atlas license key
• A decision on whether to install Atlas on the same machine or a different one
• The version of Atlas to be installed
• The desired port and hostname for the Atlas server
• SSL certificate details (if deploying with HTTPS)

Installing Atlas Using Docker Compose

The Docker Compose method is ideal for users who need a flexible and scalable deployment. The installation process involves using the Atlas installer, a command-line interface (CLI) utility that guides users through the setup process.

Step-by-Step Installation

1. Download and Prepare the Installer
   Begin by downloading the Atlas installer and making it executable using the command: bash chmod +x ./atlas-installer

2. Run the Installer Wizard
   Execute the installer with the install command: bash $./atlas-installer install The installer will prompt the user with a series of questions, including the installation location, whether Atlas will be installed on the same machine, and the desired port and hostname.

3. Download Atlas Data
   If the user selects to install Atlas on the same machine, the installer will proceed to download the necessary data and dependencies. The following command can also be used to download data separately: bash $./atlas-installer download atlas-server-files/ --token <your-atlas-token> --geocoding

4. Install and Configure
   After downloading the data, the installer will run the install.sh script to set up Atlas. Users can also manually run this script: bash $atlas-server-files/install.sh atlas-server/

5. Verify the Installation
   Once the installation is complete, users can access the Atlas web interface by navigating to the specified URL, typically http://localhost:2999.

Customizing the Installation

• Changing the Port
  To change the default port (2999) during installation, set the AtlasServerPort environment variable: bash sudo AtlasServerPort=2555 ./install.sh

• Setting the Server URL
  If deploying in production, users can configure the server URL via the web interface at http://localhost:2999/atlas/setup. For example: http://your.server.location:2999

• HTTPS Configuration
  If HTTPS is required, users must provide the path to their SSL certificate during the installation process.

Legacy Atlas Installation

The legacy Atlas installation is suitable for environments that require specific compatibility with older operating systems. This method is also useful for organizations with existing infrastructure that cannot be easily migrated to Docker-based solutions.

Step-by-Step Installation

1. Download Atlas
   The legacy Atlas software and data sources are available for download at mapbox.com/studio/atlas. Users should unpack the downloaded zip file and run the install.sh script: bash $./install.sh

2. Enter the License Key
   After installation, users must enter their Atlas license key via the web interface at http://localhost:2999/atlas/setup. This can be obtained from mapbox.com/studio/atlas.

3. Configure the Server
   The default server URL is http://localhost:2999. To change this for production, users can set a custom URL in the web interface. For example: http://ec2-54-205-117-140.compute-1.amazonaws.com:2999

4. Verify the Installation
   Access the Atlas web interface to confirm that the installation was successful and that the license key is active.

Installing on a Different Machine

If installing on a different machine (such as in an air-gapped environment), users should run the install command from an internet-connected machine to download the data. Once the data is downloaded, transfer it to the target machine and run the install.sh script there.

Configuring and Managing Atlas

After installation, users may need to configure Atlas for production use. This includes updating the license, upgrading data, and ensuring security best practices are followed.

Updating the License

To update the Atlas license, users must modify the atlasLicense setting in the Atlas root configuration file. The process involves the following steps:

1. Log in to the Mapbox account with an Atlas license.
2. Copy the new license key from the Atlas installation page.
3. Open the configuration file and update the atlasLicense field: bash atlasLicense=ey...
4. Save the file and restart Atlas.
5. Verify the new license expiration date in the Atlas web interface.

Upgrading Data and Tilesets

Atlas supports upgrades of both data and tilesets. To replace development tilesets with production tilesets or update existing data, users must re-run the download and install.sh commands.

Example: Upgrading Boundaries Data

1. Ensure the download destination directory is empty.
2. Run the following commands: bash # Download updated Boundaries data $./atlas-installer download atlas-server-files/ --token <your-atlas-token> --boundaries # Overwrite the previous Boundaries data with the updated data $atlas-server-files/install.sh atlas-server/

Example: Upgrading from Development to Production Tilesets

1. Confirm the download directory is empty.
2. Run the following commands: bash # Download production tilesets $./atlas-installer download atlas-server-files/ --token <your-atlas-token> --tilesets # Overwrite the dev tilesets with production tilesets $atlas-server-files/install.sh atlas-server/

Troubleshooting Common Issues

During the installation and configuration of Atlas, users may encounter a variety of issues. Below are some common problems and their solutions.

Connection Issues

• Problem: Atlas fails to connect to external services.
• Solution: Ensure that the server has the correct network configuration and that any firewalls or proxies are configured to allow traffic on the necessary ports.

License Validation Errors

• Problem: Atlas fails to validate the license key.
• Solution: Double-check that the license key is correctly entered in the configuration file and that it has not expired.

Port Conflicts

• Problem: Atlas fails to start because the default port (2999) is already in use.
• Solution: Change the port during installation or in the configuration file using the AtlasServerPort environment variable.

SSL Certificate Errors

• Problem: Atlas fails to start in HTTPS mode.
• Solution: Ensure that the SSL certificate is correctly configured and that the path to the certificate is specified during installation.

Disk Space Errors

• Problem: Atlas fails to download data due to insufficient disk space.
• Solution: Free up disk space or increase the available storage capacity.

Production Deployment Checklist

Deploying Atlas in a production environment requires careful planning and adherence to best practices. The following checklist provides a guide for ensuring a secure and stable deployment.

1. Use a Load Balancer or CDN
   Deploying Atlas with a load balancer or CDN can help manage traffic and protect against DDoS attacks. Ensure that the load balancer is configured to handle the X-Forwarded-For header.

2. Set Up HTTPS
   Always deploy Atlas using HTTPS to ensure secure communication. Provide a valid SSL certificate and configure the server accordingly.

3. Monitor Performance and Logs
   Regularly monitor the performance of the Atlas server and review logs for any errors or warnings.

4. Implement Backup and Recovery
   Set up a regular backup schedule for the Atlas data and configuration files. Ensure that a recovery plan is in place in case of data loss or corruption.

5. Secure the Server
   Apply the latest security patches and updates to the operating system and any dependencies. Use strong authentication and access controls to prevent unauthorized access.

Conclusion

Atlas is a powerful geospatial rendering platform that can be deployed in a variety of environments using either Docker Compose or legacy methods. The installation and configuration process involves careful planning, preparation, and adherence to best practices. By following the steps outlined in this article, users can ensure a smooth and secure deployment of Atlas, whether for development, testing, or production use. Regular maintenance, updates, and monitoring are essential for maintaining the performance and security of the Atlas instance over time.

Sources

1. Atlas for Docker Compose
2. Legacy Atlas Installation and Setup