Skip to main content

Run the Astro CLI using Podman

The Astro CLI requires a container management engine to run Apache Airflow components on your local machine and deploy to Astro. For example, the astro dev start and astro deploy commands both require containers.

By default, the Astro CLI uses Docker as its container management engine. However, if your organization uses Podman to run and manage containers, you can configure the Astro CLI to use it instead. Podman is a secure, free, and open source alternative to Docker that doesn't require root access and orchestrates containers without using a centralized daemon.

Configure the Astro CLI to use Podman​

Set up Podman on a Mac operating system so you can run Apache Airflow locally and deploy to Astro with Podman containers.

Prerequisites​

  • Podman 3 or later. See Getting started with Podman.
  • A running Podman machine with at least 4 GiB of RAM. To confirm that Podman is running, run podman ps.
  • (M1 MacOS) Turn on rootful mode for Podman by using podman machine set --rootful. A Podman bug currently causes issues with volumes when running in rootless mode on M1.
tip

If you receive an error after running podman ps, there is likely a problem with your Podman connection. You might need to set the system-level DOCKER_HOST environment variable to be the location of your Podman service socket:

  1. Run the following command to identify the connection URI for podman-machine-default:

    podman system connection ls

    The output should look like the following:

    podman-machine-default*      /Users/user/.ssh/podman-machine-default  ssh://core@localhost:54523/run/user/1000/podman/podman.sock
    podman-machine-default-root  /Users/user/.ssh/podman-machine-default  ssh://root@localhost:54523/run/podman/podman.sock

  2. Copy the value in the URI column from podman-machine-default*. This is typically unix:///run/podman/podman.sock, but it can vary based on your installation.

  3. Set your DOCKER_HOST environment variable to the value of the URI.

Setup​

  1. Run the following command to confirm that Podman has access to Astro images at docker.io:

    podman run --rm -it postgres:12.6 whoami

    If this command fails, use Podman Desktop to change Podman's default image registry location to docker.io. See Provide pre-defined registries.

For CLI versions 1.30.0 and earlier

Run the following command to set Podman as your container management engine for the Astro CLI:

astro config set -g container.binary podman

If you're using Podman 3, additionally run the following command:

astro config set -g duplicate_volumes false

Troubleshooting​

SHELL is not supported for OCI image format​

WARN[0010] SHELL is not supported for OCI image format, [/bin/bash -o pipefail -e -u -x -c] will be ignored. Must use `docker` format

This error can occur when the CLI tries to build your Astro Runtime image using Podman.

To resolve this issue, run the following command to set the BUILDAH_FORMAT environment variable on your machine:

export BUILDAH_FORMAT=docker

Cannot connect to the Docker daemon​

Error: error creating docker-compose project: Cannot connect to the Docker daemon at unix:///Users/[YOUR.USER]/.docker/run/docker.sock. Is the docker daemon running?

Ensure Docker Compatibility is enabled in Settings > Preferences > Experimental (Docker Compatibility) and Docker CLI Context is set to unix://var/run/docker.sock.

Configure Podman Docker Compatibility

"docker-credential-desktop": executable file not found​

Error: error reading credentials: error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: ``

This error can occur when Docker used to be installed, but no longer exists on the system. When podman runs, it is checking $HOME/.docker/config.json for registered credentials stores.

To resolve the issue, delete the corresponding Docker configuration at $HOME/.docker from the system or install Docker again.

Further info can be found here.

Switch between Docker and Podman​

After you set up the Astro CLI to use Podman on your local machine, the CLI automatically runs Podman containers whenever you run a command that requires them. To revert to the default behavior and run CLI commands in Docker containers, run the following command:

astro config set container.binary docker

If you need to switch back to using Podman again, run the following command:

astro config set container.binary podman

Was this page helpful?