-
Notifications
You must be signed in to change notification settings - Fork 861
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs(docker) Add ServerApps docs #3439
Changes from 3 commits
7a48176
eb6b464
f1d1351
ffb27c2
6370fbc
5ebbbc9
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,7 +2,7 @@ Run Flower using Docker | |
======================= | ||
|
||
The simplest way to get started with Flower is by using the pre-made Docker images, which you can | ||
find on `Docker Hub <https://hub.docker.com/u/flwr>`_. | ||
find on `Docker Hub <https://hub.docker.com/u/flwr>`__. | ||
|
||
Before you start, make sure that the Docker daemon is running: | ||
|
||
|
@@ -21,6 +21,12 @@ was not found, you will need to install Docker first. You can find installation | |
you can follow the `Post-installation steps <https://docs.docker.com/engine/install/linux-postinstall/>`_ | ||
on the official Docker website. | ||
|
||
.. important:: | ||
|
||
To ensure optimal performance and compatibility, the SuperLink, SuperNode and ServerApp image | ||
must have the same version when running together. This guarantees seamless integration and | ||
avoids potential conflicts or issues that may arise from using different versions. | ||
|
||
Flower SuperLink | ||
---------------- | ||
|
||
|
@@ -52,7 +58,7 @@ to the Flower SuperLink. Here, we are passing the flag ``--insecure``. | |
|
||
The ``--insecure`` flag enables insecure communication (using HTTP, not HTTPS) and should only be | ||
used for testing purposes. We strongly recommend enabling | ||
`SSL <https://flower.ai/docs/framework/how-to-run-flower-using-docker.html#enabling-ssl-for-secure-connections>`_ | ||
`SSL <https://flower.ai/docs/framework/how-to-run-flower-using-docker.html#enabling-ssl-for-secure-connections>`__ | ||
when deploying to a production environment. | ||
|
||
You can use ``--help`` to view all available flags that the SuperLink supports: | ||
|
@@ -66,14 +72,14 @@ Mounting a volume to store the state on the host system | |
|
||
If you want to persist the state of the SuperLink on your host system, all you need to do is specify | ||
a path where you want to save the file on your host system and a name for the database file. In the | ||
example below, we tell Docker via the flag ``-v`` to mount the user's home directory | ||
example below, we tell Docker via the flag ``--volume`` to mount the user's home directory | ||
(``~/`` on your host) into the ``/app/`` directory of the container. Furthermore, we use the | ||
flag ``--database`` to specify the name of the database file. | ||
|
||
.. code-block:: bash | ||
|
||
$ docker run --rm \ | ||
-p 9091:9091 -p 9092:9092 -v ~/:/app/ flwr/superlink:1.8.0 \ | ||
-p 9091:9091 -p 9092:9092 --volume ~/:/app/ flwr/superlink:1.8.0 \ | ||
--insecure \ | ||
--database state.db | ||
|
||
|
@@ -89,18 +95,18 @@ PEM-encoded certificate chain. | |
|
||
.. note:: | ||
For testing purposes, you can generate your own self-signed certificates. The | ||
`Enable SSL connections <https://flower.ai/docs/framework/how-to-enable-ssl-connections.html#certificates>`_ | ||
`Enable SSL connections <https://flower.ai/docs/framework/how-to-enable-ssl-connections.html#certificates>`__ | ||
page contains a section that will guide you through the process. | ||
|
||
Assuming all files we need are in the local ``certificates`` directory, we can use the flag | ||
``-v`` to mount the local directory into the ``/app/`` directory of the container. This allows the | ||
SuperLink to access the files within the container. Finally, we pass the names of the certificates | ||
to the SuperLink with the ``--certificates`` flag. | ||
``--volume`` to mount the local directory into the ``/app/`` directory of the container. This allows | ||
the SuperLink to access the files within the container. Finally, we pass the names of the | ||
certificates to the SuperLink with the ``--certificates`` flag. | ||
|
||
.. code-block:: bash | ||
|
||
$ docker run --rm \ | ||
-p 9091:9091 -p 9092:9092 -v ./certificates/:/app/ flwr/superlink:1.8.0 \ | ||
-p 9091:9091 -p 9092:9092 --volume ./certificates/:/app/ flwr/superlink:1.8.0 \ | ||
--certificates ca.crt server.pem server.key | ||
|
||
Flower SuperNode | ||
|
@@ -112,25 +118,28 @@ building your own SuperNode image. | |
.. important:: | ||
|
||
The SuperNode Docker image currently works only with the 1.9.0-nightly release. A stable version | ||
will be available when Flower 1.9.0 (stable) gets released (ETA: May). A SuperNode nightly image must be paired with the corresponding | ||
SuperLink nightly image released on the same day. To ensure the versions are in sync, using the concrete | ||
tag, e.g., ``1.9.0.dev20240501`` instead of ``nightly`` is recommended. | ||
will be available when Flower 1.9.0 (stable) gets released (ETA: May). A SuperNode nightly image | ||
must be paired with the corresponding SuperLink and ServerApp nightly images released on the same | ||
day. To ensure the versions are in sync, using the concrete tag, e.g., ``1.9.0.dev20240501`` | ||
instead of ``nightly`` is recommended. | ||
|
||
We will use the ``app-pytorch`` example, which you can find in | ||
We will use the ``quickstart-pytorch`` example, which you can find in | ||
the Flower repository, to illustrate how you can dockerize your client-app. | ||
|
||
.. _SuperNode Prerequisites: | ||
|
||
Prerequisites | ||
~~~~~~~~~~~~~ | ||
|
||
Before we can start, we need to meet a few prerequisites in our local development environment. | ||
You can skip the first part if you want to run your client-app instead of the ``app-pytorch`` | ||
You can skip the first part if you want to run your client-app instead of the ``quickstart-pytorch`` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Rename client-app > ClientApp for consistency. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Good catch! |
||
example. | ||
|
||
#. Clone the flower repository. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. flower > Flower |
||
|
||
.. code-block:: bash | ||
|
||
$ git clone https://github.com/adap/flower.git && cd flower/examples/app-pytorch | ||
$ git clone https://github.com/adap/flower.git && cd flower/examples/quickstart-pytorch | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. - git clone https://github.com/adap/flower.git && cd flower/examples/quickstart-pytorch
+ git clone --depth=1 https://github.com/adap/flower.git && cd flower/examples/quickstart-pytorch |
||
|
||
#. Verify the Docker daemon is running. | ||
|
||
|
@@ -148,44 +157,59 @@ Let's assume the following project layout: | |
|
||
$ tree . | ||
. | ||
├── client.py # client-app code | ||
├── task.py # client-app code | ||
├── requirements.txt # client-app dependencies | ||
├── client.py # ClientApp code | ||
└── <other files> | ||
|
||
First, we need to create a Dockerfile in the directory where the ``ClientApp`` code is located. | ||
If you use the ``app-pytorch`` example, create a new file called ``Dockerfile`` in | ||
``examples/app-pytorch``. | ||
First, we need to create a ``requirements.txt`` file in the directory where the ``ClientApp`` code | ||
is located. In the file, we list all the dependencies that the ClientApp requires. | ||
|
||
.. code-block:: | ||
|
||
The ``Dockerfile`` contains the instructions that assemble the SuperNode image. | ||
flwr-datasets[vision]>=0.0.2,<1.0.0 | ||
torch==2.1.1 | ||
torchvision==0.16.1 | ||
tqdm==4.66.3 | ||
|
||
.. important:: | ||
|
||
Note that `flwr <https://pypi.org/project/flwr/>`__ is already installed in the ``flwr/supernode`` | ||
base image, so you only need to include other package dependencies in your requirements.txt, | ||
such as torch, tensorflow, etc. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ... in your |
||
|
||
Next, we create a Dockerfile. If you use the ``quickstart-pytorch`` example, create a new | ||
file called ``Dockerfile.supernode`` in ``examples/quickstart-pytorch``. | ||
|
||
The ``Dockerfile.supernode`` contains the instructions that assemble the SuperNode image. | ||
|
||
.. code-block:: dockerfile | ||
|
||
FROM flwr/supernode:nightly | ||
|
||
WORKDIR /app | ||
|
||
COPY requirements.txt . | ||
RUN python -m pip install -U --no-cache-dir -r requirements.txt && pyenv rehash | ||
|
||
COPY client.py task.py ./ | ||
ENTRYPOINT ["flower-client-app"] | ||
COPY client.py ./ | ||
ENTRYPOINT ["flower-client-app", "client:app"] | ||
|
||
In the first two lines, we instruct Docker to use the SuperNode image tagged ``nightly`` as a base | ||
image and set our working directory to ``/app``. The following instructions will now be | ||
executed in the ``/app`` directory. Next, we install the ``ClientApp`` dependencies by copying the | ||
executed in the ``/app`` directory. Next, we install the ClientApp dependencies by copying the | ||
``requirements.txt`` file into the image and run ``pip install``. In the last two lines, | ||
we copy the ``ClientApp`` code (``client.py`` and ``task.py``) into the image and set the entry | ||
point to ``flower-client-app``. | ||
we copy the ClientApp code into the image and set the entry point to ``flower-client-app`` with | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. we copy the |
||
the argument ``client:app``. The argument is the object reference of the ClientApp | ||
(``<module>:<attribute>``) that will be run inside the ClientApp. | ||
|
||
Building the SuperNode Docker image | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Next, we build the SuperNode Docker image by running the following command in the directory where | ||
Dockerfile and client-app code are located. | ||
Dockerfile and ClientApp code are located. | ||
|
||
.. code-block:: bash | ||
|
||
$ docker build -t flwr_supernode:0.0.1 . | ||
$ docker build -f Dockerfile.supernode -t flwr_supernode:0.0.1 . | ||
|
||
We gave the image the name ``flwr_supernode``, and the tag ``0.0.1``. Remember that the here chosen | ||
values only serve as an example. You can change them to your needs. | ||
|
@@ -206,45 +230,162 @@ Let's break down each part of this command: | |
|
||
* ``docker run``: This is the command to run a new Docker container. | ||
* ``--rm``: This option specifies that the container should be automatically removed when it stops. | ||
* | ``flwr_supernode:0.0.1``: The name the tag of the Docker image to use. | ||
* | ``client:app``: The object reference of the ``ClientApp`` (``<module>:<attribute>``). | ||
| It points to the ``ClientApp`` that will be run inside the SuperNode container. | ||
* ``flwr_supernode:0.0.1``: The name the tag of the Docker image to use. | ||
* ``--insecure``: This option enables insecure communication. | ||
|
||
.. attention:: | ||
|
||
The ``--insecure`` flag enables insecure communication (using HTTP, not HTTPS) and should only be | ||
used for testing purposes. We strongly recommend enabling | ||
`SSL <https://flower.ai/docs/framework/how-to-run-flower-using-docker.html#enabling-ssl-for-secure-connections>`_ | ||
`SSL <https://flower.ai/docs/framework/how-to-run-flower-using-docker.html#enabling-ssl-for-secure-connections>`__ | ||
when deploying to a production environment. | ||
|
||
* | ``--server 192.168.1.100:9092``: This option specifies the address of the SuperLinks Fleet | ||
| API to connect to. Remember to update it with your SuperLink IP. | ||
|
||
.. note:: | ||
|
||
Any argument that comes after the tag is passed to the Flower SuperNode binary. | ||
To see all available flags that the SuperNode supports, run: | ||
To test running Flower locally, you can create a | ||
`bridge network <https://docs.docker.com/network/network-tutorial-standalone/#use-user-defined-bridge-networks>`__, | ||
use the ``--network`` argument and pass the name of the Docker network to run your SuperNodes. | ||
|
||
.. code-block:: bash | ||
Any argument that comes after the tag is passed to the Flower SuperNode binary. | ||
To see all available flags that the SuperNode supports, run: | ||
|
||
$ docker run --rm flwr/supernode:nightly --help | ||
.. code-block:: bash | ||
|
||
$ docker run --rm flwr/supernode:nightly --help | ||
|
||
Enabling SSL for secure connections | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
To enable SSL, we will need to mount a PEM-encoded root certificate into your SuperNode container. | ||
|
||
Assuming the certificate already exists locally, we can use the flag ``-v`` to mount the local | ||
Assuming the certificate already exists locally, we can use the flag ``--volume`` to mount the local | ||
certificate into the container's ``/app/`` directory. This allows the SuperNode to access the | ||
certificate within the container. Use the ``--certificates`` flag when starting the container. | ||
|
||
.. code-block:: bash | ||
|
||
$ docker run --rm -v ./ca.crt:/app/ca.crt flwr_supernode:0.0.1 client:app \ | ||
$ docker run --rm --volume ./ca.crt:/app/ca.crt flwr_supernode:0.0.1 client:app \ | ||
--server 192.168.1.100:9092 \ | ||
--certificates ca.crt | ||
|
||
Flower ServerApp | ||
---------------- | ||
|
||
The procedure for building and running a ServerApp image is almost identical to the SuperNode image. | ||
|
||
Similar to the SuperNode image, the ServerApp Docker image comes with a pre-installed version of | ||
Flower and serves as a base for building your own ServerApp image. | ||
|
||
We will use the same ``quickstart-pytorch`` example as we do in the Flower SuperNode section. | ||
If you have not already done so, please follow the `SuperNode Prerequisites`_ before proceeding. | ||
|
||
|
||
Creating a ServerApp Dockerfile | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Let's assume the following project layout: | ||
|
||
.. code-block:: bash | ||
|
||
$ tree . | ||
. | ||
├── server.py # ServerApp code | ||
└── <other files> | ||
|
||
First, we need to create a Dockerfile in the directory where the ``ServerApp`` code is located. | ||
If you use the ``quickstart-pytorch`` example, create a new file called ``Dockerfile.serverapp`` in | ||
``examples/quickstart-pytorch``. | ||
|
||
The ``Dockerfile.serverapp`` contains the instructions that assemble the ServerApp image. | ||
|
||
.. code-block:: dockerfile | ||
|
||
FROM flwr/serverapp:1.8.0 | ||
chongshenng marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
WORKDIR /app | ||
|
||
COPY server.py ./ | ||
ENTRYPOINT ["flower-server-app", "server:app"] | ||
chongshenng marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
In the first two lines, we instruct Docker to use the ServerApp image tagged ``1.8.0`` as a base | ||
chongshenng marked this conversation as resolved.
Show resolved
Hide resolved
|
||
image and set our working directory to ``/app``. The following instructions will now be | ||
executed in the ``/app`` directory. In the last two lines, we copy the ServerApp code into the | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ..., we copy the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should we call it There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You're right @Robert-Steiner! Let's stick to
|
||
image and set the entry point to ``flower-server-app`` with the argument ``server:app``. | ||
The argument is the object reference of the ServerApp (``<module>:<attribute>``) that will be run | ||
inside the ServerApp container. | ||
|
||
Building the ServerApp Docker image | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Next, we build the ServerApp Docker image by running the following command in the directory where | ||
Dockerfile and ServerApp code are located. | ||
|
||
.. code-block:: bash | ||
|
||
$ docker build -f Dockerfile.serverapp -t flwr_serverapp:0.0.1 . | ||
|
||
We gave the image the name ``flwr_serverapp``, and the tag ``0.0.1``. Remember that the here chosen | ||
values only serve as an example. You can change them to your needs. | ||
|
||
|
||
Running the ServerApp Docker image | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Now that we have built the ServerApp image, we can finally run it. | ||
|
||
.. code-block:: bash | ||
|
||
$ docker run --rm flwr_serverapp:0.0.1 \ | ||
--insecure \ | ||
--server 192.168.1.100:9091 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should we adopt the Docker network approach here (and also for docker run \
--network flwr-net \
--rm flwr/serverapp:1.8.0 \
--insecure --server flwr-superlink:9091 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm not sure since this only works if all containers are running on the same machine. We could add a note wdyt? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That's true. Maybe something like the following?
Or did you have another comment in mind? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I took your comment and added a link to the Docker documentation on creating a bridge network. |
||
|
||
Let's break down each part of this command: | ||
|
||
* ``docker run``: This is the command to run a new Docker container. | ||
* ``--rm``: This option specifies that the container should be automatically removed when it stops. | ||
* ``flwr_serverapp:0.0.1``: The name the tag of the Docker image to use. | ||
* ``--insecure``: This option enables insecure communication. | ||
|
||
.. attention:: | ||
|
||
The ``--insecure`` flag enables insecure communication (using HTTP, not HTTPS) and should only be | ||
used for testing purposes. We strongly recommend enabling | ||
`SSL <https://flower.ai/docs/framework/how-to-run-flower-using-docker.html#enabling-ssl-for-secure-connections>`__ | ||
when deploying to a production environment. | ||
|
||
* | ``--server 192.168.1.100:9091``: This option specifies the address of the SuperLinks Driver | ||
| API to connect to. Remember to update it with your SuperLink IP. | ||
|
||
.. note:: | ||
To test running Flower locally, you can create a | ||
`bridge network <https://docs.docker.com/network/network-tutorial-standalone/#use-user-defined-bridge-networks>`__, | ||
use the ``--network`` argument and pass the name of the Docker network to run your ServerApps. | ||
|
||
Any argument that comes after the tag is passed to the Flower ServerApp binary. | ||
To see all available flags that the ServerApp supports, run: | ||
|
||
.. code-block:: bash | ||
|
||
$ docker run --rm flwr/serverapp:1.8.0 --help | ||
|
||
Enabling SSL for secure connections | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
To enable SSL, we will need to mount a PEM-encoded root certificate into your ServerApp container. | ||
|
||
Assuming the certificate already exists locally, we can use the flag ``--volume`` to mount the local | ||
certificate into the container's ``/app/`` directory. This allows the ServerApp to access the | ||
certificate within the container. Use the ``--certificates`` flag when starting the container. | ||
|
||
.. code-block:: bash | ||
|
||
$ docker run --rm --volume ./ca.crt:/app/ca.crt flwr_serverapp:0.0.1 client:app \ | ||
--server 192.168.1.100:9091 \ | ||
--certificates ca.crt | ||
|
||
Advanced Docker options | ||
----------------------- | ||
|
||
|
@@ -253,7 +394,7 @@ Using a different Flower version | |
|
||
If you want to use a different version of Flower, for example Flower nightly, you can do so by | ||
changing the tag. All available versions are on | ||
`Docker Hub <https://hub.docker.com/r/flwr/superlink/tags>`_. | ||
`Docker Hub <https://hub.docker.com/r/flwr/superlink/tags>`__. | ||
|
||
Pinning a Docker image to a specific version | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Rename client-app > ClientApp for consistency.