Skip to main content

Legacy Atlas

Join the Mapbox Developers Discord Communityarrow-right
Legacy
Legacy Atlas only supports raster maps using Mapbox.js, while the updated Atlas version supports the latest Mapbox vector map technology, including Mapbox GL JS. The updated Atlas also ships with the latest Mapbox styling software, Mapbox Studio.Still using the legacy version of Atlas? We'd love for you to upgrade! Contact Mapbox support for help in migrating from legacy Atlas to the newest version.

Legacy Atlas install and setup​

Specifications​

The legacy Atlas product runs on Ubuntu 14.04, CentOS 7, and Red Hat Enterprise Linux 7. A developer version is available for OS X. We recommend the following hardware configuration:

  • 16 CPU cores
  • 32 GB RAM
  • 512 GB SSD

Download and install​

The legacy Atlas software and datasources are available for download at mapbox.com/studio/atlas.

Unpack the Atlas zip and run ./install.sh. All dependencies are pre-built and will be installed with Atlas. Then open http://localhost:2999/atlas/setup in the browser and follow the steps below to complete the setup process.

License key​

You can find your Atlas license key at mapbox.com/studio/atlas:

Copy the license key, go to http://localhost:2999/atlas/setup, and paste it into the license key field.

Server URL​

By default, legacy Atlas installs on the localhost domain at port 2999, as in http://localhost:2999. To set Atlas's URL for production, go to http://localhost:2999/atlas/setup and set the URL to http://your.server.location:2999.

In this example, Atlas's URL is http://ec2-54-205-117-140.compute-1.amazonaws.com:2999.

To change legacy Atlas's port from the default 2999, you can set the AtlasServerPort environment variable during installation. For example, to set the port to 2555:

  • Run sudo AtlasServerPort=2555 ./install.sh
  • Go to http://localhost:2555/atlas/setup and set the legacy Atlas URL to http://your.server.location:2555

Adding datasources​

To serve map tiles, the following datasources must be added to /opt/atlas-server-data/sources/:

  • mapbox.mapbox-streets-v5.mbtiles
  • mapbox.mapbox-terrain-v1.mbtiles
  • mapbox.satellite-full.mbtiles
  • mapbox.satellite-watermask.mbtiles

If you installed legacy Atlas via AMI, your instance may already include development (lower zoom) datasources. If you did not install via AMI or want to add production (higher zoom) datasources, you must download the datasources from your Mapbox account and add them to /opt/atlas-server-data/sources/, matching the above file names exactly.

Download URLs are cycled every 12 hours for security purposes. For larger datasources, especially the production version of mapbox.satellite-full.mbtiles, you may need to use a continuous download:

  • Copy download URL for mapbox.satellite-full.mbtiles from mapbox.com/studio/atlas
  • wget -c "pasted-download-URL" -O mapbox.satellite-full.mbtiles
  • If the URL cycles and download stops, copy the new download URL
  • wget -c "pasted-new-download-URL" -O mapbox.satellite-full.mbtiles
  • Repeat until download is complete

Once the license key, server URL, and datasources have been configured, legacy Atlas is ready to go.

Server logs​

To export and view the legacy Atlas logs on CentOS 7 and Red Hat Enterprise Linux 7, use the following command:

  • sudo journalctl -u atlas-server > /tmp/logs.txt

On Ubuntu 14.04, the legacy Atlas logs can be viewed at /var/log/upstart/atlas-server.log.

Install legacy Atlas on AWS​

To install legacy Atlas on AWS, we recommend using an Amazon Machine Image (AMI). There are two ways to install via AMI.

Install via AWS console​

Here are steps to install Atlas via the AWS Console:

  1. Login to your desired AWS region and click on the EC2 button.
  2. Click Launch Instance.
  3. Click My AMIs and check the Shared with me box under Ownership.
  4. Choose your instance type (c3.4xlarge is recommended).
  5. Confirm that presence of an EBS volume with 512 GB of storage, and add additional storage if desired.
  6. Configure your security group. Atlas operates on port 2999, which you must set as open. Add rule:
    • Type: Custom TCP Rule
    • Protocol: TCP
    • Port Range: 2999
    • Source: Anywhere
  7. Review your instance and, if it is properly configured, launch.
  8. Before launching, there will be a prompt to add a key-name pair to use to SSH into the instance. If you plan to SSH into the instance (recommended), select or create a new key pair.

Your instance is launched. Grab its public DNS record and go to http://your.server.url:2999/atlas/setup to begin the configuration process.

Install via CloudFormation template​

You will need:

Run the following command:

