For the Forge Tunnel, Podman is not Docker

TL;DR; Podman won’t work with Forge Tunnel. Just skip ahead of needing a container for Forge Tunnel with Native Node.js runtime.

There have been a few threads about or mentioning Podman as replacement for Docker:

For those who might be unfamiliar, Podman claims:

Podman is a daemonless, open source, Linux native tool designed to make it easy to find, run, build, share and deploy applications using Open Containers Initiative (OCI) Containers and Container Images. Podman provides a command line interface (CLI) familiar to anyone who has used the Docker Container Engine. Most users can simply alias Docker to Podman (alias docker=podman) without any problems. Similar to other common Container Engines (Docker, CRI-O, containerd), Podman relies on an OCI compliant Container Runtime (runc, crun, runv, etc) to interface with the operating system and create the running containers. This makes the running containers created by Podman nearly indistinguishable from those created by any other common container engine.

The reasons for a Docker replacement may vary from developer to developer. For my part, I became interested in Podman when Docker changed the licensing terms of Docker Desktop (announced 2 years ago this month). So, with some sympathy for those few requests I dug into our Forge CLI source code and ran some experiments.

Node spawn doesn’t work with user aliases

As indicated above, the easiest way to substitute podman for docker is with an alias. However, this didn’t work for me. I would only get the mysterious Error: spawn ENOENT.

This happens because the Forge CLI calls docker as a command using Node.js spawn. But spawn doesn’t run inside the user shell, which means my alias defined in .zshrc isn’t available to the Forge CLI.

My first workaround was to put a Bash script named docker into my path, which redirects by doing podman $*. Node can find that.

Forge CLI checks Docker version number

Next, I was getting another common error message for Forge:

Tunnel redirects requests you make to your local machine. This occurs for any Atlassian site where your app is installed in the development environment. You will not see requests from other users.
Press Ctrl+C to cancel.

Checking Docker image... failed   
Cannot pull the tunnel image.

With the help of source code inspection, I found this is a rather complicated code block. While responsible for checking & pulling the docker image, that’s not really why it was failing. Forge CLI depends on Docker version >17.3 but Podman’s versioning doesn’t follow Docker’s. At time of writing, the latest Podman is 4.6 designed to work with Docker 24.

My next workaround was to intercept the version subcommand and write out a fake version as 24.0.0. The Forge CLI now believes I have the right docker command.

Podman needs configuration for handling unqualified containers

Although Forge CLI now fails in a different place, it’s error message is still Checking Docker image... failed.

Assuming Docker’s wiring to, the Forge CLI tries to use Docker to pull atlassian/forge-tunnel:latest. Podman can accept the command, but tries to prompt for “where” as in which container repository. For me, Podman fails unless I configure it to use by default.

My next workaround was to configure Podman’s registries.conf with:

unqualified-search-registries = [""]

Podman has a different security model

Now, I’m getting the same Checking Docker image... failed error from Forge CLI multiple times in a row, with a new error in there. It reads, Error: invalid IP address in add-host: "host-gateway".

At this point in the code, the Forge CLI is trying to docker run the container with an option --add-host host.docker.internal:host-gateway. Apparently, this is not needed by Podman which simply does that default.

One more workaround. This time, I’m just trying to do the same Docker run command with Podman, so I just manually hack the command parameters and remove the add-host option.

Forge Tunnel is just not built for Podman

Now that I’m running Podman directly, I’m getting a direct message: Error: invalid reference format.

At this point, we’re not in the Forge CLI code so I have to call it quits. I don’t know enough about container formats to know how to solve this but I think it’s more than I could do with a Bash shim for Docker.

I tried. Podman just isn’t going to work with Forge Tunnel.

Don’t run any container

If you really are keen to avoid Docker, you can try the workarounds mentioned here:

Soon, we won’t need any containers

There is a EAP right now for the Native Node.js runtime. One of the advantages not in the docs (but shared elsewhere by the PM):

Docker is no longer required when tunnelling in your local environment. Please ensure you are using a local version of Node.js 18 when running locally.


Thank you @ibuchanan for your digging in and investigating this. It sure saves a lot of the community a lot of pain. :slight_smile: