[Git][reproducible-builds/reproducible-website][master] Add a guide for Dockerfile

[Chris Lamb (@lamby)]

Chris Lamb pushed to branch master at Reproducible Builds / reproducible-website


Commits:
461ab1eb by Akihiro Suda at 2024-06-26T17:31:23+09:00
Add a guide for Dockerfile

ref: https://github.com/moby/buildkit/blob/master/docs/build-repro.md

Applying the reproducible builds to the Docker Official Images (DOI) on
Docker Hub is being discussed in: https://github.com/docker-library/official-images/issues/16044
(waiting for the PRs linked there to be reviewed)

Signed-off-by: Akihiro Suda <akihiro.suda.cz at hco.ntt.co.jp>

- - - - -


2 changed files:

- _docs/source-date-epoch.md
- tools.md


Changes:

=====================================
_docs/source-date-epoch.md
=====================================
@@ -130,6 +130,61 @@ formatted_date = run_command(date_exe, '-u', '-d', '@' + source_date_epoch, '+%Y
 
 The above will work only with GNU `date`. See the POSIX shell example on how to support BSD date variants.
 
+### Dockerfile
+
+The `SOURCE_DATE_EPOCH` argument value is automaticallly propagated from the `SOURCE_DATE_EPOCH` environment value
+of the client host, since Docker Buildx v0.10.
+
+The `SOURCE_DATE_EPOCH` argument value can be captured as an environment value for `RUN` instructions, by putting an `ARG` instruction
+between `FROM` and `RUN`:
+```dockerfile
+FROM [...]
+ARG SOURCE_DATE_EPOCH
+RUN [...]
+```
+
+Capturing the `SOURCE_DATE_EPOCH` argument value is optional.
+Alternatively, the `SOURCE_DATE_EPOCH` environment value can be declared inside a `RUN` instruction too.
+```dockerfile
+FROM [...]
+ADD src /src
+RUN [...]
+  SOURCE_DATE_EPOCH="$(find /src -type f -exec stat -c '%Y' {} + | sort -nr | head -n1)"; \
+  export SOURCE_DATE_EPOCH; \
+# for logging validation/edification
+  date --date "@$SOURCE_DATE_EPOCH" --rfc-2822; \
+  [...]
+```
+
+#### Scope
+Regardless to whether the `SOURCE_DATE_EPOCH` argument value is captured into Dockerfile with `ARG SOURCE_DATE_EPOCH`,
+the argument value is also used for:
+- the `created` timestamp in the [OCI Image Config](https://github.com/opencontainers/image-spec/blob/main/config.md#properties)
+- the `created` timestamp in the `history` objects in the [OCI Image Config](https://github.com/opencontainers/image-spec/blob/main/config.md#properties)
+- the `org.opencontainers.image.created` annotation in the [OCI Image Index](https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys)
+- the timestamp of the files exported with the `local` exporter
+- the timestamp of the files exported with the `tar` exporter
+
+To apply the `SOURCE_DATE_EPOCH` argument value to the timestamps of the files inside the image,
+specify `rewrite-timestamp=true` as an image exporter option:
+```bash
+docker buildx create --use --name buildkit
+docker buildx build --output type=image,name=docker.io/username/image,push=true,rewrite-timestamp=true .
+```
+
+The `rewrite-timestamp` option is not set to `true` by default due to the overhead of rewriting image layers.
+
+#### apt-get
+`RUN apt-get` does not automatically consume `SOURCE_DATE_EPOCH` to install packages from the past snapshot.
+
+<https://github.com/reproducible-containers/repro-sources-list.sh> can be used for reconfiguring `/etc/apt/sources.list`
+to use `https://snapshot.debian.org/archive/debian/<SOURCE_DATE_EPOCH>/`.
+
+#### Further information
+See:
+- https://github.com/moby/buildkit/blob/master/docs/build-repro.md
+- https://github.com/docker-library/official-images/issues/16044
+
 ### C
 
 ```c
@@ -500,6 +555,7 @@ Complete:
 * [texi2html](https://bugs.debian.org/783475) (Debian `>=` 1.82+dfsg1-4, [needs forwarding](https://sources.debian.net/src/texi2html/1.82%2Bdfsg1-5/debian/patches/05_reproducible-build/))
 * [texlive-bin](https://bugs.debian.org/792202) (`>=` 2016.20160512.41045)
 * [txt2man](https://bugs.debian.org/790801) (`>=` [1.5.7](https://github.com/mvertes/txt2man/pull/1), Debian `>=` 1.5.6-4)
+* [docker buildx](https://github.com/docker/buildx/pull/1489) (`>=` 0.10)
 
 Or you can [search in all Debian sources](https://codesearch.debian.net/search?perpkg=1&q=SOURCE_DATE_EPOCH).
 


=====================================
tools.md
=====================================
@@ -108,6 +108,7 @@ changing the source code, changed the generated binaries.
 * [reproducible-build-maven-plugin](https://zlika.github.io/reproducible-build-maven-plugin) for the [Apache Maven](https://maven.apache.org) build tool, popular with Java projects.
 * [sbt-reproducible-builds](https://github.com/raboof/sbt-reproducible-builds#readme) plugin for the [sbt](https://www.scala-sbt.org/) build tool, popular with [Scala](https://www.scala-lang.org/) projects.
 * [apksigcopier](https://github.com/obfusk/apksigcopier) and [reproducible-apk-tools](https://github.com/obfusk/reproducible-apk-tools) for creating reproducible Android APKs and comparing APK (meta)data.
+* [diffoci](https://github.com/reproducible-containers/diffoci): diff for Docker and OCI (Open Container Initiative) container images
 
 ## Misc
 



View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/commit/461ab1ebc3ef45c39549222fba8d8063e31d8f0d

-- 
This project does not include diff previews in email notifications.
View it on GitLab: https://salsa.debian.org/reproducible-builds/reproducible-website/-/commit/461ab1ebc3ef45c39549222fba8d8063e31d8f0d
You're receiving this email because of your account on salsa.debian.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.reproducible-builds.org/pipermail/rb-commits/attachments/20240626/9f270c01/attachment.htm>