KaueTech commented at 8:07 pm on August 5, 2025: none

Add Docker support with multi-arch build and user permissions handling

This pull request introduces a Dockerfile and supporting scripts to enable containerized builds and deployment of Bitcoin Core, targeting multiple architectures (amd64, arm64, riscv64).

Key changes include:

Multi-stage Dockerfile to build Bitcoin Core from official releases, GitHub source, or local source with consistent environments.
User and group creation inside the container to avoid running bitcoind as root, with proper permissions set on data directories.
Entrypoint script to dynamically configure RPC bindings based on IPv4 or IPv6 protocol environment variable.
Inclusion of gosu to drop root privileges safely inside the container.
Docker Compose file for easy local development and testing setups.

This improves deployment reproducibility, security by avoiding root execution, and supports multiple CPU architectures for broader compatibility.

No changes to core Bitcoin functionality have been made. Tests remain passing for the built binaries.

Add docker support 3632325289

Update docker-compose.yaml 8bdb143d3b

DrahtBot commented at 8:07 pm on August 5, 2025: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33139.

Reviews

See the guideline for information on the review process.

Type	Reviewers
Concept NACK	fanquake, pinheadmz, achow101

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

LLM Linter (✨ experimental)

Possible typos and grammar issues:

Proccess HS_* envs -> Process HS_* envs [“Proccess” is a misspelling of “Process”]
If not has virtual_port, uses target_port -> If virtual_port is unset, use target_port [original phrasing is ungrammatical and unclear]

drahtbot_id_4_m

pinheadmz commented at 8:14 pm on August 5, 2025: member

This has been proposed before and typically gets rejected:

#25681

https://github.com/bitcoin-core/packaging/issues/55

KaueTech commented at 8:24 pm on August 5, 2025: none

This has been proposed before and typically gets rejected:

#25681

bitcoin-core/packaging#55

I believe these are very different pull requests.
In my case, the goal is to allow anyone to run Bitcoin Core simply by cloning the repository and running:

0docker compose up --build -d

There are three image build modes:

local: for development (builds from local source)
github: clones directly from the official GitHub repository
official-site: downloads the release directly from bitcoincore.org validating signatures

It also supports building for different architectures (amd64, arm64, riscv64).

I don’t see a reason not to include this. After all, no prebuilt image is used — only local builds. Is there any specific concern or reason why we shouldn’t make it easier for someone to locally build and run Bitcoin Core with a single command?

maflcko commented at 8:36 pm on August 5, 2025: member

local: for development (builds from local source)

Developer would want to be able to pick different compile options. I don’t think your approach of adding a hardcoded command is useful. Has any developer asked for this?

KaueTech commented at 8:41 pm on August 5, 2025: none

Developer would want to be able to pick different compile options. I don’t think your approach of adding a hardcoded command is useful. Has any developer asked for this?

Thanks for the feedback!

I understand that developers might want to customize build options — and this setup doesn’t remove that flexibility. The local build target is exactly for that: developers can edit the Dockerfile or mount their source with custom flags. This setup simply provides a working, modular starting point.

The main goals here are:

Reduce friction for new contributors or testers
Enable fast prototyping with docker compose up
Provide a consistent, portable build environment across different machines/architectures
Keep everything isolated and reproducible

To answer your question directly: no, no one specifically asked for this — but many open source improvements are proactive. This is a non-invasive addition that doesn’t affect the core build system or existing workflows. It simply offers another way to interact with the project, especially for Docker-native users.

If the concern is the hardcoded flags: I’m happy to refactor to make those configurable via env vars or build args, if that helps move it forward.

in entrypoint.sh:15 in 8bdb143d3b outdated

10+    IPV4|"")
11+        RPC_BIND="-rpcbind=0.0.0.0:8332"
12+        RPC_ALLOW="-rpcallowip=0.0.0.0/0"
13+        ;;
14+    *)
15+        echo "Protocolo inválido: $PROTOCOL (use IPV4 ou IPV6)"

