Add some docs about the docker images

docs/development/docker-images.rst

@@ -0,0 +1,106 @@
+HoneyBadgerMPC Docker Image
+===========================
+The Docker image for HoneyBadgerMPC is roughly made up of two main
+parts:
+
+1. HoneyBadgerMPC code-independent dependencies
+   (`initc3/honeybadgermpc-deps`_).
+2. HoneyBadgerMPC code-dependent and experimental dependencies
+   (`initc3/honeybadgermpc`__).
+
+In addition to distinguishing between dependencies that dependent on
+the HoneyBadgerMPC source code from those that do not, it is also
+useful to distinguish between dependencies that can be installed via
+a package management tool like ``apt`` or ``pip`` from dependencies
+that must be built and installed from their source code.
+
+1. Dependencies obtained from a package repository. (Examples:
+   `debian packages`_ or `PyPI`_.)
+2. Dependencies which must be installed from their source code.
+
+Some dependencies that must be installed from their source code can
+take a lot of time to build and in these cases it may be convenient
+to provide standalone Docker images that contain the pre-built binaries
+and headers. The parent image of HoneyBadgerMPC makes use of such
+images:
+
+* `FLINT`_
+* `NTL`_
+* `PBC`_
+* `Charm-crypto`_
+* `Rust nightly frozen`_
+
+
+HoneyBadgerMPC code-independent dependencies
+--------------------------------------------
+The Docker image for HoneyBadgerMPC is built from the parent image
+`initc3/honeybadgermpc-deps`_. This parent image contains core
+dependencies that do not need any of the HoneyBadgerMPC code or context
+from the HoneyBadgerMPC source repository. NTL or Rust are examples of
+such dependencies. The ``Dockerfile`` for the parent image is
+maintained in `initc3/docker-honeybadgermpc-deps`_.
+
+HoneyBadgerMPC code-dependent and experimental dependencies
+-----------------------------------------------------------
+The HoneyBadgerMPC main image contains dependencies that rely on the
+source code. Examples of such dependencies are the Rust/Python based
+`pairing`_ library and the C++ based asynchromix `compute-power-sums`_
+program. Dependencies required for integration or experimentation
+purposes can be added to the main image as well. For example,
+``solidity`` is part of the main image as it is necessary for an
+integration with the Ethereum testnet (see `asynchromix.sol`_ and
+`asynchromix.py`_). The ``Dockerfile`` for the main image is maintained
+in `initc3/HoneyBadgerMPC`__.
+
+Workflows
+---------
+Changes to the parent or main Docker image may be needed for various
+reasons. This section presents some suggestions on how to go about to
+perform the necessary changes.
+
+Adding, or modifying a core dependency
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For dependencies that can be added via a package manager like ``apt``
+or ``pip`` you can simply add, or update the version of the dependency
+using the package manager.
+
+For dependencies that must be built from source, adding or modifying
+the dependency can be done in three or four phases:
+
+1. Modify the main image, by modifying the `Dockerfile
+   <https://github.com/initc3/HoneyBadgerMPC/blob/dev/Dockerfile>`_
+   under ``initc3/HoneyBadgerMPC``.
+2. Create a standalone image such as `NTL`_.
+3. Using the standalone image as a stage add the dependency to the main
+   or parent image. See `Use an external image as a "stage"`_.
+4. If adding the dependency to the parent image, then change the
+   sha256 digest of the parent image in the ``FROM`` statements in the
+   main image.
+
+A core dependency (that does not depend on the source code of
+HoneyBadgerMPC) can always be added to the main image first, and moved
+to the parent image at a later time. This may be convenient for
+testing, experimentation or troubleshooting purposes.
+
+Modifying an existing core dependency can also be done in the main
+image. For instance, if the goal was to upgrade an existing dependency,
+like the Rust version, this could be done first in the main image by
+installing the new version and making it the default one.
+
+
+.. __: https://hub.docker.com/repository/docker/initc3/honeybadgermpc
+.. __: https://github.com/initc3/HoneyBadgerMPC
+.. _initc3/honeybadgermpc-deps: https://hub.docker.com/repository/docker/initc3/honeybadgermpc-deps
+.. _initc3/docker-honeybadgermpc-deps: https://github.com/initc3/docker-honeybadgermpc-deps
+.. _pairing: https://github.com/initc3/HoneyBadgerMPC/tree/dev/pairing<Paste>
+.. _compute-power-sums: https://github.com/initc3/HoneyBadgerMPC/blob/dev/apps/asynchromix/cpp/compute-power-sums.cpp
+.. _asynchromix.sol: https://github.com/initc3/HoneyBadgerMPC/blob/dev/apps/asynchromix/asynchromix.sol
+.. _asynchromix.py: https://github.com/initc3/HoneyBadgerMPC/blob/dev/apps/asynchromix/asynchromix.py
+.. _debian packages: https://www.debian.org/distrib/packages
+.. _pypi: https://pypi.org/
+.. _FLINT: https://hub.docker.com/repository/docker/initc3/flint2
+.. _NTL: https://hub.docker.com/repository/docker/initc3/ntl
+.. _PBC: https://hub.docker.com/repository/docker/initc3/pbc
+.. _Charm-crypto: https://hub.docker.com/repository/docker/initc3/charm-crypto
+.. _Rust nightly frozen: https://hub.docker.com/repository/docker/initc3/rust-frozen
+.. _Use an external image as a "stage": https://docs.docker.com/develop/develop-images/multistage-build/#use-an-external-image-as-a-stage

docs/index.rst

@@ -58,6 +58,7 @@
 
     development/getting-started
     development/contributing
+    development/docker-images
     development/reviewing-contributions
     ci
     packaging