General
What is Atlas?
Atlas is a containerized set of Mapbox services which can be downloaded and installed to self-host Mapbox APIs and data on a private cloud or on-premises network. Atlas works offline, even in air gapped or classified environments. With Atlas, you have full control over the location data and services in your applications.
What can I do with Atlas?With Atlas, you can create an entire custom location platform from start to finish on your own private infrastructure. Style beautiful custom basemaps in Studio then use them with Mapbox GL JS to create beautiful heatmaps or complex data visualizations. Bring business intelligence visualizations on-premises with drop-in support for Power BI, Tableau, MicroStrategy, and Cognos. Create custom tilesets of high resolution satellite imagery with GDAL and use Tippecanoe to transform massive vector datasets into slim mbtiles files. Use Atlas to power your private mobile applications using our Mapbox Maps SDKs for Android and iOS. You can even use Atlas with our Unity SDK to power 3D visualizations using sensitive data.
Why should I use Atlas?With Atlas, you can map, display, and analyze large or sensitive geographic data that needs to stay on-premises or in your own private cloud. Atlas lets you use Mapbox APIs while meeting the security needs or requirements of your organization, including HIPAA, SOC 2, FISMA, ISO, or GDPR. Atlas can also power location services for remote, distributed, or offline systems such as utility operation centers, cruise ships, or field laptops in humanitarian missions.
How does Atlas work?Atlas is downloaded as a set of containers including Mapbox APIs, data storage, a caching layer, and a user interface. These interdependent services are brought together to run Atlas by using either Docker Compose or Kubernetes. To support these two methods of deploying multi-container applications, there are two separate Atlas architectures: Atlas for Docker Compose and Atlas for Kubernetes.
How do I get started with Atlas?Contact us to get started with a full trial of Atlas.
Installing Atlas
How do I install Atlas?
You can install Atlas for Docker Compose using the Atlas installer command-line utility. You can install Atlas for Kubernetes using the Mapbox Helm chart. See the Atlas documentation for detailed installation instructions.
Can I use Atlas on my own private cloud?Yes! You can install Atlas on your own private cloud, including Amazon Web Services (AWS), Google Cloud Platform (GCP), or Microsoft Azure.
Which operating systems does Atlas support?macOS (development use only)
Ubuntu 16.04
Ubuntu 18.04
Ubuntu 20.04
CentOS 7
Red Hat Enterprise Linux 7
Red Hat Enterprise Linux 8
What are the hardware requirements for Atlas?We recommend the following minimum hardware configuration for production Atlas instances:
4 CPU cores
16 GB RAM
2 TB SSD
For testing and development of Atlas we recommend:
2 CPU cores
8 GB RAM
60 GB SSD
How do I upgrade from Atlas v1?To upgrade your web applications you’ll need to switch from classic styles to GL styles. We recommend switching from Mapbox.js to Mapbox GL JS. Alternatively, you can use L.mapbox.styleLayer in Mapbox.js to load GL styles. Contact Mapbox support (help@mapbox.com) to receive a detailed upgrade and migration guide.
Atlas for Kubernetes
What is Atlas for Kubernetes?
Mapbox Atlas is now built with support for Kubernetes, a container orchestration platform. Atlas for Kubernetes provides features for organizations that need enterprise-level availability, scalability, and disaster recovery. Kubernetes also makes Atlas easier to install, manage, and upgrade.
What is Kubernetes?Kubernetes is an open-source container orchestrator that lets developers automate the process of deploying, scaling, and managing containerized applications. It supports Docker as well as other container technologies such as rkt, cri-o, kata, and virtlet.
For the first time, Atlas for Kubernetes gives you the option of running Atlas at scale, with built-in redundancy and load balancing. Atlas for Kubernetes allows you to scale horizontally across several running containers, in addition to the vertical scaling previously possible with Atlas on Docker Compose.
Atlas for Kubernetes requires a cluster running a current version of Kubernetes. For development, Atlas for Kubernetes requires a cluster with 4 CPUs, 8GB RAM, and 100GB of disk space. Production clusters can vary in size based on capacity and scaling factor, but the minimum requirements are 8 CPUs, 16GB RAM, and 1.5TB of disk space.
Once you have provisioned your cluster with sufficient resources (see “What are the system requirements for Atlas for Kubernetes?”), make sure that Helm is installed and that you have an Ingress available.
We distribute Atlas for Kubernetes as a Helm chart. The Helm client will fetch the chart from the Mapbox private Helm repository at install time, so in most cases you do not need to download the chart in advance. For instructions on how to install Atlas for Kubernetes, visit .
How do I use Atlas for Kubernetes?Once installed, you can use Atlas for Kubernetes the same way you would use other versions of Atlas via the Mapbox APIs or Mapbox Studio. Navigate to your configured Atlas URL in a web browser, log in using the credentials you set during installation, and access Mapbox Studio, the Atlas Toolkit, and the Atlas Account Dashboard.
We expose private Docker repositories for customers to download Docker images. The Helm chart will automatically authenticate to our registry using your Mapbox token and save the docker-registry secret in the Kubernetes cluster. For air-gapped environments we suggest you mirror our repository or use your own private repository as a proxy.
You can download production data for Atlas for Kubernetes by using the scriptdownload strategy in our Helm chart. This will fetch data directly from our data API. For air-gapped environments you will need to prefetch data and make it accessible for download from within the cluster. For ease of use with development data, we also provide an image download strategy that bundles testing data in a Docker image.
How do I update Atlas for Kubernetes?When a new version of Atlas for Kubernetes is available, download an updated Helm Chart and pull new container images from the registry. Use Helm to automatically update the existing deployment. With Kubernetes, you can perform rolling updates of Atlas without taking downtime. For instruction on how to update Atlas for Kubernetes, visit .
Atlas supports current versions of Kubernetes.
Does Atlas for Kubernetes support federated clusters?Atlas does not yet support the alpha release of Kubernetes Cluster Federation.
Atlas for Kubernetes can be installed and configured with the Mapbox Helm chart on any Kubernetes platform, including the following list. For a full list of official and beta supported platforms visit .
AWS Elastic Kubernetes Service
Red Hat OpenShift
Azure Kubernetes Service
Google Kubernetes Engine
Other public, private, on-premises environments
How do I deploy Atlas for Kubernetes with AWS?Before you install Atlas on Amazon Elastic Kubernetes Service, you will need to create and configure a cluster:
You can now install Atlas on the new EKS cluster (see “How do I download/install Atlas for Kubernetes?”).
Yes. Atlas for Kubernetes supports the Elastic Kubernetes Service, which is available on AWS GovCloud. For a full list of official and beta supported platforms visit .
Before you install Atlas on RedHat OpenShift, you will need to create and configure a cluster:
, for example using the atomic-openshift-installer tool
You can now install Atlas on the new OpenShift cluster (see “How do I download and install Atlas for Kubernetes?” above).
Atlas for Kubernetes includes built-in storage engines that run on a standard OS-mounted volume. You can also use an external storage solution such as an appliance.
Atlas can store user data on any datastore compatible with the Amazon DynamoDB API.
How do I configure high availability with Atlas for Kubernetes?Atlas uses Kubernetes’s built-in to provide high availability. Atlas services are automatically replicated and restarted if a failure occurs, and upgrades can automatically roll back in case of error. Atlas for Kubernetes supports several storage engines (see “How do I configure storage solutions with Atlas for Kubernetes?”) that provide redundancy.
Although there is not a single definition, a high availability system is one that is resilient to failure. A single failed component should not impact the entire system.
Atlas is a collection of many interdependent services, all of which need to be online for Atlas to be considered “available”. This includes the data storage backends, the Mapbox API containers, the caching layer, and the UI. Atlas can run in a limited capacity without the caching layer, but this causes severe performance impacts.
By using Kubernetes, we can run multiple pods of our API and UI containers so that a single pod failure does not impact service health. If a pod does fail, Kubernetes will automatically create a new pod to restore redundancy to the API service.
Atlas uses Kubernetes Ingress controllers and Services for load balancing. Kubernetes takes advantage of the appropriate load balancer for the environment (e.g. Application Load Balancers in AWS) and splits traffic to all available servers across the Atlas deployment
At this time, the caching layer and data storage backends do not support high availability in most cases. If those pods fail, Kubernetes will recreate the pod and restore service, but there will be an outage until the new pod becomes healthy.
Atlas relies on the Kubernetes cluster and underlying storage and network resources. You should design your Kubernetes deployment to meet your application’s availability and recovery objectives. The most important consideration for Atlas is ensuring that all persistent volumes are backed by highly available storage.
How do I back up and restore Atlas for Kubernetes?You can back up Atlas data by taking snapshots of the Atlas data volumes. These volumes contain all tileset and style data, as well as user tokens and settings. To ensure a consistent backup, we recommend stopping Atlas or putting volumes in a read-only state before taking a snapshot.
Yes, Atlas uses the on all API requests. Contact sales if you would like to increase these limits.
Atlas for Kubernetes is available for all Atlas Basic, Standard, and Enterprise licenses at no additional cost. Using Atlas for Kubernetes with high-availability requires an Atlas Enterprise license. Contact sales to learn more about Atlas pricing.
If you are a current Atlas customers, you can get started with the Atlas for Kubernetes documentation. New customers will need to contact sales to get started with an Atlas license or trial.
Using Atlas
Can I use Mapbox Studio with Atlas?
Yes, Atlas Standard and Atlas Enterprise include Mapbox Studio.
Which styles are available with Atlas?Can I use custom tilesets with Atlas?Yes! You can use custom tilesets (MBtiles files) in the on-premises version of Studio available in Atlas. You can use Tippecanoe or GDAL to create these tilesets before adding them to your Atlas instance.
Atlas Search
What is Atlas Search?
Atlas Search enables offline global address level geocoding in an Atlas installation. Turn location text like addresses, cities, and countries into coordinates (forward geocoding) and vice versa (reverse geocoding).
Why should I use Atlas Search?Add global address level geocoding to offline web, desktop, and mobile applications. Batch forward and reverse geocode large datasets. Quickly search for locations instead of manually panning or zooming. Find locations even with incomplete or misspelled queries using autocomplete and fuzzy search. For example, develop an asset tracking solution on an air-gapped network using sensitive sensor data. Geotag content datasets like videos or images to visualize them on the map and drill down to the address level. Or, build a dynamic resource locator to search and display assets based on bounding boxes or proximity to a given address.
Does Atlas Search have the same features as mapbox.com search?Atlas Search supports the same features as Mapbox.com Search, but completely offline. This includes autocomplete, bounding boxes, fuzzy search, languages, and proximity. However, Atlas Search does not include points of interest (POIs).
What countries are available with Atlas Search?Atlas Search has the same global coverage as Mapbox Search except for Japan, and Canada.
Country
Restrictions
Italy
Up to city level only
Japan
Up to city level only
Canada
Up to city level included, addresses available for an additional fee
No, Atlas Search does not include points of interest (POIs).
Can I add my own data to Atlas Search?No, you cannot upload your custom data and query it from Atlas Search.
How often is Atlas Search data updated?All Atlas Search customers receive complimentary yearly updates upon renewal with the option to purchase quarterly or monthly updates.
How do I purchase Atlas Search?Atlas customers can purchase Atlas Search for an additional charge. Talk to our sales team to add Atlas Search to your Atlas license.
How do I download Atlas Search updates?Use the Atlas Installer’s download command to download Atlas Search updates. This command requires internet access. After downloading you can copy the data to your on-premises or offline Atlas installation.
How do I add Atlas Search to my existing Atlas installation?After buying and downloading Atlas Search, rerun the setup command from the Atlas Installer. This will update your Atlas license and configure Docker containers for Atlas Search.
What are the system requirements for Atlas Search?Atlas Search uses an additional 70 GB of disk space and 8 GB of RAM.
Atlas Boundaries
What is Atlas Boundaries?
Atlas Mapbox Boundaries adds administrative, postal, and statistical boundaries to your maps, dashboards, and data visualizations. Atlas Boundaries consists of multiple data layers that come cartographically-matched, georeferenced, and processed as a Mapbox tileset ready for integration with your maps and data.
Why should I use Atlas Boundaries?Atlas Boundaries facilitates data-driven decision making by enabling you to join custom data with global and local boundary polygons. For example:
A regional disaster response center can use city and county boundaries to determine jurisdiction for emergency response.
An Autonomous vehicle company can use administrative boundaries to track mobile asset compliance with varying local, state, and national laws.
A utility or energy company can visualize and assess localities affected by transmission infrastructure planning.
A business intelligence platform can help customers to do any of the above.
Atlas Boundaries lets you visualize your data by country, region, sub-region, or post code to unlock insights within your own application. You can:
All of this can happen completely offline.
How do I buy Atlas Boundaries?Atlas Boundaries is an additional charge on your current Atlas Standard or Enterprise license. Talk to our sales team or your Mapbox sales representative to add Boundaries to your license.
How do I download Atlas Boundaries?After buying you can use the Atlas installer to download Atlas Boundaries by running the
How do I use Atlas Boundaries?Follow this getting started guide to begin building maps with Atlas Boundaries.
How do I add Atlas Boundaries to a map style in Atlas Studio?To add Atlas Boundaries to a map style in Atlas Studio, select the “Add Layer” button and view the “Sources” tab. Next, add the tilesets as a layer within a map by selecting specific boundary tilesets from the list of Boundary tilesets. Additional information is covered in the Boundaries getting started guide.
What data is available in Atlas Boundaries?Atlas Boundaries offers the same data as Boundaries on mapbox.com.
What version of Boundaries comes with Atlas?Atlas Boundaries uses v3 of Mapbox Boundaries.
What are the system requirements for Atlas Boundaries?We recommend an additional 10 GB of storage on top of
How do I upgrade or update Atlas Boundaries data?To upgrade or update Atlas Boundaries data on an existing Atlas installation you would use the download command in the . The command will download the latest version of Atlas Boundaries. After the download is completed you will have to run the setup command to move the new tilesets into your Atlas instance tileset directory. A detailed guide to this process is available in
Developing with Atlas
Which Mapbox APIs come with Atlas?
Currently only API calls with public access tokens (pk.* tokens) are supported.
Can I use Mapbox GL JS with Atlas?Yes, you can use Mapbox GL JS with Atlas. To get started, replace mapboxgl.accessToken with an Atlas access token and set mapboxgl.config.API_URL to the URL of your Atlas server.
Can I use Mapbox.js with Atlas?Yes, you can use Mapbox.js with Atlas. To get started, set L.mapbox.accessToken to an Atlas access token and set L.mapbox.config.HTTPS_URL to the URL of your Atlas server.
Only GL styles with L.mapbox.styleLayer are supported. See Using Your Mapbox Studio styles everywhere. Mapbox Studio Classic styles and legacy styles are not supported.
Can I use Leaflet with Atlas?Yes, you can use raster tiles served by Atlas with Leaflet.
When adding a L.tileLayer, point it to a style on your local Atlas instance and pass in your token:
L.tileLayer(ATLAS_STYLE_URL + 'tiles/{z}/{x}/{y}?access_token=' + YOUR_ACCESS_TOKEN).addTo(map);
Note that Leaflet only supports raster tiles, so this will be fetching raster tiles from Atlas, not . See here for a more thorough example.
Can I use the Maps SDK for iOS with Atlas?Yes, you can use the Maps SDK for iOS with Atlas.
Can I use the Maps SDK for Qt with Atlas?Yes, you can use the Maps SDK for Qt with Atlas.
Can I use the Maps SDK for Unity with Atlas?Yes, you can use the Maps SDK for Unity with Atlas.
Which versions of Mapbox GL JS and Mapbox.js are available with Atlas?Versions 0.40 through 2.2.0 of Mapbox GL JS
Versions 2.0 through 3.1 of Mapbox.js
Data
What data is available with Atlas?
All Atlas installations come with the following complimentary datasets:
Higher zoom levels and other data sets are available. Contact sales for more information.
Can I use the Mapbox Terrain-RGB tileset with Atlas?Yes!
What are the file sizes for each tileset?Below are approximate sizes for each tileset. Exact tileset file sizes are subject to change with new data from weekly updates.
DatasetDevProductionHigh-Resolution
Terrain-v2 1 GB 40 GB 820 GB
Streets-v7 300 MB 125 GB Not Available
Streets-v8 300 MB 250 GB Not Available
Countries-v1 1 MB 1.5 GB Not Available
Satellite 1 GB 225 GB 2 TB
Terrain-RGB 1.5 GB 450 GB 3.1 TB
Boundaries Not Available 15 GB Not Available
Search 5 GB 75 GB Not Available
Navigation 100 MB 50 GB Not Available
Total 9 GB 1.2 TB 6.5 TB
All Atlas installations come with complimentary yearly updates of our Mapbox Streets data set. If you want more frequent updates (weekly, monthly, or quarterly), please contact sales.
Can I use high resolution satellite imagery with Atlas?Yes! Contact sales if you’d like to purchase high resolution satellite imagery for Atlas. You can also use GDAL to convert your existing imagery to MBTiles to use in Atlas.
Security and access control
What access tokens do I use with Atlas?
Atlas uses a local public access token that is unique to your Atlas installation. You can use this token to build with Mapbox GL JS and serve your Atlas maps on your infrastructure.
Does Atlas support secret access tokens?No, at this time Atlas does not support secret access tokens (sk.*).
Can I use Mapbox.com access tokens with Atlas?No, you cannot use Mapbox.com access tokens with your Atlas installation. You can only use local Atlas access tokens with your Atlas installation.
Does Atlas support HTTPS?Yes, Atlas supports HTTPS natively without needing to configure a separate proxy server. You can use your own TLS certificates with Atlas. Atlas will also generate temporary self-signed certificates for testing and development purposes only.
How many user accounts are available with Atlas?At the moment Atlas only supports one user account (atlas-user). Multiple user accounts are currently on our roadmap.
Can I change the password for the Atlas user?Yes, to change the Atlas password, open the config file and set the desired password in the atlasUserPassword field. Then restart Atlas. You can find more details in .
Can I change the port and hostname of my Atlas server?Yes, to change the port and hostname, open the config file and set the desired port and hostname values. Then restart Atlas. You can find more details in .
