Skip to main content

Running Atlas in Docker

Atlas ships as a set of official Docker Images for you to use.

To run Atlas in Docker, execute:

docker run --rm -it arigaio/atlas:latest-alpine

Depending on your use case, you may want to use a different image type:

Base ImageImage TagsPurpose
Distrolesslatest, latest-distrolessBare bone image containing only Atlas
Alpinelatest-alpineAlpine based image, with basic shell (/bin/sh)

Common Issues​

Use 'atlas login' to access this feature​

Atlas is an open-core project, with some features available only to signed-in users. To use these features, you must sign in to Atlas. To sign in:

  1. Run:

    docker run --rm -it \
      -v ~/.atlas:/root/.atlas \
      arigaio/atlas:latest login

  2. Atlas will provide you with a URL to visit in your browser:

    Please visit:

    https://auth.atlasgo.cloud/login?cli=ade66529-e6c0-4c56-8311-e23d0efe9ee9&port=33281

    Follow the instructions on screen. (Hit <ENTER> to manually provide the code.)

  3. Visit the URL in your browser and follow the on-screen instructions.

  4. Copy the code provided by Atlas Cloud:

  5. Paste the code back into the terminal where you ran atlas login and hit <ENTER>:

    Please enter the auth code:

  6. Atlas will verify your code and provide you with a success message:

    You are now connected to acme-corp-1337-ltd on Atlas Cloud.

  7. You can now use Atlas features that require authentication. Use the -v ~/.atlas:/root/.atlas flag to persist your login credentials across Docker runs. For example:

     docker run --rm -it \
       -v ~/.atlas:/root/.atlas \
       arigaio/atlas:latest-alpine schema inspect --url "<url>"

"docker": executable file not found in $PATH​

Atlas heavily relies on the presence of a Dev Database for various calculations and schema normalization. To use a Dev Database, users provide Atlas with the URL to connect to an empty database of the type they wish to operate on.

To streamline work with Dev Databases, Atlas provides a convenience driver named docker://, in which Atlas depends on the Docker CLI command docker to be present in the runtime environment. Running Docker-in-Docker is a notoriously nuanced topic and so we do not ship docker in the distributed Atlas images.

For this reason, Atlas users who wish to run Atlas in Docker, cannot, by default use the docker:// driver.

Workaround: Spin up a local database container and use it​

A common workaround is to spin up a local, empty database container and connect to it.

  1. Create a Docker Network to establish network connectivity between your local DB and Atlas:
    docker network create db-network
  2. Run the database:
    docker run --name pg-dev-db --network db-network -e POSTGRES_PASSWORD=mysecretpassword -d postgres:16
  3. Use the new dev db:
    docker run --rm --network db-network \
      -v $PWD:/data \
      arigaio/atlas migrate diff \
      --to file:///data/schema.hcl \
      --dir file:///data/migrations \
      --dev-url "postgres://postgres:mysecretpassword@pg-dev:5432/postgres?sslmode=disable"
    Note a few things about this command:
  • We use the --network flag to use the network we created for our dev database on step 1.
  • We mount our local dir as /data
  • We use the URL for our dev database as the --dev-url flag, note that the hostname pg-dev was specified in step 2 as the container name.