pinheadmz commented at 8:45 pm on August 5, 2025:

Español here?

in docker-compose.yaml:16 in 8bdb143d3b outdated

11+    restart: unless-stopped
12+    volumes:
13+      - ./data:/bitcoin/.bitcoin
14+    ports:
15+      - "8332:8332"  # RPC
16+      - "8333:8333"  # P2P

pinheadmz commented at 8:46 pm on August 5, 2025:

There’s also 3 other network types as well as zmq and tor ports.

KaueTech commented at 9:18 pm on August 5, 2025:

There’s also 3 other network types as well as zmq and tor ports.

I’m new to the Bitcoin codebase and these are the ports I know so far:

0      - "8332:8332"  # RPC  
1      - "8333:8333"  # P2P

Could you please suggest which other network ports I should expose in the yaml?

in Dockerfile:52 in 8bdb143d3b outdated

47+WORKDIR /tmp
48+
49+ARG VERSION
50+ENV VERSION="${VERSION}"
51+
52+ENV BITCOIN_CORE_SIGNATURE=71A3B16735405025D447E8F274810B012346C9A6

pinheadmz commented at 8:47 pm on August 5, 2025:

This is lannwj’s key but this isn’t how we “sign” releases any more.

pinheadmz changes_requested

KaueTech requested review from pinheadmz on Aug 5, 2025

verify pre-downloaded binary with guix.sigs 3ec37f0abb

DrahtBot added the label CI failed on Aug 5, 2025

DrahtBot commented at 9:05 pm on August 5, 2025: contributor

🚧 At least one of the CI tasks failed. Task lint: https://github.com/bitcoin/bitcoin/runs/47453070097 LLM reason (✨ experimental): The CI failure is due to lint check errors, including trailing whitespace, shell script issues, spelling warnings, and misconfigured file permissions.

Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.
A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.
An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

Change log output from Portuguese to English 8f40b890e4

Update Dockerfile 0f2cb2f71f

in .dockerignore:7 in 0f2cb2f71f outdated

0@@ -0,0 +1,10 @@
1+doc
2+.git
3+.github
4+.tx
5+*.md
6+build/
7+cmake-build*

maflcko commented at 8:05 am on August 6, 2025:

not sure about implicit copying and having to maintain a list of stuff to ignore. it would be better to explicitly copy just the git-tracked files.

in docker-compose.yaml:9 in 0f2cb2f71f outdated

0@@ -0,0 +1,16 @@
1+services:
2+  bitcoin:
3+    build:
4+      context: .
5+      dockerfile: Dockerfile
6+      target: official-site   # local | github | official-site
7+      args:
8+        VERSION: "29.0"
9+        TARGETARCH: "amd64"  # amd64 | arm64 | riscv64

maflcko commented at 8:24 am on August 6, 2025:

I don’t think it makes sense to enumerate them or even mention them. It should simply use the native arch. This can be achieved by just passing --platform=linux, like in the CI system

KaueTech commented at 1:37 pm on August 6, 2025:

I don’t think it makes sense to enumerate them or even mention them. It should simply use the native arch. This can be achieved by just passing --platform=linux, like in the CI system

The TARGETARCH is only for the image build that downloads from bitcoincore.net, because it’s needed in the wget URL: https://bitcoincore.org/bin/bitcoin-core-${VERSION}/bitcoin-${VERSION}-${ARCH}-linux-gnu.tar.gz

The image build from local code doesn’t need VERSION or ARCH.

The build from GitHub code only needs VERSION, since it clones the repository using the version tag.

maflcko commented at 2:49 pm on August 6, 2025:

It should just auto-detect, if it is only used internally? Seems odd to ask the user to lookup their arch and pass a magic value?

KaueTech commented at 2:58 pm on August 6, 2025:

