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.
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 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 registries.conf with:
unqualified-search-registries = ["docker.io"]
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.
