Merge branch 'develop' into straggler-tests

.dockerignore

@@ -1,3 +1,3 @@
-.git
 *.egg-info
 build
+venv

.github/workflows/tr_docker_gramine_direct.yml

@@ -25,6 +25,10 @@ jobs:
         python -m pip install --upgrade pip
         pip install .
 
+    - name: Build base image
+      run: |
+        docker build -t openfl -f openfl-docker/Dockerfile.base .
+
     - name: Create workspace image
       run: |
         fx workspace create --prefix example_workspace --template keras/mnist
@@ -35,7 +39,7 @@ jobs:
         # https://github.com/gramineproject/examples/issues/33
         sed -i 's/write_logs: true/write_logs: false/g' plan/plan.yaml
 
-        fx workspace dockerize --save --revision https://github.com/${GITHUB_REPOSITORY}.git@${{ github.event.pull_request.head.sha }}
+        fx workspace dockerize --base-image openfl --save
 
     - name: Create certificate authority for workspace
       run: |

.github/workflows/tr_docker_native.yml

@@ -25,12 +25,16 @@ jobs:
         python -m pip install --upgrade pip
         pip install .
 
+    - name: Build base image
+      run: |
+        docker build -t openfl -f openfl-docker/Dockerfile.base .
+
     - name: Create workspace image
       run: |
         fx workspace create --prefix example_workspace --template keras/mnist
         cd example_workspace
         fx plan initialize -a localhost
-        fx workspace dockerize --save --revision https://github.com/${GITHUB_REPOSITORY}.git@${{ github.event.pull_request.head.sha }}
+        fx workspace dockerize --base-image openfl --save
 
     - name: Create certificate authority for workspace
       run: |

docs/installation.rst

@@ -0,0 +1,80 @@
+Installation
+============
+
+This document provides instructions for installing OpenFL; either in a Python virtual environment or as a docker container.
+
+Using ``pip``
+-----------
+
+We recommend using a Python virtual environment. Refer to the `venv installation guide <https://docs.python.org/3/library/venv.html>`_ for details.
+
+* From PyPI (latest stable release):
+
+  .. code-block:: bash
+
+    pip install openfl
+
+* For development (editable build):
+
+  .. code-block:: bash
+
+    git clone https://github.com/securefederatedai/openfl.git && cd openfl
+    pip install -e .
+
+* Nightly (from the tip of `develop` branch):
+
+  .. code-block:: bash
+
+    pip install git+https://github.com/securefederatedai/openfl.git@develop
+
+Verify installation using the ``fx --help`` command.
+
+.. code-block:: bash
+
+  OpenFL - Open Federated Learning                                                
+
+  BASH COMPLETE ACTIVATION
+
+  Run in terminal:
+  _FX_COMPLETE=bash_source fx > ~/.fx-autocomplete.sh
+  source ~/.fx-autocomplete.sh
+  If ~/.fx-autocomplete.sh already exists:
+  source ~/.fx-autocomplete.sh
+
+  CORRECT USAGE
+
+  fx [options] [command] [subcommand] [args]
+
+  GLOBAL OPTIONS
+
+  -l, --log-level TEXT  Logging verbosity level.
+  --no-warnings         Disable third-party warnings.
+  --help                Show this message and exit.
+
+  AVAILABLE COMMANDS
+  ...
+
+Using ``docker``
+--------------
+
+This method can be used to run federated learning experiments in an isolated environment. Install and verify installation of Docker engine on all nodes in the federation. Refer to the Docker installation `guide <https://docs.docker.com/engine/install/>`_ for details.
+
+* Pull the latest image:
+
+  .. code-block:: bash
+
+    docker pull ghcr.io/securefederatedai/openfl:latest
+
+* Build from source:
+
+  .. code-block:: bash
+
+    git clone https://github.com/securefederatedai/openfl.git && cd openfl
+    git checkout develop
+
+  .. code-block:: bash
+
+    docker build -t openfl -f openfl-docker/Dockerfile.base .
+
+  .. note::
+    This command copies current context (i.e. OpenFL root directory) to the base image. Ensure that the ``.dockerignore`` file is configured to exclude unnecessary files and directories (like secrets or local virtual environments).