It should just auto-detect, if it is only used internally? Seems odd to ask the user to lookup their arch and pass a magic value?

Oh right, it already passes TARGETARCH automatically. I’ll remove it from the docker-compose.

fanquake commented at 8:41 am on August 6, 2025: member

Concept NACK. The benefits of this are unclear, this seems to just add a new dependency/abstraction layer (for development?), without solving any specific problem. It’s also trying to do three things at once, and there already exist maintained Dockerfiles, for the deployment scenario, i.e https://github.com/willcl-ark/bitcoin-core-docker.

developers can edit the Dockerfile or mount their source with custom flags.

This is more work than just using CMake and setting options?

Provide a consistent, portable build environment across different machines/architectures Keep everything isolated and reproducible

Nothing in here is pinned, so how is this acheived? This seems like a worse version of a Nix flake, or our Guix build.

Is there any specific concern or reason why we shouldn’t make it easier for someone to locally build and run Bitcoin Core with a single command?

What specific issues have you had with the current CMake build system / docs that adding Docker, resolves?

local: for development (builds from local source)

If this is for development, it seems odd that it would hardcode a number of options, and for example, disable the wallet?

maflcko commented at 9:13 am on August 6, 2025: member

developers can edit the Dockerfile or mount their source with custom flags.

This is more work than just using CMake and setting options?

Yeah, for devs it could make sense to have an image with just the build deps, similar to the lint ci image:

0DOCKER_BUILDKIT=1 docker build -t bitcoin-core-build-deps --file "./contrib/dev-build-deps_imagefile" ./ && docker run --rm -v $(pwd):/bitcoin -it bitcoin-core-build-deps
1... then run cmake, etc...

However, I am not sure if any devs would use this.

pinheadmz commented at 10:50 am on August 6, 2025: member

concept NACK willcl_ark’s dockerhub repo is already outstanding: https://hub.docker.com/r/bitcoin/bitcoin even providing nightly builds!

KaueTech commented at 2:04 pm on August 6, 2025: none

Concept NACK. The benefits of this are unclear, this seems to just add a new dependency/abstraction layer (for development?), without solving any specific problem. It’s also trying to do three things at once, and there already exist maintained Dockerfiles, for the deployment scenario, i.e https://github.com/willcl-ark/bitcoin-core-docker.

developers can edit the Dockerfile or mount their source with custom flags.

This is more work than just using CMake and setting options?

Provide a consistent, portable build environment across different machines/architectures Keep everything isolated and reproducible

Nothing in here is pinned, so how is this acheived? This seems like a worse version of a Nix flake, or our Guix build.

Is there any specific concern or reason why we shouldn’t make it easier for someone to locally build and run Bitcoin Core with a single command?

What specific issues have you had with the current CMake build system / docs that adding Docker, resolves?

local: for development (builds from local source)

If this is for development, it seems odd that it would hardcode a number of options, and for example, disable the wallet?

The goal was simply to run bitcoind with a single command. I genuinely don’t think anyone cares about the Bitcoin Core wallet in this context.

Yes, as a developer, I’m fully capable of building Bitcoin Core using CMake. But I didn’t want to pollute my distro by installing all its build dependencies. Some users prefer running everything isolated in Docker — and that’s a valid preference. Providing three build options using just one Dockerfile and one docker-compose.yaml doesn’t hurt anyone.

As for this repo:

https://github.com/willcl-ark/bitcoin-core-docker https://hub.docker.com/r/bitcoin/bitcoin

I don’t know who that person is. It’s a third-party repo, not official and not reviewed or validated by thousands of people. That’s a trust issue.

There doesn’t need to be an official Bitcoin Core image on Docker Hub or anywhere else — that’s not secure, as it would require trusting one or more third parties.

The point is to give people easy access to running Bitcoin Core — whether for development or to contribute to the network. A Dockerfile that automates the entire build process would help.

