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 Image | Image Tags | Purpose |
---|---|---|
Distroless | latest , latest-distroless | Bare bone image containing only Atlas |
Alpine | latest-alpine | Alpine 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:
Run:
docker run --rm -it \
-v ~/.atlas:/root/.atlas \
arigaio/atlas:latest loginAtlas 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.)Visit the URL in your browser and follow the on-screen instructions.
Copy the code provided by Atlas Cloud:
Paste the code back into the terminal where you ran
atlas login
and hit<ENTER>
:Please enter the auth code:
Atlas will verify your code and provide you with a success message:
You are now connected to acme-corp-1337-ltd on Atlas Cloud.
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.
- Create a Docker Network to establish network connectivity between your local DB and Atlas:
docker network create db-network
- Run the database:
docker run --name pg-dev-db --network db-network -e POSTGRES_PASSWORD=mysecretpassword -d postgres:16
- Use the new dev db:Note a few things about this command:
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"
- 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 hostnamepg-dev
was specified in step 2 as the container name.