diff --git a/docs/development/docker-images.rst b/docs/development/docker-images.rst new file mode 100644 index 000000000..3a43015b1 --- /dev/null +++ b/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 + `_ + 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 +.. _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 diff --git a/docs/index.rst b/docs/index.rst index bedda67dc..3e1942834 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -58,6 +58,7 @@ development/getting-started development/contributing + development/docker-images development/reviewing-contributions ci packaging