diff --git a/.github/workflows/docker-server.yml b/.github/workflows/docker-server.yml index 8233b5206d49..f580a8e9a280 100644 --- a/.github/workflows/docker-server.yml +++ b/.github/workflows/docker-server.yml @@ -7,8 +7,8 @@ on: description: "Version of Flower e.g. (1.6.0)." required: true type: string - base-image-version: - description: "Version of the Flower base image." + base-image-tag: + description: "The tag of the Flower base image." required: false type: string default: "py3.11-ubuntu22.04" @@ -27,9 +27,9 @@ jobs: file-dir: src/docker/server build-args: | FLWR_VERSION=${{ github.event.inputs.flwr-version }} - BASE_IMAGE_VERSION=${{ github.event.inputs.base-image-version }} + BASE_IMAGE_TAG=${{ github.event.inputs.base-image-tag }} tags: | - ${{ github.event.inputs.flwr-version }}-${{ github.event.inputs.base-image-version }} + ${{ github.event.inputs.flwr-version }}-${{ github.event.inputs.base-image-tag }} ${{ github.event.inputs.flwr-version }} latest secrets: diff --git a/doc/source/contributor-how-to-build-docker-images.rst b/doc/source/contributor-how-to-build-docker-images.rst new file mode 100644 index 000000000000..d85e48155de0 --- /dev/null +++ b/doc/source/contributor-how-to-build-docker-images.rst @@ -0,0 +1,135 @@ +How to build Docker Flower images locally +========================================= + +Flower provides pre-made docker images on `Docker Hub `_ +that include all necessary dependencies for running the server. You can also build your own custom +docker images from scratch with a different version of Python or Ubuntu if that is what you need. +In this guide, we will explain what images exist and how to build them locally. + +Before we can start, we need to meet a few prerequisites in our local development environment. + +#. Clone the flower repository. + + .. code-block:: bash + + $ git clone https://github.com/adap/flower.git && cd flower + +#. Verify the Docker daemon is running. + + Please follow the first section on + `Run Flower using Docker `_ + which covers this step in more detail. + +Currently, Flower provides two images, a base image and a server image. There will also be a client +image soon. The base image, as the name suggests, contains basic dependencies that both the server +and the client need. This includes system dependencies, Python and Python tools. The server image is +based on the base image, but it additionally installs the Flower server using ``pip``. + +The build instructions that assemble the images are located in the respective Dockerfiles. You +can find them in the subdirectories of ``src/docker``. + +Both, base and server image are configured via build arguments. Through build arguments, we can make +our build more flexible. For example, in the base image, we can specify the version of Python to +install using the ``PYTHON_VERSION`` build argument. Some of the build arguments have default +values, others must be specified when building the image. All available build arguments for each +image are listed in one of the tables below. + +Building the base image +----------------------- + +.. list-table:: + :widths: 25 45 15 15 + :header-rows: 1 + + * - Build argument + - Description + - Required + - Example + * - ``PYTHON_VERSION`` + - Version of ``python`` to be installed. + - Yes + - ``3.11`` + * - ``PIP_VERSION`` + - Version of ``pip`` to be installed. + - Yes + - ``23.0.1`` + * - ``SETUPTOOLS_VERSION`` + - Version of ``setuptools`` to be installed. + - Yes + - ``69.0.2`` + * - ``UBUNTU_VERSION`` + - Version of the official Ubuntu Docker image. + - Defaults to ``22.04``. + - + +The following example creates a base image with Python 3.11.0, pip 23.0.1 and setuptools 69.0.2: + +.. code-block:: bash + + $ cd src/docker/base/ + $ docker build \ + --build-arg PYTHON_VERSION=3.11.0 \ + --build-arg PIP_VERSION=23.0.1 \ + --build-arg SETUPTOOLS_VERSION=69.0.2 \ + -t flwr_base:0.1.0 . + +The name of image is ``flwr_base`` and the tag ``0.1.0``. Remember that the build arguments as well +as the name and tag can be adapted to your needs. These values serve as examples only. + +Building the server image +------------------------- + +.. list-table:: + :widths: 25 45 15 15 + :header-rows: 1 + + * - Build argument + - Description + - Required + - Example + * - ``BASE_REPOSITORY`` + - The repository name of the base image. + - Defaults to ``flwr/server``. + - + * - ``BASE_IMAGE_TAG`` + - The image tag of the base image. + - Defaults to ``py3.11-ubuntu22.04``. + - + * - ``FLWR_VERSION`` + - Version of Flower to be installed. + - Yes + - ``1.6.0`` + +The following example creates a server image with the official Flower base image py3.11-ubuntu22.04 +and Flower 1.6.0: + +.. code-block:: bash + + $ cd src/docker/server/ + $ docker build \ + --build-arg BASE_IMAGE_TAG=py3.11-ubuntu22.04 \ + --build-arg FLWR_VERSION=1.6.0 \ + -t flwr_server:0.1.0 . + +The name of image is ``flwr_server`` and the tag ``0.1.0``. Remember that the build arguments as well +as the name and tag can be adapted to your needs. These values serve as examples only. + +If you want to use your own base image instead of the official Flower base image, all you need to do +is set the ``BASE_REPOSITORY`` and ``BASE_IMAGE_TAG`` build arguments. The value of +``BASE_REPOSITORY`` must match the name of your image and the value of ``BASE_IMAGE_TAG`` must match +the tag of your image. + +.. code-block:: bash + + $ cd src/docker/server/ + $ docker build \ + --build-arg BASE_REPOSITORY=flwr_base \ + --build-arg BASE_IMAGE_TAG=0.1.0 \ + --build-arg FLWR_VERSION=1.6.0 \ + -t flwr_server:0.1.0 . + +After creating the image, we can test whether the image is working: + +.. code-block:: bash + + $ docker run --rm flwr_server:0.1.0 --help diff --git a/doc/source/index.rst b/doc/source/index.rst index f7a4ec3daeda..c4e91b100cc0 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -167,6 +167,7 @@ The Flower community welcomes contributions. The following docs are intended to contributor-how-to-write-documentation contributor-how-to-release-flower contributor-how-to-contribute-translations + contributor-how-to-build-docker-images .. toctree:: :maxdepth: 1 diff --git a/src/docker/server/Dockerfile b/src/docker/server/Dockerfile index 9bf3214bb42c..c42246b16104 100644 --- a/src/docker/server/Dockerfile +++ b/src/docker/server/Dockerfile @@ -1,7 +1,8 @@ # Copyright 2023 Flower Labs GmbH. All Rights Reserved. -ARG BASE_IMAGE_VERSION=py3.11-ubuntu22.04 -FROM flwr/base:$BASE_IMAGE_VERSION as server +ARG BASE_REPOSITORY=flwr/base +ARG BASE_IMAGE_TAG=py3.11-ubuntu22.04 +FROM $BASE_REPOSITORY:$BASE_IMAGE_TAG as server WORKDIR /app ARG FLWR_VERSION