more information about build container

docs/development/dockerbuildmaint.rst

@@ -1,12 +1,21 @@
-Docker Build Maintenance
-========================
+.. _build_container:
 
-Get your Quay account squared away
------------------------------------
-The container that performs builds of Debian packages is version controlled in
-a docker repository at **quay.io/freedomofpress/sd-docker-builder**.
-There are tight restrictions over who can make edits here. If you have permissions
-to do so, you'll need to make sure your local docker client has credentials to push.
+Build container
+===============
+We use a Docker build container to build our debian packages for SecureDrop (via ``make build-debs``
+in the ``securedrop`` Github repository root directory). We keep images of this our container in a
+Docker repository at **quay.io/freedomofpress**. The images are organized by Ubuntu release
+version. For instance, you can find the images for Xenial at
+**quay.io/freedomofpress/sd-docker-builder-xenial** and, for Focal, at
+**quay.io/freedomofpress/sd-docker-builder-focal**.
+
+Maintaining images of our bulid container for each release is our way of recording the exact version
+of each dependency used to build our production debian packages for SecureDrop.
+
+Who can update the build container?
+===================================
+There are tight restrictions over who can make edits to our Docker repository. If you have
+permissions to do so, you'll need to make sure your local Docker client has credentials to push.
 
 * First login into your quay.io account via the web-portal at https://quay.io/
 * Drill into your **Account settings** via the upper right drop-down (where your username is)
@@ -15,12 +24,16 @@ to do so, you'll need to make sure your local docker client has credentials to p
   obtained from the previous step.
 * Proceed with update instructions
 
+Updating the build container
+============================
+We know the build container needs to be updated when **test_ensure_no_updates_avail** fails during
+``make build-debs`` in the ``securedrop`` Github reprository root directory. This test fails if any
+of the dependencies of the build container require security updates. If you have access rights to
+push to quay.io, then you can build and push a new container to the Quay repository by
+following the steps below.
 
-Performing container updates
-----------------------------
-If one of the dependencies requires security updates, the build may fail at
-**test_ensure_no_updates_avail** . If you have access rights to push to quay.io,
-here is the process to build and push a new container:
+.. note:: The reason we don't update the container at runtime is that we use the container image as
+          a way of recording our build environment.
 
 .. code:: sh
 
@@ -41,4 +54,4 @@ You can now test the container by going back to the SecureDrop repository root:
     cd ../..
     make build-debs
 
-Assuming no errors here, commit the changes in ``molecule/builder/image_hash`` in a branch containing the prefix ``update-builder-``.
+Assuming no errors here, commit the changes in ``molecule/builder/image_hash`` in a branch containing the prefix ``update-builder-``.

docs/development/release_management.rst

@@ -43,11 +43,12 @@ Pre-Release
    goal is to make sure we test against the lastest Tails release, including release candidates,
    so that we can report bugs early to Tails.
 
-#. Check if there is a new stable release of Tor that can be QAed and released as part of the
-   SecureDrop release. Also check for any new release candidates so that we're aware of any
-   upcoming major bug fixes and communicate them to the team. You can find releases by checking the
-   `Tor blog <https://blog.torproject.org/category/tags/stable-release>`_. If there is a new
-   stable release, file an issue and upgrade Tor following these steps:
+#. Check the Tor blog for new
+   `release candidates <https://blog.torproject.org/category/tags/release-candidate>`_ and new
+   `stable releases <https://blog.torproject.org/category/tags/stable-release>`_. Let the team
+   know about any new release candidates during the SecureDrop release process in case there are
+   critical bug fixes. For a new stable release, file an issue and upgrade Tor following these
+   steps:
 
       a. Bump the version in `fetch-tor-packages
          <https://github.com/freedomofpress/securedrop/blob/develop/molecule/fetch-tor-packages/
@@ -127,23 +128,30 @@ Pre-Release
 #. Build Debian packages:
 
    a. Check out the tag for the release candidate.
-   #. Build the packages with ``make build-debs``.
-   #. Build logs should be saved and published according to the `build
-      log guidelines
+   b. Build the packages with ``make build-debs``
+
+     .. note:: If the :ref:`build container <build_container>` used by ``make build-debs`` has
+               security updates, then you will see ``test_ensure_no_updates_avail`` fail in the
+               build output. To get around the bottleneck of tight restrictions around who can
+               update the build container, you can ignore this test failure until you are building a
+               production release.
+
+   c. Build logs should be saved and published according to the `build log guidelines
       <https://github.com/freedomofpress/securedrop/wiki/Build-logs>`_.
-   #. Open a PR on `securedrop-dev-packages-lfs
+   d. Open a PR on `securedrop-dev-packages-lfs
       <https://github.com/freedomofpress/securedrop-dev-packages-lfs>`_ that targets the ``main``
       branch with the new debs. Do not include tarballs or any debs that would overwrite
       existing debs. Changes merged to this branch will be published to ``apt-test.freedom.press``
       within 15 minutes.
 
-   .. warning:: Only commit deb packages with an incremented version number: do not clobber existing
-                packages. That is, if there is already a deb called e.g.
-                ``ossec-agent-3.6.0-amd64.deb`` in ``main``, do not commit a new version of this
-                deb.
+     .. warning:: Only commit deb packages with an incremented version number: do not clobber
+                  existing packages. That is, if there is already a deb called e.g.
+                  ``ossec-agent-3.6.0-amd64.deb`` in ``main``, do not commit a new version of this
+                  deb.
 
-   .. note:: If the release contains other packages not created by ``make build-debs``, such as Tor
-             or kernel updates, make sure that they also get pushed to ``apt-test.freedom.press``.
+     .. note:: If the release contains other packages not created by ``make build-debs``, such as
+               Tor or kernel updates, make sure that they also get pushed to
+               ``apt-test.freedom.press``.
 
 #. Write a test plan that focuses on the new functionality introduced in the release. Post for
    feedback and make changes based on suggestions from the community. Once it's ready, publish the