メインコンテンツまでスキップ

Getting Started with Mapbox Atlas

This getting started guide shows how to install and set up a local development Atlas v3 installation with Mapbox Streets. This includes downloading Atlas v3 assets and the Streets development tileset, setting up the Streets map style, and configuring a local server with Docker and Nginx.

When you are ready to deploy to production, review Deploy to production for production deployments using AWS S3 or Nginx.

Prerequisites​

  • A Mapbox access token with the atlas:read scope. See access token for instructions.
  • Docker Compose
  • 5 GB of free disk space for the development tilesets.

Download the Atlas installer​

Documentation conventions
In this guide, we used atlas-installer as the installer name. Depending on which target OS you selected the installer will be named differently. To simplify the documentation, we will use atlas-installer for the rest of the documentation.
  1. Go to atlas.mapbox.com/install.
  2. Download the Atlas installer for your operating system (macOS or Linux).
  3. Unzip the binary and mark it as executable:
$unzip atlas-installer.zip
$chmod +x ./atlas-installer

Run the Atlas installer​

Start the guided Atlas installer:

$./atlas-installer install

When prompted:

  1. Choose Atlas v3 for the major version (selected by default).
  2. Paste your atlas:read access token.
  3. Select the latest version of Atlas v3 to download.
  4. For data and tilesets to download, select Assets, Mapbox GL JS Library, and Mapbox Streets v8. These are the default selections.
  5. Select the latest version of Mapbox GL JS.
  6. Select yes for downloading development data.
  7. Select yes or no for verifying tileset checksums. Verifying tileset checksums is optional.
  8. Select yes for running Atlas on this machine.
  9. Keep the default atlas-server directory name for where you plan to install Atlas.

If you would prefer to run the Atlas installer programmatically, you can run the following command:

$./atlas-installer download ./atlas-server \
    --token <your-atlas-token> \
    --version <Atlas version>
    --dev \
    --tilesets streets

Inspect the Atlas v3 directory​

The Atlas installer downloads:

  • The Atlas v3 assets bundle, which includes fonts, spritesheets, and default Mapbox map styles.
  • Tilesets
  • Mapbox GL JS

After the Atlas installer finishes downloading Atlas v3, the atlas-server directory should look like this:

atlas-server/
├── data/
│   ├── fonts/
│   ├── sprites/
│   ├── styles/
│       └── mapbox/
│   ├── tilesets/
├── mapbox-gl-js/
│   ├── plugins/
└── mapbox-gl.css
└── mapbox-gl.js

Set up Mapbox GL JS​

In the atlas-server directory, create a new index.html file with the following HTML and JavaScript code.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Atlas v3</title>
    <link rel="stylesheet" href="./mapbox-gl.css" />
    <script src="./mapbox-gl.js"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      mapboxgl.accessToken = 'YOUR_ATLAS_V3_LICENSE';

      mapboxgl.baseApiUrl = 'http://127.0.0.1:8080/';

      const map = new mapboxgl.Map({
        container: 'map',
        style: 'http://127.0.0.1:8080/data/styles/mapbox/streets-v12.json',
        center: [-74.5, 40],
        zoom: 9
      });
    </script>
  </body>
</html>

Set up the Streets v12 style​

In a text editor, open the Streets v12 style.json file, which is located at /atlas-server/data/styles/mapbox/streets-v12.json.

First, update lines 2-3 for sprites and glyphs to point to the local server hosted at http://127.0.0.1:8080:

  "sprite": "http://127.0.0.1:8080/data/sprites/streets-v12",
  "glyphs": "http://127.0.0.1:8080/data/fonts/mapbox/{fontstack}/{range}.pbf",

Then update the url of the tileset source (sources) on line 4548 to point to the development Mapbox Streets v8 tileset located in /atlas-server/data/tilesets.

      "url": "http://127.0.0.1:8080/data/tilesets/mapbox.mapbox-streets-v8-20260210-dev.pmtiles",

Set up Nginx​

We will set up an Nginx server to set up the correct headers for Atlas v3. For convenience, this guide uses Docker Compose to set up Nginx. This sets up a local web server running on port 8080 accessible at http://127.0.0.1:8080.

You will need to create three files in the atlas-server directory:

  • docker-compose.yml
  • Dockerfile
  • nginx.conf

Copy and paste the content below into the appropriate files:

docker-compose.yml​

services:
  atlas:
    build: .
    ports:
      - "8080:80"
    volumes:
      - ./data:/usr/share/nginx/html/data:ro
      - ./mapbox-gl-js:/usr/share/nginx/html/mapbox-gl-js:ro
    restart: unless-stopped

Dockerfile​

FROM nginx:alpine

COPY nginx.conf /etc/nginx/conf.d/default.conf

COPY index.html          /usr/share/nginx/html/
COPY mapbox-gl.js        /usr/share/nginx/html/
COPY mapbox-gl.css       /usr/share/nginx/html/

EXPOSE 80

nginx.conf​

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    # ------------------------------------------------------------------
    # CORS — required when serving data files from a different origin
    # than the page hosting index.html. If everything is on the same
    # origin you can remove the add_header and if ($request_method) block.
    # ------------------------------------------------------------------
    add_header Access-Control-Allow-Origin  "*" always;
    add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Range" always;
    add_header Access-Control-Expose-Headers "Content-Length, Content-Range" always;

    # Handle CORS preflight requests
    if ($request_method = OPTIONS) {
        return 204;
    }

    # ------------------------------------------------------------------
    # PMTiles — must support Range requests; do NOT gzip (breaks offsets)
    # ------------------------------------------------------------------
    location ~* \.pmtiles$ {
        gzip off;
        types { application/octet-stream pmtiles; }
        add_header Accept-Ranges          bytes always;
        add_header Cache-Control           "public, max-age=86400" always;
        # Re-add CORS (location-level add_header overrides server-level)
        add_header Access-Control-Allow-Origin  "*" always;
        add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Range" always;
        add_header Access-Control-Expose-Headers "Content-Length, Content-Range" always;
    }

    # ------------------------------------------------------------------
    # Font glyphs (Protocol Buffer files)
    # Files on disk are pre-gzipped; Content-Encoding tells the browser
    # to decompress on the fly so Mapbox GL JS receives raw protobuf.
    # ------------------------------------------------------------------
    location ~* ^/data/fonts/.*\.pbf$ {
        types { application/x-protobuf pbf; }
        add_header Content-Encoding        "gzip" always;
        add_header Cache-Control           "public, max-age=604800" always;
        add_header Access-Control-Allow-Origin  "*" always;
        add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
    }

    # ------------------------------------------------------------------
    # Sprites and style JSON
    # ------------------------------------------------------------------
    location ~* \.(json|png)$ {
        add_header Cache-Control           "public, max-age=86400" always;
        add_header Access-Control-Allow-Origin  "*" always;
        add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS" always;
    }
}

Start the server​

Run docker compose up in the atlas-server directory to build the Docker image and start Nginx.

Open the map​

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

Open http://127.0.0.1:8080/ in a web browser. You should see an interactive Mapbox map rendered entirely from files on your development machine.

If the map does not load, open the browser developer tools and check for any CORS or 404 errors. The server must return 206 Partial Content for range requests and include Access-Control-Allow-Origin: * (or the equivalent for your origin).

Next steps​

このpageは役に立ちましたか？