This opens up possibilities, for example, to also build a Tor image and connect Bitcoin Core directly to the Tor network — all integrated via Docker Compose. Running Bitcoin on the Tor network with a single command. But that’s another topic — I’m already going beyond the scope of these commits.

Like I said: this is just another way to interact with the project, an addition — not a replacement or requirement. Even for casual users who want to run a node, having an official Dockerfile in the repo (not relying on third parties) would make a difference.

Right now, people end up trusting ecosystems like Umbrel or Start9 just to run a node. But that gap could be solved if Bitcoin Core itself offered a ready-to-use Dockerfile and Compose.

So no — this doesn’t “solve” any developer problem. We know how to build it. It just makes it easier for beginners and regular users to get started. And for devs who prefer it, the local CMake build remains fully available.

fanquake commented at 2:08 pm on August 6, 2025: member

not maintained by Bitcoin Core contributors,

It is. @willcl-ark is a regular contributor to the project.

KaueTech commented at 2:10 pm on August 6, 2025: none

not maintained by Bitcoin Core contributors,

It is. @willcl-ark is a regular contributor to the project.

I’m not saying he’s not a trustworthy person — just that his work isn’t in the Bitcoin Core repository. I think everyone naturally prefers what’s in the official repo, since any code inside it carries more trust from the community. But as I said, it’s nothing strictly necessary.

sipa commented at 2:13 pm on August 6, 2025: member

FWIW, I think there is value in having some form of docker integration for users, as part of the repository/release itself and not just maintained by a third party. I’m not familiar enough with docker myself to judge what approaches are appropriate, but it’s a sufficiently common request that I think it would be nice if Bitcoin Core offered something like this. But, obviously, only if someone wants to step to maintain it, and make sure infrastructure is available to test it doesn’t bitrot.

For development, I don’t really see the point, but maybe I’m too oldschool.

willcl-ark commented at 3:06 pm on August 6, 2025: member

I can sympapthezie somewhat with wanting an un-polluted system as a developer, but for that I personally think Nix is a strictly superior solution to docker for this use-case (and indeed I maintain a nix devShell flake here for exactly this purpose).

We already have our CI setup containerised for exactly this type of reason too, and the use-case of a developer wanting to build-and-test inside a container is already provided by running a CI job locally I think.

Regarding the deployment use-case. For this it would seem sensible to limit to release builds/versions. As mentioned above I already maintain some non-official image files at github.com/willcl-ark/bitcoin-core-docker which are deployed ot dockerhub. IMO those Dockerfiles have a number of advantages over the changeset here:

they are (in my opinion) a bit tidier/simpler
have correct ports being exposed
they use our own verify-binaries.py script (although this is arguably clumsily bundled in the repo currently) and builder-keys from the guix.sigs repo

That said I am not in favour of adding “deployment dockerfiles” to this repo; if anything, perhaps they could go in https://github.com/bitcoin-core/packaging ? This has been tried before but there was not much interest: https://github.com/bitcoin-core/packaging/pull/2

Modify docker integration 737142bd73

Merge branch 'add-docker-support' of https://github.com/KaueTech/bitcoin into add-docker-support ade8bb533e

Remove portuguese comments 78c5f1ebc8

KaueTech commented at 5:07 pm on August 6, 2025: none

I can sympapthezie somewhat with wanting an un-polluted system as a developer, but for that I personally think Nix is a strictly superior solution to docker for this use-case (and indeed I maintain a nix devShell flake here for exactly this purpose).

We already have our CI setup containerised for exactly this type of reason too, and the use-case of a developer wanting to build-and-test inside a container is already provided by running a CI job locally I think.

Regarding the deployment use-case. For this it would seem sensible to limit to release builds/versions. As mentioned above I already maintain some non-official image files at github.com/willcl-ark/bitcoin-core-docker which are deployed ot dockerhub. IMO those Dockerfiles have a number of advantages over the changeset here:

