Configure Atlas

Note

These instructions apply for Atlas version: 2.6.0

All configuration is contained within a single file found in the Atlas root: config. This self documenting configuration file will be explained in this guide.

The default configuration

# These variables describe the administrator. Typically only
# "atlasUserPassword" is changed:
atlasUserPassword=password
atlasUserEmail=atlas-user@mapbox.com
atlasUsername=atlas-user

# This is the URL where users will be accessing Atlas
# This could be
# - the machine's local IP Address
# - the DNS name of your load balancer
# - etc
atlasURL=http://localhost:2999

# This is the port and protocol that the Atlas Docker
# container will listen on.
#
# If https is used, Atlas will expect SSL certificates to be placed
# in the $ATLAS_ROOT/ssl_cert folder with names:
# - cert.pem
# - key.pem
atlasPort=2999
atlasProtocol=http

# READ ONLY
# These environment variables describe the hostnames
# where each service can be found, respectively:
ddbEndpoint=http://atlas-ddb:4567
memcachedServer=memcached:11211
s3Endpoint=http://atlas-s3:4568
redisHost=redis
redisPort=6379

# READ ONLY
# These environment variables propagate to the UI
# and describe your current release.
atlasVersion=v2.6.0
atlasVersionDate=2020-01-24T15:21:59.152Z

Configuration reference

  1. atlasUserPassword should be changed and is generally only shared with Atlas administrators.
  2. atlasURL also varies per installation and could be a local IP address or a public DNS hostname.
  3. atlasPort is the port on which Atlas will bind to on the host machine.
  4. atlasProtocol is the protocol Atlas will listen on using Nginx.
Read Only

In general the other configuration properties should be treated as read-only.

Configure Atlas password

The password used to login to the Atlas Account page, Studio, and other resources should be changed from the default. To change this,

  1. Open the config file and set the desired password in the atlasUserPassword field.
  2. Restart Atlas: .\atlas.sh stop && .\atlas.sh start.

Configure HTTPS

Atlas can be configured to communicate using HTTPS for increased security. In production use, the certificate file should be signed by a trusted Certificate Authority. For ease of testing, we also provide a script to generate a self-signed certificate.

  1. Edit the configuration:

    1. Open ./config.
    2. Change atlasURL to start with the https protocol (e.g., https://localhost:2999).
    3. Change atlasProtocol to https.
    4. Save and close the file.
  2. Save the certificate:

    • If you have a signed certificate:

      1. Save the private key (in PEM format) to ./ssl_cert/key.pem.
      2. Save the certificate (in PEM format) to ./ssl_cert/cert.pem.
    • If you want to create a self-signed certificate:

      1. cd to the Atlas root directory and run ./atlas.sh create-certificate. This will store the necessary files in ./ssl_cert for you.
  3. Restart Atlas: ./atlas.sh stop && ./atlas.sh start

For example, to configure HTTPS with a self-signed certificate, you would run:

sed -i .bak -e 's/atlasURL=http:/atlasURL=https:/;s/atlasProtocol=http$/atlasProtocol=https/' config
./atlas.sh create-certificate
./atlas.sh stop && ./atlas.sh start

Configure HTTP

Atlas can be configured to communicate by unencrypted HTTP if it has previously been configured with HTTPS.

  1. Edit the configuration:

    1. Open ./config.
    2. Change atlasURL to start with the http protocol (e.g., http://localhost:2999).
    3. Change atlasProtocol to http.
    4. Save and close the file.
  2. Restart Atlas: ./atlas.sh stop && ./atlas.sh start

For example, to configure HTTP, you would run:

sed -i .bak -e 's/atlasURL=https:/atlasURL=http:/;s/atlasProtocol=https$/atlasProtocol=http/' config
./atlas.sh stop && ./atlas.sh start

Run Atlas behind a reverse proxy

A common configuration is to have Atlas served over HTTP and behind an HTTPS reverse proxy. Because some services within Atlas advertise URIs to the client, you will need to configure Atlas to advertise the correct URI. These environment variables populate those URIs within the services.

  1. Stop Atlas: ./atlas.sh stop
  2. Edit ./config
  3. Update the atlasURL variable with your public hostname or load balancer address.
  4. Update atlasProtocol & atlasPort as needed.
  5. Start Atlas: ./atlas.sh start
Was this page helpful?