Skip to main content

Why docker:// does not work inside the Atlas Docker image

Question​

Why does using a dev URL like docker://postgres/15/dev inside the official arigaio/atlas image fail with: exec: "docker": executable file not found in $PATH?

Answer​

Commands that use docker:// dev-database URLs (such as schema diff, schema apply, and migrate test) fail when run inside the Atlas Docker image. This is expected behavior.

The docker:// scheme requires Atlas to run the docker client to start a temporary database container. The official Atlas image is minimal and does not include the docker binary. Additionally, the Docker daemon is unreachable from inside the container unless explicitly mounted.

Where docker:// URLs Work​

The docker:// scheme is supported when:

  • Running Atlas directly on a machine where docker is installed
  • Running Atlas in a CI environment where docker is available (both docker client and docker daemon)
  • Using custom container images that include the docker client and have access to the host docker daemon

In container-based platforms (Kubernetes, ECS, CI runners, etc.), it is not recommended for a container to spin up other containers on the host. Instead:

  1. Run a separate dev database container
  2. Pass its connection URL to the Atlas container

For example:

env "local" {
  url  = getenv("DATABASE_URL")
  src  = "file://schema"
  dev  = "postgres://user:pass@dev-db:5432/dev?sslmode=disable"
}

This keeps Atlas isolated and avoids granting containers permissions to manage host resources.

Advanced Workaround​

If docker:// must be used inside a container, you can provide the docker CLI and daemon access to the Atlas container. For example:

docker run \
  --volume=/usr/local/bin/docker:/usr/local/bin/docker:ro \
  --add-host="host.docker.internal:$DOCKER_HOST" \
  arigaio/atlas:latest

This approach mounts the docker client into the container and requires the host docker daemon to be reachable (e.g., via host.docker.internal in Docker Desktop, or by mounting /var/run/docker.sock on Linux). This is an advanced setup and not recommended for most CI or container environments. Configuration details vary by platform (Bitbucket Pipelines, GitHub Actions, GitLab CI, etc.).

Have additional questions or feedback? Feel free to reach out on our Discord server.