From efdb900671d84cc189af489bea3ac04006fa15d7 Mon Sep 17 00:00:00 2001 From: Robert Steiner Date: Thu, 19 Sep 2024 11:09:38 +0200 Subject: [PATCH] docs(framework) Add quickstart examples Docker compose guide (#4189) Signed-off-by: Robert Steiner Co-authored-by: Javier --- doc/source/docker/index.rst | 1 + ...run-quickstart-examples-docker-compose.rst | 122 ++++++++++++++++++ .../tutorial-quickstart-docker-compose.rst | 5 + 3 files changed, 128 insertions(+) create mode 100644 doc/source/docker/run-quickstart-examples-docker-compose.rst diff --git a/doc/source/docker/index.rst b/doc/source/docker/index.rst index ac6124b4c138..968f01581b34 100644 --- a/doc/source/docker/index.rst +++ b/doc/source/docker/index.rst @@ -44,3 +44,4 @@ Run Flower using Docker Compose :maxdepth: 1 tutorial-quickstart-docker-compose + run-quickstart-examples-docker-compose diff --git a/doc/source/docker/run-quickstart-examples-docker-compose.rst b/doc/source/docker/run-quickstart-examples-docker-compose.rst new file mode 100644 index 000000000000..b279fb66c45b --- /dev/null +++ b/doc/source/docker/run-quickstart-examples-docker-compose.rst @@ -0,0 +1,122 @@ +Run Flower Quickstart Examples with Docker Compose +================================================== + +Flower provides a set of `quickstart examples `_ +to help you get started with the framework. These examples are designed to demonstrate the +capabilities of Flower and by default run using the Simulation Engine. This guide demonstrates +how to run them using Flower's Deployment Engine via Docker Compose. + +.. important:: + + Some quickstart examples may have limitations or requirements that prevent them from running + on every environment. For more information, please see `Limitations`_. + +Prerequisites +------------- + +Before you start, make sure that: + +- The ``flwr`` CLI is :doc:`installed <../how-to-install-flower>` locally. +- The Docker daemon is running. +- Docker Compose is `installed `_. + +Run the Quickstart Example +-------------------------- + +#. Clone the quickstart example you like to run. For example, ``quickstart-pytorch``: + + .. code-block:: bash + + $ git clone --depth=1 https://github.com/adap/flower.git \ + && mv flower/examples/quickstart-pytorch . \ + && rm -rf flower && cd quickstart-pytorch + +#. Download the `compose.yml `_ file into the example directory: + + .. code-block:: bash + + $ curl https://raw.githubusercontent.com/adap/flower/refs/heads/main/src/docker/complete/compose.yml \ + -o compose.yml + +#. Build and start the services using the following command: + + .. code-block:: bash + + $ docker compose up --build -d + +#. Append the following lines to the end of the ``pyproject.toml`` file and save it: + + .. code-block:: toml + :caption: pyproject.toml + + [tool.flwr.federations.local-deployment] + address = "127.0.0.1:9093" + insecure = true + + .. note:: + + You can customize the string that follows ``tool.flwr.federations.`` to fit your needs. + However, please note that the string cannot contain a dot (``.``). + + In this example, ``local-deployment`` has been used. Just remember to replace + ``local-deployment`` with your chosen name in both the ``tool.flwr.federations.`` string + and the corresponding ``flwr run .`` command. + +#. Run the example: + + .. code-block:: bash + + $ flwr run . local-deployment + +#. Follow the logs of the SuperExec service: + + .. code-block:: bash + + $ docker compose logs superexec -f + +That is all it takes! You can monitor the progress of the run through the logs of the SuperExec. + +Run a Different Quickstart Example +---------------------------------- + +To run a different quickstart example, such as ``quickstart-tensorflow``, first, shut down the Docker +Compose services of the current example: + +.. code-block:: bash + + $ docker compose down + +After that, you can repeat the steps above. + +Limitations +----------- + +.. list-table:: + :header-rows: 1 + + * - Quickstart Example + - Limitations + * - quickstart-fastai + - None + * - examples/quickstart-huggingface + - For CPU-only environments, it requires at least 32GB of memory. + * - quickstart-jax + - The example has not yet been updated to work with the latest ``flwr`` version. + * - quickstart-mlcube + - The example has not yet been updated to work with the latest ``flwr`` version. + * - quickstart-mlx + - `Requires to run on macOS with Apple Silicon `_. + * - quickstart-monai + - None + * - quickstart-pandas + - The example has not yet been updated to work with the latest ``flwr`` version. + * - quickstart-pytorch-lightning + - Requires an older pip version that is not supported by the Flower Docker images. + * - quickstart-pytorch + - None + * - quickstart-sklearn-tabular + - None + * - quickstart-tabnet + - The example has not yet been updated to work with the latest ``flwr`` version. + * - quickstart-tensorflow + - Only runs on AMD64. diff --git a/doc/source/docker/tutorial-quickstart-docker-compose.rst b/doc/source/docker/tutorial-quickstart-docker-compose.rst index 36d9bd58e29e..7aeae1e2fb6b 100644 --- a/doc/source/docker/tutorial-quickstart-docker-compose.rst +++ b/doc/source/docker/tutorial-quickstart-docker-compose.rst @@ -396,3 +396,8 @@ Remove all services and volumes: $ docker compose down -v $ docker compose -f certs.yml down -v + +Where to Go Next +---------------- + +* :doc:`run-quickstart-examples-docker-compose`