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.
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
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.
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.
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
In this example, Atlas's URL is
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
sudo AtlasServerPort=2555 ./install.sh
- Go to
http://localhost:2555/atlas/setupand set the legacy Atlas URL to
To serve map tiles, the following datasources must be added to
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
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.
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
To install legacy Atlas on AWS, we recommend using an Amazon Machine Image (AMI). There are two ways to install via AMI.
Here are steps to install Atlas via the AWS Console:
- Login to your desired AWS region and click on the EC2 button.
- Click Launch Instance.
- Click My AMIs and check the Shared with me box under Ownership.
- Choose your instance type (c3.4xlarge is recommended).
- Confirm that presence of an EBS volume with 512 GB of storage, and add additional storage if desired.
- 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
- Review your instance and, if it is properly configured, launch.
- 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.
You will need:
- An AWS account
- AWS Command Line Tools installed
- A Mapbox access token
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.
Mapbox recommends deploying legacy Atlas with a c3.4xlarge, though it is also compatible with the following instance types:
- Legacy Atlas AMIs include development data sources. To add full production base map data follow the instructions for adding datasources.
sudocommand 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.
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.
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
- 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 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.
Enter your Atlas URL in the Mapbox Studio Classic login screen.
Once connected to Atlas, Mapbox Studio Classic will display Offline user.
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
- Confirm that the new source and its map ID are visible in Atlas's Sources tab:
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
- Confirm that the new style and its map ID are visible in the Styles tab:
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:
xxxx.yyyy.tm2zIn these examples,
xxxx.yyyywill be the map IDs corresponding to the source and style files.