Update READMEs (#69)

This PR updates the READMEs as follows:
* Logging into GHCR is only needed when pushing, so those instructions
are moved to the last section.
* GCC base image ARG was missing ghcr.io, which has been fixed.
* To simplify copy-pasting of commands, the `CONTAINER_REGISTRY` var has
been removed and ghcr.io has been added explicitly. Otherwise it's
needed to copy-paste-run commands scattered across the readme.
* Extra note for macOS is included to add `--platform linux/amd64` in
order to create a Docker image that can be run by CI on Linux.
* Updated push instruction to include `sha-${USER}` to the image tag, so
it can be referenced in the strategy matrix.
* General other cleanups.

Author: bthomee

docker/debian/README.md

@@ -7,48 +7,33 @@ Although the images will be built by a CI pipeline in this repository, if
 necessary a maintainer can build them manually by following the instructions
 below.
 
-### Logging into the GitHub registry
-
-To be able to push a Docker image to the GitHub registry, a personal access
-token is needed, see instructions [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).
-In summary, if you do not have a suitable personal access token, generate one
-[here](https://github.com/settings/tokens/new?scopes=write:packages).
-
-```shell
-CONTAINER_REGISTRY=ghcr.io
-GITHUB_USER=<your-github-username>
-GITHUB_TOKEN=<your-github-personal-access-token>
-echo ${GITHUB_TOKEN} | \
-docker login ${CONTAINER_REGISTRY} -u "${GITHUB_USER}" --password-stdin
-```
-
-### Building and pushing the Docker image
+### Building the Docker image
 
 The same Dockerfile can be used to build an image for different Debian releases
 by specifying the `DEBIAN_VERSION` build argument. There are additional
 arguments to specify as well, namely `GCC_VERSION` for the GCC flavor and
 `CLANG_VERSION` for the Clang flavor.
 
-Build image for `gcc` supports packaging.
+Only the build image for `gcc` supports packaging.
 
 #### Note on old GCC binaries
 
 This image supports variety of releases of Debian, GCC and Clang. In order to
-support current GCC versions on an older Debian releases, we rely on `gcc` images
-backported from the [official GCC repository](https://github.com/docker-library/gcc).
+support current GCC versions on an older Debian releases, we rely on `gcc`
+images backported from the [official GCC repository](https://github.com/docker-library/gcc).
 
-Hence, depending on the Debian release used, the GCC binaries are sourced from either of:
+Hence, depending on the Debian release used, the GCC binaries are sourced from
+either of:
 
-- for `DEBIAN_VERSION=bookworm` : `gcc:$GCC_VERSION-$DEBIAN_VERSION`, produced in the [official GCC repository](https://github.com/docker-library/gcc)
-- for `DEBIAN_VERSION=bullseye` : `xrplf/ci/gcc:$GCC_VERSION-$DEBIAN_VERSION`, produced in [this repository](https://github.com/XRPLF/ci/pkgs/container/gcc)
+- for `DEBIAN_VERSION=bookworm`: `gcc:${GCC_VERSION}-${DEBIAN_VERSION}`, produced in
+  the [official GCC repository](https://github.com/docker-library/gcc)
+- for `DEBIAN_VERSION=bullseye`: `ghcr.io/xrplf/ci/gcc:${GCC_VERSION}-${DEBIAN_VERSION}`,
+  produced in [this repository](https://github.com/XRPLF/ci/pkgs/container/gcc)
 
 #### Building the Docker image for GCC
 
-In order to build an image, run the commands below from the root directory of
-the repository.
-
-Ensure you've run the login command above to authenticate with the Docker
-registry.
+In order to build the image for GCC, run the commands below from the root
+directory of the repository.
 
 ```shell
 DEBIAN_VERSION=bookworm
@@ -57,7 +42,7 @@ CONAN_VERSION=2.19.1
 GCOVR_VERSION=8.3
 CMAKE_VERSION=4.1.0
 MOLD_VERSION=2.40.4
-CONTAINER_IMAGE=xrplf/ci/debian-${DEBIAN_VERSION}:gcc-${GCC_VERSION}
+CONTAINER_IMAGE=ghcr.io/xrplf/ci/debian-${DEBIAN_VERSION}:gcc-${GCC_VERSION}
 
 docker buildx build . \
   --file docker/debian/Dockerfile \
@@ -70,10 +55,10 @@ docker buildx build . \
   --build-arg GCOVR_VERSION=${GCOVR_VERSION} \
   --build-arg CMAKE_VERSION=${CMAKE_VERSION} \
   --build-arg MOLD_VERSION=${MOLD_VERSION} \
-  --tag ${CONTAINER_REGISTRY}/${CONTAINER_IMAGE}
+  --tag ${CONTAINER_IMAGE}
 ```
 
-In order to build an image for Bullseye, you also need to explicitly set
+In order to build a GCC image for Bullseye, you also need to explicitly set
 `BASE_IMAGE` build argument, e.g.
 
 ```shell
@@ -83,8 +68,8 @@ CONAN_VERSION=2.19.1
 GCOVR_VERSION=8.3
 CMAKE_VERSION=4.1.0
 MOLD_VERSION=2.40.4
-BASE_IMAGE=xrplf/ci/gcc:12-bullseye
-CONTAINER_IMAGE=xrplf/ci/debian-${DEBIAN_VERSION}:gcc-${GCC_VERSION}
+BASE_IMAGE=ghcr.io/xrplf/ci/gcc:12-bullseye
+CONTAINER_IMAGE=ghcr.io/xrplf/ci/debian-${DEBIAN_VERSION}:gcc-${GCC_VERSION}
 
 docker buildx build . \
   --file docker/debian/Dockerfile \
@@ -98,13 +83,13 @@ docker buildx build . \
   --build-arg CMAKE_VERSION=${CMAKE_VERSION} \
   --build-arg MOLD_VERSION=${MOLD_VERSION} \
   --build-arg BASE_IMAGE=${BASE_IMAGE} \
-  --tag ${CONTAINER_REGISTRY}/${CONTAINER_IMAGE}
+  --tag ${CONTAINER_IMAGE}
 ```
 
 #### Building the Docker image for Clang
 
-Ensure you've run the login command above to authenticate with the Docker
-registry.
+In order to build an image for Clang, run the commands below from the root
+directory of the repository.
 
 ```shell
 DEBIAN_VERSION=bookworm
@@ -113,7 +98,7 @@ CONAN_VERSION=2.19.1
 GCOVR_VERSION=8.3
 CMAKE_VERSION=4.1.0
 MOLD_VERSION=2.40.4
-CONTAINER_IMAGE=xrplf/ci/debian-${DEBIAN_VERSION}:clang-${CLANG_VERSION}
+CONTAINER_IMAGE=ghcr.io/xrplf/ci/debian-${DEBIAN_VERSION}:clang-${CLANG_VERSION}
 
 docker buildx build . \
   --file docker/debian/Dockerfile \
@@ -126,17 +111,17 @@ docker buildx build . \
   --build-arg GCOVR_VERSION=${GCOVR_VERSION} \
   --build-arg CMAKE_VERSION=${CMAKE_VERSION} \
   --build-arg MOLD_VERSION=${MOLD_VERSION} \
-  --tag ${CONTAINER_REGISTRY}/${CONTAINER_IMAGE}
+  --tag ${CONTAINER_IMAGE}
 ```
 
-#### Running the Docker image
+### Running the Docker image
 
 If you want to run the image locally using a cloned `rippled` repository, you
 can do so with the following command:
 
 ```shell
 CODEBASE=<path to the rippled repository>
-docker run --user $(id -u):$(id -g) --rm -it -v ${CODEBASE}:/rippled ${CONTAINER_REGISTRY}/${CONTAINER_IMAGE}
+docker run --user $(id -u):$(id -g) --rm -it -v ${CODEBASE}:/rippled ${CONTAINER_IMAGE}
 ```
 
 Note, the above command will assume the identity of the current user in the
@@ -163,7 +148,7 @@ cd /rippled
 # Remove any existing data from previous builds on the host machine.
 rm -rf CMakeCache.txt CMakeFiles build || true
 # Install dependencies via Conan.
-conan remote add --index=0 xrplf https://conan.ripplex.io
+conan remote add --force --index 0 xrplf https://conan.ripplex.io
 conan install . --build missing --settings:all build_type=${BUILD_TYPE} \
   --options:host '&:tests=True' --options:host '&:xrpld=True'
 # Configure the build with CMake.
@@ -177,11 +162,45 @@ cmake --build . -j ${PARALLELISM}
 ./rippled --unittest --unittest-jobs ${PARALLELISM}
 ```
 
-#### Pushing the Docker image to the GitHub registry
+### Pushing the Docker image
+
+#### Logging into the GitHub registry
+
+To be able to push a Docker image to the GitHub registry, a personal access
+token is needed, see instructions [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).
+In summary, if you do not have a suitable personal access token, generate one
+[here](https://github.com/settings/tokens/new?scopes=write:packages).
+
+```shell
+GITHUB_USER=<your-github-username>
+GITHUB_TOKEN=<your-github-personal-access-token>
+echo ${GITHUB_TOKEN} | docker login ghcr.io -u "${GITHUB_USER}" --password-stdin
+```
+
+#### Pushing to the GitHub registry
 
-If you want to push the image to the GitHub registry, you can do so with the
-following command:
+To push the image to the GitHub registry, you can do so with the following
+command, whereby we append your username to not overwrite existing images:
 
 ```shell
-docker push ${CONTAINER_REGISTRY}/${CONTAINER_IMAGE}
+docker tag ${CONTAINER_IMAGE} ${CONTAINER_IMAGE}-sha-${GITHUB_USER}
+docker push ${CONTAINER_IMAGE}-sha-${GITHUB_USER}
 ```
+
+This way you can test the image in the `rippled` repository by modifying the
+`image_sha` entry in `.github/scripts/strategy-matrix/linux.json` for the
+relevant configuration, and then creating a pull request.
+
+Note, if you or the CI pipeline are pushing an image for the first time, it will
+be private by default. You will need to go to the
+[packages page](https://github.com/orgs/XRPLF/packages), select the relevant
+package, then "Package settings", and after clicking the "Change visibility"
+button make it "Public". In addition, on that same page, under "Manage Actions
+access" click the "Add repository" button, select the `ci` repository, and grant
+it "Admin" access.
+
+#### Note on macOS
+
+If you are using macOS and wish to push an image to the GitHub registry for use
+in GitHub Actions, you will need to append `--platform linux/amd64` to the
+`docker buildx build` commands above.

docker/gcc/README.md

@@ -19,54 +19,68 @@ Although the images will be built by a CI pipeline in this repository, if
 necessary a maintainer can build them manually by following the instructions
 below.
 
-### Logging into the GitHub registry
+### Building the Docker image
 
-To be able to push a Docker image to the GitHub registry, a personal access
-token is needed, see instructions [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).
-In summary, if you do not have a suitable personal access token, generate one
-[here](https://github.com/settings/tokens/new?scopes=write:packages).
-
-```shell
-CONTAINER_REGISTRY=ghcr.io
-GITHUB_USER=<your-github-username>
-GITHUB_TOKEN=<your-github-personal-access-token>
-echo ${GITHUB_TOKEN} | \
-docker login ${CONTAINER_REGISTRY} -u "${GITHUB_USER}" --password-stdin
-```
-
-### Building and pushing the Docker image
-
-Dockerfiles provided in this directory can be used to build an image for different GCC versions
-by specifying it as part of the the extension of a Dockerfile, e.g. `Dockerfile.12-bullseye`.
+Dockerfiles provided in this directory can be used to build an image for
+different GCC versions by specifying it as part of the extension of a
+Dockerfile, e.g. `Dockerfile.12-bullseye`.
 
 Even though in principle this repository can support different Debian releases,
 currently only Dockerfiles for Debian Bullseye are provided.
 
-#### Building the Docker image
-
 In order to build an image, run the commands below from the root directory of
 the repository.
 
-Ensure you've run the login command above to authenticate with the Docker
-registry.
-
 ```shell
 GCC_VERSION=12
 DEBIAN_VERSION=bullseye
-CONTAINER_IMAGE=xrplf/ci/gcc:${GCC_VERSION}-${DEBIAN_VERSION}
+CONTAINER_IMAGE=ghcr.io/xrplf/ci/gcc:${GCC_VERSION}-${DEBIAN_VERSION}
 
 docker buildx build . \
   --file docker/gcc/Dockerfile.${GCC_VERSION}-${DEBIAN_VERSION} \
   --build-arg BUILDKIT_DOCKERFILE_CHECK=skip=InvalidDefaultArgInFrom \
   --build-arg BUILDKIT_INLINE_CACHE=1 \
-  --tag ${CONTAINER_REGISTRY}/${CONTAINER_IMAGE}
+  --tag ${CONTAINER_IMAGE}
 ```
 
-#### Pushing the Docker image to the GitHub registry
+### Pushing the Docker image
 
-If you want to push the image to the GitHub registry, you can do so with the
-following command:
+#### Logging into the GitHub registry
+
+To be able to push a Docker image to the GitHub registry, a personal access
+token is needed, see instructions [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).
+In summary, if you do not have a suitable personal access token, generate one
+[here](https://github.com/settings/tokens/new?scopes=write:packages).
+
+```shell
+GITHUB_USER=<your-github-username>
+GITHUB_TOKEN=<your-github-personal-access-token>
+echo ${GITHUB_TOKEN} | docker login ghcr.io -u "${GITHUB_USER}" --password-stdin
+```
+
+#### Pushing to the GitHub registry
+
+To push the image to the GitHub registry, you can do so with the following
+command, whereby we append your username to not overwrite existing images:
 
 ```shell
-docker push ${CONTAINER_REGISTRY}/${CONTAINER_IMAGE}
+docker tag ${CONTAINER_IMAGE} ${CONTAINER_IMAGE}-${GITHUB_USER}
+docker push ${CONTAINER_IMAGE}-${GITHUB_USER}
 ```
+
+However, there should be no need to push the GCC image manually, as it is only
+used as a base image for other images in this repository.
+
+Note, if you or the CI pipeline are pushing an image for the first time, it will
+be private by default. You will need to go to the
+[packages page](https://github.com/orgs/XRPLF/packages), select the relevant
+package, then "Package settings", and after clicking the "Change visibility"
+button make it "Public". In addition, on that same page, under "Manage Actions
+access" click the "Add repository" button, select the `ci` repository, and grant
+it "Admin" access.
+
+#### Note on macOS
+
+If you are using macOS and wish to push an image to the GitHub registry for use
+in GitHub Actions, you will need to append `--platform linux/amd64` to the
+`docker buildx build` commands above.