Add some explanatory comments around the various docker images we use.

Change-Id: I33867840df49ac3146f8bfac6fd5001635bf73a4

Author: ernoc

Dockerfile

@@ -1,3 +1,5 @@
+# Docker image we use to run CI. Build with scripts/docker_build.
+# Open a shell to this image with scripts/docker_sh.
 # Use a fixed snapshot of the base image to create a deterministic environment.
 # Snapshot tags can be found at https://hub.docker.com/_/debian/tags
 ARG image_digest=sha256:f528891ab1aa484bf7233dbcc84f3c806c3e427571d75510a9d74bb5ec535b33

WORKSPACE

@@ -252,21 +252,35 @@ oci_register_toolchains(
 
 load("@rules_oci//oci:pull.bzl", "oci_pull")
 
+# This is the base docker image we use to bundle example apps like hello world
+# trusted apps. We don't build these, we pull them from the existing repo.
+#
+# E.g.: //oak_containers/examples/hello_world/trusted_app:bundle . You can find
+# these images at: gcr.io/distroless/cc-debian12 . We do not need root access
+# so you can search with ":nonroot" (gcr.io/distroless/cc-debian12:nonroot) or
+# "latest" (gcr.io/distroless/cc-debian12:latest). Note files tagged as ".sig"
+# or ".att" do not contain images. You can find a given digest (like the one
+# below) at http://gcr.io/distroless/cc-debian12@{digest} where {digest}
+# includes the "sha256:" bit.
 oci_pull(
     name = "distroless_cc_debian12",
     digest = "sha256:6714977f9f02632c31377650c15d89a7efaebf43bab0f37c712c30fc01edb973",
     image = "gcr.io/distroless/cc-debian12",
     platforms = ["linux/amd64"],
 )
 
+# System image for Oak Containers
+# We build these (see oak_containers/system_image) and push them to the repo below before
+# this snippet can pull them.
 # This image is based on debian:stable-20240612
 oci_pull(
     name = "oak_containers_sysimage_base",
     digest = "sha256:4844b899dcb44420d368bfe24dca856d01a8483d6976fbee292227f601d69940",
     image = "europe-west2-docker.pkg.dev/oak-ci/oak-containers-sysimage-base/oak-containers-sysimage-base",
 )
 
-# This image is based on debian:stable-20240612
+# Same as previous, for Nvidia GPU support (see
+# oak_containers/system_image/README.md). Based on debian:stable-20240612 .
 oci_pull(
     name = "oak_containers_nvidia_sysimage_base",
     digest = "sha256:9e69576783ad3c0a420bcb978dec53da5de6fd1a304b9b0f9d6c6bc6f188e894",

oak_containers/system_image/Dockerfile

@@ -1,3 +1,4 @@
+# Deprecated - use base_image.Dockerfile or nvidia version, see README.md.
 # debian:stable-20240612
 ARG debian_snapshot=sha256:26878d0d3aa5e1980d6f8060b4af32fc48b8edeb1fc4d2d074a13a04b17c95f2
 FROM debian@${debian_snapshot}

oak_containers/system_image/README.md

@@ -6,6 +6,8 @@
 
 # System Image Build Tools
 
+We use this Docker image to build the base system image for Oak Containers.
+
 ## Full System Image Tools
 
 `build-old.sh` and `Dockerfile`
@@ -56,6 +58,13 @@ How this works:
 
 5. `oci_runtime_bundle` exports the bundle to a tarball that we can use.
 
+## Sysroot
+
+We use this to get a full, consistent set of libraries, tools and compilers, and
+extract them to make a sysroot. The plan is to plug this sysroot into Bazel to
+get a consistent toolchain. This image is not used to run anything at the
+moment.
+
 # Current Issues/Improvements
 
 - The bazel version should eventually be full bazel, and not require running any

oak_containers/system_image/base_image.Dockerfile

@@ -1,4 +1,6 @@
-# debian:stable-20240612
+# System Image for Oak Containers. Contains base Debian plus binaries and 
+# configs to run Oak. This MUST be based on a stable Debian image.
+# debian:stable-20240612 - https://hub.docker.com/_/debian/tags
 ARG debian_snapshot=sha256:26878d0d3aa5e1980d6f8060b4af32fc48b8edeb1fc4d2d074a13a04b17c95f2
 FROM debian@${debian_snapshot}
 
@@ -8,10 +10,14 @@ SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 # This takes advantage of the fact that the base image contains the snapshot
 # URL as a comment in /etc/apt/sources.list.d/debian.sources, with a switch
 # to snapshot-cloudflare in case it has higher availability.
+# NOTE: Using snapshot-cloudflare may cause issues in future image bases.
+# If you get errors like b/365523488#comment60, remove the following block.
+# Tracking: b/369706690.
 RUN sed -i -e '/^URIs/d' \
     -e '/^# http:\/\/snapshot/{s/#/URIs:/;s/snapshot/snapshot-cloudflare/}' \
     -e '/^Signed-By/a\Check-Valid-Until: no' \
     /etc/apt/sources.list.d/debian.sources
+
 RUN apt-get --yes update \
     && apt-get install --yes --no-install-recommends \
     systemd systemd-sysv dbus udev runc \

oak_containers/system_image/sysroot.Dockerfile

@@ -1,3 +1,10 @@
+# Builds a Docker image from which we can extract a sysroot.
+
+# At the moment we don't use this image to run anything - only to copy out
+# the sysroot (essesntially, C libraries and tools). The goal is to plug this
+# sysroot into Bazel C toolchains so as to align compiler and library versions
+# at build time (Bazel) and at runtime (e.g. containers system image).
+
 # The expectation is that we build `base_image.Dockerfile` before this one.
 # hadolint ignore=DL3007
 FROM oak-containers-sysimage-base:latest