they are (in my opinion) a bit tidier/simpler

have correct ports being exposed

they use our own verify-binaries.py script (although this is arguably clumsily bundled in the repo currently) and builder-keys from the guix.sigs repo

That said I am not in favour of adding “deployment dockerfiles” to this repo; if anything, perhaps they could go in https://github.com/bitcoin-core/packaging ? This has been tried before but there was not much interest: bitcoin-core/packaging#2

I added validation using the existing verify.py script from the repository. I reused your example code @willcl-ark, exposed the correct ports, and as a bonus, added support for a .onion address via docker-compose.yaml. But let me know if you’d prefer I remove that part.

I moved everything to /contrib/docker, except for docker-compose.yaml, which I kept in the project root. I can move it as well if needed, but I believe it makes more sense to keep it there.

fix docker compose network 17c58be50d

achow101 commented at 5:23 pm on August 6, 2025: member

NACK

If this is for users to be able to deploy Bitcoin Core in docker, I don’t think it belongs in this repo. We have the separate packaging repo where stuff related to producing packages for distribution on specific platforms, so a dockerfile for users to use belongs there.

If this is for development, it does not seem to be useful. It hardcodes a bunch of stuff, including disabling benchmarks and tests. There doesn’t seem to be any way to override those options without modifying the dockerfile. If the expectation is that developers will modify the dockerfile to suit whatever builds that they are doing, I think it’s also reasonable to expect those developers to be able to write their own dockerfile. Anyone who doesn’t know how to do that is not going to be doing a whole lot of useful things with this dockerfile.

KaueTech commented at 5:35 pm on August 6, 2025: none

NACK

Se isso for para que os usuários possam implantar o Bitcoin Core no Docker, acho que não pertence a este repositório. Temos um repositório de empacotamento separado, onde estão as coisas relacionadas à produção de pacotes para distribuição em plataformas específicas, então um dockerfile para os usuários usarem deve estar lá.

Se for para desenvolvimento, não parece ser útil. Ele codifica um monte de coisas, incluindo a desativação de benchmarks e testes. Não parece haver nenhuma maneira de substituir essas opções sem modificar o dockerfile. Se a expectativa é que os desenvolvedores modifiquem o dockerfile para se adequar a quaisquer builds que estejam fazendo, acho que também é razoável esperar que esses desenvolvedores sejam capazes de escrever seu próprio dockerfile. Quem não sabe como fazer isso não vai fazer muitas coisas úteis com este dockerfile.

NACK

Se isso for para que os usuários possam implantar o Bitcoin Core no Docker, acho que não pertence a este repositório. Temos um repositório de embalagens separado, onde estão as coisas relacionadas à produção de pacotes para distribuição em plataformas específicas, então um dockerfile para os usuários usarem deve estar lá.

Se for para desenvolvimento, não parece ser útil. Ele codifica um monte de coisas, incluindo a desativação de benchmarks e testes. Não parece haver nenhuma maneira de substituir essas opções sem modificar o dockerfile. Se a expectativa é que os desenvolvedores modifiquem o dockerfile para se adequar a quaisquer compilações que estejam fazendo, acho que também é razoável esperar que esses desenvolvedores sejam capazes de escrever seu próprio dockerfile. Quem não sabe como fazer isso não vai fazer muitas coisas úteis com este dockerfile.

The thing with the new version I sent, which is based on Willcl’s, is that it just downloads the .zip file to verify. What it should do is pull the code directly from GitHub, zip it, verify it against the developers’ signatures and compile. That way, people can be sure that the version on GitHub is exactly the same as the one on bitcoincore.net, just built via Docker. That would actually have technical value.

Other than that, the only real reason is to have Docker directly in the official Bitcoin repository, which everyone is watching. The main goal is to get rid of the need for extra repositories.

Being able to run a full node just by cloning the repo and running docker-compose up –build -d seems great. It’s not just running a full node, but a build from scratch, fully verified with the developers’ signatures.

