Clear documentation on the bitcoin/bitcoin docker images on Dockerhub and their build process #31707

1. 
   raweber42 commented at 3:08 pm on January 22, 2025: none

   Please describe the feature you’d like to see added.

   Explanations around the Docker Images being built in the GitHub workflows.

   Is your feature related to a problem, if so please describe it.

   As of now, I was not able to find some clear reference of how the Docker images which are available here are being built. It would also be nice to have a short explanation for newcomers about the risks of using a pre-built image. And most importantly: How can I make sure that the DockerHub images are actually built from this repository? I can see some GitHub actions here, but I only found them by digging deep into the repo.

   Describe the solution you’d like

   A clear explanation on how the Docker images are being built (referencing the GitHub workflows would be nice!) and also a clear statement about whether this DockerHub page is owned by the maintainers of this project.

   Describe any alternatives you’ve considered

   No response

   Please leave any additional context

   I am willing to contribute, if necessary.

2. raweber42 added the label Feature on Jan 22, 2025
3. fanquake removed the label Feature on Jan 22, 2025
4. fanquake added the label Questions and Help on Jan 22, 2025
5. 
   fanquake commented at 3:10 pm on January 22, 2025: member

   Those Docker images come from this repository: https://github.com/willcl-ark/bitcoin-core-docker.

   cc @willcl-ark.

6. 
   raweber42 commented at 3:16 pm on January 22, 2025: none

   Alright, thanks for the lightning fast response!

   It is a bit confusing to see that the DockerHub repo is called bitcoin/bitcoin. This makes users assume, that it’s “the official image”. But from what I can see, it is not.

7. 
   willcl-ark commented at 3:31 pm on January 22, 2025: member

   Hi [@raweber42](/bitcoin-bitcoin/contributor/raweber42/)
   

   These docker images are not owned or maintained by the project, but rather by myself. I.e they are not official. They are aimed at testing environments (e.g. for other bitcoin-adjacent projects), as it is non-trivial to verify the authenticity of the bitcoin core binaries inside (but it is possible in some cases, see below).

   To answer your questions more concretely:

   As detailed in the project README.md:

   The Debian-based (non-alpine) images use pre-built binaries pulled from bitcoincore.org or bitcoin.org (or both) as availability dictates. These binaries are built using the Bitcoin Core reproducible build system, and signatures attesting to them can be found in the guix.sigs repo. Signatures are checked in the build process for these docker images using the verify_binaries.py script from the bitcoin/bitcoin git repository.

   The alpine images are built from source inside the CI.

   The nightly master image is currently alpine-based, source-built, and targeted at the linux/amd64 platform.

   This effectively means that:

   1. Non-alpine tagged images are pulled as tarballs from https://bitcoincore.org/bin/ and the binaries have their guix signatures checked using a copy of our verify-binaries.py script.

   2. Alpine images are built on-demand inside the GitHub Actions CI

   3. Nightly master image is built on-demand inside the GitHub Actions CI

   ---

   When using Bitcoin Core software for non-testing purposes you should always ensure that you have either: i) built it from source yourself, or ii) verfied your binary download (see this page for more information on how to do this).

   Whilst I have followed this procedure myself in creating these images, you should not trust me (or anyone else) providing docker images (or any other source of pre-built binaries!).

   Whilst you can in theory pull the non-nightly, debian-based images, boot into a shell, and verify the binary inside using the same verification instructions from bitcoincore.org/en/download, it’s not the most ergonomic process, and you are likely better off re-building the image yourself using the Dockerfile after reading through it, so that you don’t have to trust me.

   The reason these are at bitcoin/bitcoin on Dockerhub is that there was previously a squatted project there with very old images, which I took up ownership of.

   Thanks for asking about this, I should clarify more of this information in the README on that project.

   Let me know if you have any other questions about this, otherwise feel free to close this issue.

8. 
   raweber42 commented at 3:40 pm on January 22, 2025: none

   @willcl-ark thank you very much for the exhaustive response! It would be great to see this kind of explanation on the DockerHub page for clarification.
9. raweber42 closed this on Jan 22, 2025

   ---

Contributors
raweber42 fanquake willcl-ark

Labels
Questions and Help