contrib/docker_notes.md: add notes re debian apt mirror, and envvars

related https://github.com/spesmilo/electrum/issues/8496

contrib/android/Readme.md

@@ -15,7 +15,9 @@ similar system.
 
 1. Install Docker
 
-    See `contrib/docker_notes.md`.
+    See [`contrib/docker_notes.md`](../docker_notes.md).
+
+    (worth reading even if you already have docker)
 
 2. Build binaries
 
@@ -27,7 +29,7 @@ similar system.
 
     If you want reproducibility, try instead e.g.:
     ```
-    $ ELECBUILD_COMMIT=HEAD ELECBUILD_NOCACHE=1 ./build.sh qml all release-unsigned
+    $ ELECBUILD_COMMIT=HEAD ./build.sh qml all release-unsigned
     ```
 
 3. The generated binary is in `./dist`.

contrib/build-linux/appimage/README.md

@@ -14,7 +14,9 @@ see [issue #5159](https://github.com/spesmilo/electrum/issues/5159).
 
 1. Install Docker
 
-    See `contrib/docker_notes.md`.
+    See [`contrib/docker_notes.md`](../../docker_notes.md).
+
+    (worth reading even if you already have docker)
 
 2. Build binary
 
@@ -23,7 +25,7 @@ see [issue #5159](https://github.com/spesmilo/electrum/issues/5159).
     ```
     If you want reproducibility, try instead e.g.:
     ```
-    $ ELECBUILD_COMMIT=HEAD ELECBUILD_NOCACHE=1 ./build.sh
+    $ ELECBUILD_COMMIT=HEAD ./build.sh
     ```
 
 3. The generated binary is in `./dist`.

contrib/build-linux/sdist/README.md

@@ -19,7 +19,9 @@ the source-only one, also includes:
 
 1. Install Docker
 
-    See `contrib/docker_notes.md`.
+    See [`contrib/docker_notes.md`](../../docker_notes.md).
+
+    (worth reading even if you already have docker)
 
 2. Build tarball
 

contrib/build-wine/README.md

@@ -8,7 +8,9 @@ similar system.
 
 1. Install Docker
 
-    See `contrib/docker_notes.md`.
+    See [`contrib/docker_notes.md`](../docker_notes.md).
+
+    (worth reading even if you already have docker)
 
     Note: older versions of Docker might not work well
     (see [#6971](https://github.com/spesmilo/electrum/issues/6971)).
@@ -21,7 +23,7 @@ similar system.
     ```
     If you want reproducibility, try instead e.g.:
     ```
-    $ ELECBUILD_COMMIT=HEAD ELECBUILD_NOCACHE=1 ./build.sh
+    $ ELECBUILD_COMMIT=HEAD ./build.sh
     ```
 
 3. The generated binaries are in `./contrib/build-wine/dist`.
@@ -33,7 +35,7 @@ similar system.
 Electrum Windows builds are signed with a Microsoft Authenticode™ code signing
 certificate in addition to the GPG-based signatures.
 
-The advantage of using Authenticode is that Electrum users won't receive a 
+The advantage of using Authenticode is that Electrum users won't receive a
 Windows SmartScreen warning when starting it.
 
 The release signing procedure involves a signer (the holder of the
@@ -57,7 +59,7 @@ certificate/key) and one or multiple trusted verifiers:
 
 ## Verify Integrity of signed binary
 
-Every user can verify that the official binary was created from the source code in this 
+Every user can verify that the official binary was created from the source code in this
 repository. To do so, the Authenticode signature needs to be stripped since the signature
 is not reproducible.
 

contrib/docker_notes.md

@@ -1,4 +1,28 @@
-# Notes about using Docker in the build scripts
+# Using the build scripts
+
+Most of our build scripts are docker-based.
+(All, except the macOS build, which is a separate beast and always has to be special-cased
+at the cost of significant maintenance burden...)
+
+Typically, the build flow is:
+
+- build a docker image, based on debian
+  - the apt sources mirror used is `snapshot.debian.org`
+    - (except for the source tarball build, which is simple enough not to need this)
+    - this helps with historical reproducibility
+    - note that `snapshot.debian.org` is often slow and sometimes keeps timing out :/
+      (see #8496)
+      - a potential alternative would be `snapshot.notset.fr`, but that mirror is missing
+        e.g. `binary-i386`, which is needed for the wine/windows build.
+    - if you are just trying to build for yourself and don't need reproducibility,
+      you can just switch back to the default debian apt sources mirror.
+  - docker caches the build (locally), and so this step only needs to be rerun
+    if we update the Dockerfile. This caching happens automatically and by default.
+    - you can disable the caching by setting envvar `ELECBUILD_NOCACHE=1`. See below.
+- create a docker container from the image, and build the final binary inside the container
+
+
+## Notes about using Docker
 
 - To install Docker:
 
@@ -18,4 +42,27 @@
   $ sudo usermod -aG docker ${USER}
   ```
   (and then reboot or similar for it to take effect)
-  
+
+
+## Environment variables
+
+- `ELECBUILD_COMMIT`
+
+    When unset or empty, we build directly from the local git clone. These builds
+    are *not* reproducible.
+
+    When non-empty, it should be set to a git ref. We will create a fresh git clone
+    checked out at that reference in `/tmp/electrum_build/`, and build there.
+
+- `ELECBUILD_NOCACHE=1`
+
+    A non-empty value forces a rebuild of the docker image.
+
+    Before we started using `snapshot.debian.org` for apt sources,
+    setting this was necessary to properly test historical reproducibility.
+    (we were version-pinning packages installed using `apt`, but it was not realistic to
+     version-pin all transitive dependencies, and sometimes an update of those resulted in
+     changes to our binary builds)
+
+    I think setting this is no longer necessary for building reproducibly.
+