HOWTO: Use Podman instead of Docker for local builds and uploading container images

If for any reason including but not limited to:

  • not needing root or privileged group (docker) access to do local builds and uploads.
  • being diametrically opposed to running a privileged daemon just so you can build some glorified tarballs.
  • thinking: how is this a client-server architecture thing for just building a friggin image!?
    …you may want to use Podman for your related container image building needs.

So I wondered, can I just use Podman without installing anything from Docker and not requiring any root permissions?

Let’s start with just the ability to being able to deploy a locally built image.
Good folks at Fly allowed direct uploads to their registry at
Neat! Let’s build the image locally and upload it to Fly’s registry.

% podman build -t example-app .
% podman push example-app docker://
Error: error copying image to [...] unauthorized: authentication required.

Oh. Duh. Okay. How do we do that? I recall seeing docker mention under flyctl auth command help. Let’s do that.

% flyctl auth docker
Error unknown command "docker" for "flyctl"

Huh. So flyctl looks for Docker CLI but we don’t have it.

Update (2021-01-09):
As @michael pointed in the thread required registry credentials are just the auth token and username is ignored. We can ask for our token from flyctl instead of getting it do the credential passing for us.

flyctl auth token | podman login -u x –password-stdin

You can ignore this part from the original post:

Remember I said podman is CLI compatible with docker? Let’s see if we can get flyctl to not worry too much.

% ln -s $(which podman) ~/.local/bin/docker
% export PATH=$HOME/.local/bin:$PATH
% flyctl auth docker
Authentication successful. You can now tag and push images to{your-app}

Nice! Let’s try pushing again.

% podman push example-app docker://
Getting image source signatures
Storing signatures

Awesome. Can we deploy now?

% flyctl deploy -i
==> Validating App Configuration
==> Validating App Configuration done
TCP 80/443 ⇢ 8080
==> Creating Release
Error not a valid image:

“Not a valid image”? I’m certain it’s valid. After all "it works on my laptop"™. :nerd_face:

Podman defaults to building OCI format container images but supports Docker image manifest v2 and schemas v1 and v2 as well. Let’s try something more Dockery; maybe deployment portion expects squarely-Docker image manifest and schema.

% podman push --format v2s2 example-app docker://
Getting image source signatures
Writing manifest to image destination
Storing signatures

% flyctl deploy -i
==> Validating App Configuration
1 desired, 1 placed, 1 healthy, 0 unhealthy [health checks: 1 total, 1 passing]
--> v13 deployed successfully


tl;dr – just give me the commands


1. Pass your registry credentials to Podman

% flyctl auth token | podman login -u x –password-stdin

2. Build Locally

% podman build -t example-app .

3. Upload

podman push --format v2s2 example-app docker://<ver>

Either use a specific version tag for <ver> or you can use customary latest.

4. Deploy

Either edit fly.toml to change the builder to image:

  image = ""

…or you can pass the image to flyctl directly.

% flyctl deploy -i

Can I get flyctl do local a build with Podman too?

I don’t know, yet. For this functionality flyctl wants to connect to local Docker daemon. Although Podman supports a client-server model like Docker over a Unix domain socket, I don’t know if it speaks a compatible protocol so flyctl can get its bidding done. I will likely make a follow up to this post about this.


That’s really cool, nice detective work :slight_smile: A few people asked about Podman, now we have something to send them to. Thanks for sharing!

It’s surprisingly simple, but the symlink and export step is gross. Thankfully you can login to podman directly using the token from flyctl:

flyctl auth token | podman login -u x –password-stdin