Upgrade Atlas

help
Note
This guide assumes you are using at least v1.3.0 of the Atlas Installer

To upgrade to the latest version of Mapbox Atlas, you will need access to the internet to pull in new data.

To upgrade when a new Atlas version is released, you will need to download new Docker images. This guide also applies for upgrading your map data. We recommend upgrading using the install command to upgrade Atlas.

Back up your settings

As a precaution before upgrading, make sure your config is saved as a JSON to use as a backup in case your settings are overwritten during an upgrade:

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

Save this file and keep it somewhere safe. If you need to update your settings from a backup after upgrading, follow the guide to change your configuration post setup.

Clean out old data

Run the following commands before downloading any new data:

# Stop all docker containers, remove mounted volumes, networks, and purge all images
$ ./atlas-installer remove atlas-server/

# Remove existing docker tarballs
$ rm -rf atlas-server/docker/
$ rm -rf atlas-server-files/docker

Upgrade using the Installer Wizard

First, make sure you followed the guide to clean out old data. To upgrade, 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.

To ensure your settings aren't touched, make sure you answer yes to Are you upgrading an existing Atlas installation?.

If you are planning to update your tilesets without upgrading to a new version of Atlas, you can use the install command and deselect Docker images and then select the tilesets you want to download for the What data would you like to download? prompt

Manual upgrade

If you prefer to run the download and setup commands manually rather than the install command, follow these instructions. Make sure you followed the instructions to clean out old data and you have backed up your settings.

To upgrade to a new version of Atlas

# Download new images
$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token> --no-tilesets --no-geocoding --enterprise-boundaries none

# Set up Atlas with new images
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --config <config.json>

Upgrade Atlas images and tilesets

If you are upgrading a testing or beta Atlas installation that was using development tilesets, you may want to download the full-zoom production tilesets instead.

Run the following commands to upgrade your Atlas images and tilesets:

# Stop all docker containers, remove mounted volumes, networks, purge all images, and remove Mapbox tilesets
$ ./atlas-installer remove atlas-server --mapbox-mbtiles

# Download new images and data
$ ./atlas-installer download atlas-server-files/ --token <your-atlas-token>

# Set up Atlas with new images and tilesets
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --config <config.json>

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

# Overwrite the dev tilesets with the downloaded production tilesets
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --config <config.json>

If you want to only update your Mapbox Streets tileset, you can specify --tilesets streets to only download the latest Mapbox Streets tileset.

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

# Set up Atlas with new images and tilesets
$ ./atlas-installer setup atlas-server-files/ atlas-server/ --config <config.json>