openfl-docker/Dockerfile.base

@@ -2,7 +2,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # ------------------------------------
 # OpenFL Base Image w/ Gramine support
-# $> docker build . -t openfl -f Dockerfile.base [--build-arg OPENFL_REVISION=GIT_URL@COMMIT_ID]
 # ------------------------------------
 FROM ubuntu:22.04 AS base
 
@@ -43,8 +42,9 @@ RUN --mount=type=cache,id=apt-dev,target=/var/cache/apt \
     rm -rf /var/lib/apt/lists/*
 
 # Install OpenFL.
-ARG OPENFL_REVISION=https://github.com/securefederatedai/openfl.git@develop
-RUN pip install --no-cache-dir git+${OPENFL_REVISION} && \
+WORKDIR /repo
+COPY . .
+RUN pip install --no-cache-dir . && \
     INSTALL_SOURCES=yes /opt/venv/lib/python3.10/site-packages/openfl-docker/licenses.sh
 
 # Create an unprivileged user.

openfl/interface/workspace.py

@@ -385,14 +385,14 @@ def export_() -> str:
     "--save",
     is_flag=True,
     default=False,
-    help="Export the docker image as ``<workspace_name>.tar`` file.",
+    help="Export the workspace image as ``<workspace_name>.tar`` file.",
     show_default=True,
 )
 @option(
     "--rebuild",
     is_flag=True,
     default=False,
-    help="If set, rebuilds docker images with ``--no-cache`` option.",
+    help="If set, rebuilds workspace image with ``--no-cache`` option.",
     show_default=True,
 )
 @option(
@@ -407,46 +407,33 @@ def export_() -> str:
     ),
 )
 @option(
-    "--revision",
+    "--base-image",
+    "base_image",
     required=False,
-    default=None,
+    default="ghcr.io/securefederatedai/openfl:latest",
     help=(
-        "Optional, version of OpenFL source code to build base image from. "
-        "If unspecified, default value in `Dockerfile.base` will be used, "
-        "typically the latest stable release. "
-        "Format: ``OPENFL_GIT_URL@<COMMIT_ID/BRANCH>``"
+        "OpenFL base image to use for creating a workspace. "
+        "If unspecified, default latest base image will be pulled. "
+        "To build a base image from source, follow docker build "
+        "`instructions. <https://openfl.readthedocs.io/en/latest/installation.html#using-docker>`_ "
+        "Format: ``IMAGE_URI:TAG``"
     ),
+    show_default=True,
 )
 @pass_context
-def dockerize_(context, save: bool, rebuild: bool, enclave_key: str, revision: str):
+def dockerize_(context, save: bool, rebuild: bool, enclave_key: str, base_image: str):
     """Packages current workspace as a TEE-ready docker image."""
 
-    # Docker build options
-    options = []
-    options.append("--no-cache" if rebuild else "")
-    options.append(f"--build-arg OPENFL_REVISION={revision}" if revision else "")
-    options = " ".join(options)
-
     # Export workspace
     archive = context.invoke(export_)
     workspace_name, _ = archive.split(".")
 
-    # Build OpenFL base image.
-    logging.info("Building OpenFL Base image")
-    base_image_build_cmd = (
-        "DOCKER_BUILDKIT=1 docker build {options} -t {image_name} -f {dockerfile} {build_context}"
-    ).format(
-        options=options,
-        image_name="openfl",
-        dockerfile=os.path.join(SITEPACKS, "openfl-docker", "Dockerfile.base"),
-        build_context=".",
-    )
-    _execute(base_image_build_cmd)
-
     # Build workspace image.
     options = []
     options.append("--no-cache" if rebuild else "")
+    options.append(f"--build-arg BASE_IMAGE={base_image}")
     options = " ".join(options)
+    logging.info(f"Using base image: {base_image}")
     if enclave_key is None:
         _execute("openssl genrsa -out key.pem -3 3072")
         enclave_key = os.path.abspath("key.pem")