Upgrade Atlas

Note

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 Mapbox 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.

Note

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.

  1. Install the new Atlas using the guides to Install Atlas and Configure Atlas. Copy any custom configuration to the new config file.

  2. 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
    
  3. Start the new Atlas installation:

    cd <atlas-server-old>
    ./atlas.sh stop
    cd <atlas-server-new>
    ./atlas.sh start
    
  4. Connect to Atlas in your browser and verify the listed version is correct. Use Studio to verify expected data is correct.

  5. 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:

  1. 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.
  2. 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.

Note

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:

ArgumentTilesets
--tilesets allAll
--tilesets streetsMapbox Streets
--tilesets terrainMapbox Terrain
--tilesets satelliteSatellite

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

Was this page helpful?