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:
- Use of other alternatives instead of Docker to run the forge tunnel?
- Forge Tunnel exits immediately without error
- Forge tunnel error: Cannot pull the tunnel image
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.
As indicated above, the easiest way to substitute
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 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.
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
Although Forge CLI now fails in a different place, it’s error message is still
Checking Docker image... failed.
Assuming Docker’s wiring to
docker.io, 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
docker.io by default.
My next workaround was to configure Podman’s
unqualified-search-registries = ["docker.io"]
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
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.
If you really are keen to avoid Docker, you can try the workarounds mentioned here:
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.