Aris-Ritz commented at 5:45 pm on August 6, 2025: none

.dockerignore

KaueTech commented at 5:56 pm on August 6, 2025: none

You already have your own CI setup and build methods, but they’re like using a cannon to kill a fly. I believe the official repository should include a simple way to run Bitcoin Core without worrying about the operating system, dependencies, or anything like that — everything could be handled through a Dockerfile.

As I mentioned, people already use forks of Bitcoin Core like Umbrel’s or Start9’s, which include Dockerfiles. People install Bitcoin Core like any other app, and it just magically runs. The point is: Bitcoin Core could offer this out of the box, so users wouldn’t need to rely on third-party images or random Docker Hub uploads.

With this commit, anyone can build and run their own image directly from source.

pinheadmz commented at 8:39 pm on August 6, 2025: member

With this commit, anyone can build and run their own image directly from source.

That’s what the release binaries are for? The security is the same: verifying a signature from a trusted developer either on a guix build or a commit in this repository.

in contrib/docker/tor/Dockerfile:4 in 17c58be50d

0@@ -0,0 +1,39 @@
1+FROM --platform=$BUILDPLATFORM alpine:3.22
2+
3+LABEL maintainer="hundehausen"
4+LABEL description="Tor Hidden Service Docker Image"

maflcko commented at 7:31 am on August 7, 2025:

copy-paste from https://github.com/hundehausen/tor-hidden-service-docker/blob/main/Dockerfile

in contrib/docker/bitcoin/Dockerfile:21 in 17c58be50d

16+    git \
17+    libevent-dev \
18+    libtool \
19+    linux-headers \
20+    sqlite-dev \
21+    zeromq-dev

maflcko commented at 7:33 am on August 7, 2025:

copy-paste from https://github.com/willcl-ark/bitcoin-core-docker/blob/master/29.0/alpine/Dockerfile

KaueTech commented at 12:16 pm on August 7, 2025:

I mentioned her — initially it wasn’t copy-pasted, but I changed it because Willcl-ark said his version was better, and it really was

in contrib/docker/bitcoin/Dockerfile:23 in 17c58be50d

18+    libtool \
19+    linux-headers \
20+    sqlite-dev \
21+    zeromq-dev
22+
23+ARG BITCOIN_VERSION=29.0

maflcko commented at 7:55 am on August 7, 2025:

This needs a proper workflow documented on how to bump it and when. Otherwise, it would be confusing to have a 30.0 git release tag which contains a dockerfile with a hard-coded 29.0 tag.

maflcko commented at 7:58 am on August 7, 2025: member

now you are just copy-pasting random files from the internet without even mentioning the source?

maflcko commented at 8:08 am on August 7, 2025: member

For reference, for development, the dockerfile should look more like https://github.com/fanquake/core-review/blob/0bb70124a23807e3638f29ebd76c2bebc4880fd7/podman/debian.imagefile, just containing the install commands copy-pasted from the docs. But the development and deployment workflows differ significantly enough to not mix them up as the same.

My recommendation would be to just pick one problem/goal and not try to interleave multiple in the same pull request.

KaueTech closed this on Aug 7, 2025

KaueTech deleted the branch on Aug 7, 2025

KaueTech restored the branch on Aug 7, 2025

pinheadmz commented at 12:34 pm on August 7, 2025: member

@KaueTech Thanks for the contribution, I encourage you to learn more about the codebase and find other ways you make Bitcoin great. Here’s some good onboarding resources:

https://bitcoincore.academy/

https://bitcoindevs.xyz/

KaueTech deleted the branch on Aug 11, 2025

Add Docker support with multi-arch build and user permissions handling #33139

Add Docker support with multi-arch build and user permissions handling

Key changes include:

Code Coverage & Benchmarks

Reviews

LLM Linter (✨ experimental)