protonmail-bridge-docker: ProtonMail Bridge in a container, with ARM images

The bridge is a local proxy, and this package puts it in a container

ProtonMail Bridge is Proton's own application for using a Proton account in any mail client, and this repository packages it as a Docker image. The repository is explicit that it is an unofficial container, and that some of the scripts are based on work by Hendrik Meyer. The point of running it in Docker is that the bridge is a local process that holds your account credentials in its own local store and then serves standard IMAP and SMTP to clients on the same machine or network. That architecture explains the two-step setup below and the security warning at the end. The image is published on Docker Hub as shenxn/protonmail-bridge, and the repository itself is GPL-3.0 licensed, which matters because the ProtonMail Bridge itself is proprietary software that the container downloads and packages rather than shipping the source of.

Two image families, and the reason the source build exists

There are two types of images, and the split is about architecture support. The deb images are based on the official .deb release from Proton and only support amd64. The build images are based on the source code of proton-bridge and support amd64, arm64, arm/v7 and riscv64, with the README saying that supporting more architectures is possible and that pull requests are welcome. The tag table explains the naming: latest is the latest deb image, a version tag is a deb image, build is the latest build image, and a version tag with a build suffix is a build image. The practical guidance is to use the build tag if you are on a Raspberry Pi or an ARM server, and to use the deb image otherwise, since it is the officially packaged release path. The README's ARM support section points at the build images for exactly this reason.

Initialization needs an interactive login, and that is deliberate

Setting the container up is not a single command, because the account has to be added to the bridge through its own interactive shell.

docker run --rm -it -v protonmail:/root shenxn/protonmail-bridge init

You wait for the bridge to start, a prompt appears for the Proton Mail Bridge interactive shell, you use the login command and follow the instructions to add your account, then use info to see the configuration information, which is the username and password the bridge generated, and then exit. The README notes you may need to interrupt with CTRL+C to leave Docker itself. With Docker Compose the equivalent is to copy the provided docker-compose.yml, adjust it, and run docker compose run protonmail-bridge init. The reason this cannot be done with environment variables is stated later in the README: it seems to be the best way to support two-factor authentication, and that is a meaningful constraint rather than a missing feature.

Running the container exposes SMTP and IMAP on two ports

Once the account is registered, the container runs as a normal long-lived service.

docker run -d --name=protonmail-bridge -v protonmail:/root -p 1025:25/tcp -p 1143:143/tcp --restart=unless-stopped shenxn/protonmail-bridge

The port mapping is the key detail. Port 25 inside the container is SMTP, published on the host as 1025 because port 25 needs root privileges on the host, and port 143 inside is IMAP, published as 1143 for the same reason. The volume named protonmail is mounted at /root so the bridge's local state, which includes the account registration and the generated credentials, survives a container restart. The provided docker-compose.yml does the same thing declaratively with the same port mapping and a named volume, and the compose alternative for running is docker compose up -d. If you only need to send mail, for instance as a notification service, the README says you can publish only port 25.

The security warning is the most useful paragraph in the README

The README tells you plainly that running the published ports will expose your bridge to the network, and to use a firewall if you run it on an untrusted network or a machine with a public IP address. The fix it offers is to publish to localhost only, which the README says is the same behaviour as the official bridge package.

docker run -d --name=protonmail-bridge -v protonmail:/root -p 127.0.0.1:1025:25/tcp -p 127.0.0.1:1143:143/tcp --restart=unless-stopped shenxn/protonmail-bridge

This is worth taking seriously rather than skimming. The bridge hands out a working IMAP and SMTP session for a real mail account, and the credentials it generates are stored in the mounted volume, so anything that can reach the published port and knows the bridge username and password can send mail as you. The repository also carries a SECURITY.md file at the root, and the README's compatibility section notes that the bridge supports only some email clients, with details on the official site. The author reports testing it on a Synology DiskStation where it runs well, with the caveat that you may need to ssh in to run the interactive command to add your account.

Kubernetes options and building the image yourself

For a cluster, the README points at a Helm chart created by Eagleman7, hosted in the k8s-at-home charts repository, with more detail in issue 23, and at a plain guide written by ghudgins in issue 6 for people who do not want to use Helm. The bridge CLI itself is also exposed by the initialization step, so you can switch between combined and split mode, change the proxy and similar, with the official guide linked. Building the image locally is deliberately simple. You change into the deb or build directory depending on which image type you want, and run the docker build command.

docker build .

The README says that is all it takes, since the Dockerfile and the bash scripts handle the downloading, building and packing. It also says you can add tags, push to your own registry, or use buildx for multi-architecture images, which is the route to a custom architecture the public images do not cover. The repository has a build and a deb directory, an update-check.py script, a VERSION file, and a SECURITY.md.

Editorial conclusion

This container fits a self-hosted setup, a NAS, or a small server that needs a local IMAP and SMTP endpoint backed by a Proton account, and where you are willing to log into the bridge interactively over a shell once. It does not fit someone who wants a hosted mail service, since the bridge is by design a local proxy, and it does not fit a public-facing deployment without a firewall, because the ports expose an authenticated local mail client to whoever can reach them. Verify first that the client you use is one the bridge supports, keep the published ports bound to localhost unless you have a firewall, and read the SECURITY.md file before exposing anything.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. shenxn/protonmail-bridge-docker on GitHub