Upgrade Atlas

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 make sure 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>

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

# 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> --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>

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.

To validate that the Atlas instance has picked up the license changes, run docker-compose logs atlas-router and you should see the following:

atlas-router    | Atlas License expiration date -  (your license expiration date)
atlas-router    | Atlas License valid - restarting nginx

After 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).

Was this page helpful?