github.com/letsencrypt/boulder@v0.20251208.0/test/boulder-tools/README.md (about)

     1  # Boulder-Tools Docker Image Utilities
     2  
     3  In CI and our development environment we do not rely on the Go environment of
     4  the host machine, and instead use Go installed in a container. To simplify
     5  things we separate all of Boulder's build dependencies into its own
     6  `boulder-tools` Docker image.
     7  
     8  ## Setup
     9  
    10  To build boulder-tools images, you'll need a Docker set up to do cross-platform
    11  builds (we build for both amd64 and arm64 so developers with Apple silicon can use
    12  boulder-tools in their dev environment).
    13  
    14  ### Ubuntu steps:
    15  ```sh
    16  sudo apt-get install qemu binfmt-support qemu-user-static
    17  docker buildx create --use --name=cross
    18  ```
    19  
    20  After setup, the output of `docker buildx ls` should contain an entry like:
    21  
    22  ```sh
    23  cross0  unix:///var/run/docker.sock running linux/amd64, linux/386, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6
    24  ```
    25  
    26  If you see an entry like:
    27  
    28  ```sh
    29  cross0  unix:///var/run/docker.sock stopped
    30  ```
    31  
    32  That's probably fine; the instance will be started when you run
    33  `tag_and_upload.sh` (which runs `docker buildx build`).
    34  
    35  ### macOS steps:
    36  Developers running macOS 12 and later with Docker Desktop 4 and later should
    37  be able to use boulder-tools without any pre-setup.
    38  
    39  ## Go Versions
    40  
    41  Rather than install multiple versions of Go within the same `boulder-tools`
    42  container we maintain separate images for each Go version we support.
    43  
    44  When a new Go version is available we perform several steps to integrate it
    45  to our workflow:
    46  
    47  1. We add it to the `GO_VERSIONS` array in `tag_and_upload.sh`.
    48  2. We run the `tag_and_upload.sh` script to build, tag, and upload
    49     a `boulder-tools` image for each of the `GO_VERSIONS`.
    50  3. We update `.github/workflows/boulder-ci.yml` to add the new image tag(s).
    51  4. We update the remaining `.github/workflows/` yaml files that use a `GO_VERSION` matrix with the new version of Go.
    52  5. We update `docker-compose.yml` to update the default image tag (optional).
    53  
    54  After some time when we have spot checked the new Go release and coordinated
    55  a staging/prod environment upgrade with the operations team we can remove the
    56  old `GO_VERSIONS` entries, delete their respective build matrix items, and update
    57  `docker-compose.yml`.