aws cloudformation create-stack \
--region us-east-1 \
--stack-name "Atlas_Server" \
--parameters ParameterKey=Instance,ParameterValue=c3.4xlarge ParameterKey=KeyName,ParameterValue=your_key_name \
--template-url https://s3.amazonaws.com/mapbox/atlas-server/ami/atlas-server-linux-x64-VERSION.template

This command will launch an Atlas instance in the US-East-1 region. Go to your AWS console, find the instance, copy its public DNS record, and navigate to http://your.server.url:2999/atlas/setup/ to configure your instance.

Suggested instance types​

Mapbox recommends deploying legacy Atlas with a c3.4xlarge, though it is also compatible with the following instance types:

  • c3.8xlarge
  • r3.4xlarge
  • r3.8xlarge
  • i2.4xlarge
  • hs1.8xlarge

Notes​

  • Legacy Atlas AMIs include development data sources. To add full production base map data follow the instructions for adding datasources.
  • The sudo command is not possible on a legacy Atlas instance created via AMI.
  • User data scripts are not allowed when creating a legacy Atlas instance via AMI. You can provide a script, but it will be blocked by the AMI.

Upgrading legacy Atlas​

Upgrade a local instance​

To upgrade a local instance of Atlas while retaining your source and style files, run rm -rf /opt/atlas-server but leave /opt/atlas-server-data in place. Then download the latest Atlas package from your Mapbox.com account and follow the normal installation instructions.

Upgrade on AWS​

To upgrade your Atlas AMI instance while retaining your source and style files, take a snapshot of your data, create a new instance, and attach the data volume to the new instance using the following steps:

  • From the AWS Console, navigate to your instance.
  • Find the attached data volume at the bottom of the Description tab for your instance under Block Devices. The data volume will always be the /dev/sdg device.
  • Create a snapshot of your data volume by clicking Actions > Create Snapshot.
  • While the snapshot is copying, create a new Atlas instance from the most recent AMI. Follow the Atlas AMI setup instructions, but remove the data volume option on the Storage page.
  • Once the new instance has completed all setup processes, stop the instance.
  • Create a new volume from you data snapshot in the same availability zone as the new Atlas AMI instance.
  • Attach the volume to the stopped instance by clicking Actions > Attach Volume.
  • Paste the instance ID of your stopped Atlas in the Instance field. Under device paste /dev/sdg. This step will not work if the volume and instance availability zones are different.
  • Once your data volume is attached, start your new Atlas instance and stop the old one.

Mapbox Studio Classic and legacy Atlas​

Mapbox Studio Classic is a desktop application for vector tile driven map design. You can use Mapbox Studio Classic to create new sources and styles with your data that can be loaded onto the legacy Atlas product. Mapbox Studio Classic is no longer in development, and we recommend using Mapbox Studio instead.

Connect Mapbox Studio Classic​

Enter your Atlas URL in the Mapbox Studio Classic login screen.

Once connected to Atlas, Mapbox Studio Classic will display Offline user.

New source​

Atlas stores source data in .mbtiles files in the /opt/atlas-server-data/sources/ directory. To create a new source from your data, follow the steps in our source quickstart. When your source is ready, follow these steps:

  • Click Save as.
  • Click Settings and select Export to MBTiles.
  • Click Download once the export is complete.
  • Move the downloaded file into your Atlas's /opt/atlas-server-data/sources/ directory.
  • Confirm that the new source and its map ID are visible in Atlas's Sources tab:

New style​

Atlas stores style data in .tm2z files in the /opt/atlas-server-data/styles/ directory. To create a new style from a source file on Atlas:

  • Click Projects in the lower left corner of Mapbox Studio Classic.
  • Click New project.
  • Enter your source’s map ID in the your map ID box, shown below. Multiple sources can be composited by separating their map IDs with commas.
  • Click Create.
  • Use CartoCSS to style your data. (For more information, see the Mapbox style manual.)
  • Click Save as.
  • Click Settings and select Download package.
  • Move the downloaded file into your Atlas's /opt/atlas-server-data/styles/ directory.
  • Confirm that the new style and its map ID are visible in the Styles tab:

Naming sources and styles​

Each source and style file must have a unique filename. Source and style files can be renamed after export from Mapbox Studio Classic and before loading into Atlas with the following formats:

  • Sources: aaaa.bbbb.mbtiles
  • Styles: xxxx.yyyy.tm2z In these examples, aaaa.bbbb and xxxx.yyyy will be the map IDs corresponding to the source and style files.
Join the Mapbox Developers Discord Communityarrow-right
Was this page helpful?