Quickstart with Docker¶
This quickstart aims to guide you through the process of containerizing a Flower project and running it end to end using Docker on your local machine.
This tutorial does not use production-ready settings, so you can focus on understanding the basic workflow that uses the minimum configurations.
Prerequisites¶
Before you start, make sure that:
The
flwr
CLI is installed locally.The Docker daemon is running.
Step 1: Set Up¶
Create a new Flower project (PyTorch):
$ flwr new quickstart-docker --framework PyTorch --username flower 🔨 Creating Flower project quickstart-docker... 🎊 Project creation successful. Use the following command to run your project: cd quickstart-docker pip install -e . flwr run $ cd quickstart-docker
Create a new Docker bridge network called
flwr-network
:$ docker network create --driver bridge flwr-network
User-defined networks, such as
flwr-network
, enable IP resolution of container names, a feature absent in the default bridge network. This simplifies quickstart example by avoiding the need to determine host IP first.
Step 2: Start the SuperLink¶
Open your terminal and run:
$ docker run --rm \
-p 9091:9091 -p 9092:9092 -p 9093:9093 \
--network flwr-network \
--name superlink \
--detach \
flwr/superlink:1.13.1 \
--insecure \
--isolation \
process
Understand the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.-p 9091:9091 -p 9092:9092 -p 9093:9093
: Map port9091
,9092
and9093
of thecontainer to the same port of the host machine, allowing other services to access theServerAppIO API onhttp://localhost:9091
, the Fleet API onhttp://localhost:9092
andthe Exec API onhttp://localhost:9093
.--network flwr-network
: Make the container join the network namedflwr-network
.--name superlink
: Assign the namesuperlink
to the container.--detach
: Run the container in the background, freeing up the terminal.flwr/superlink:1.13.1
: The name of the image to be run and the specifictag of the image. The tag1.13.1
represents a specific version of the image.--insecure
: This flag tells the container to operate in an insecure mode, allowingunencrypted communication.--isolation process
: Tells the SuperLink that the ServerApp is created by separateindependent process. The SuperLink does not attempt to create it. You can learn more aboutthe different process modes here: Run ServerApp or ClientApp as a Subprocess.
Step 3: Start the SuperNodes¶
Start two SuperNode containers.
Start the first container:
$ docker run --rm \ -p 9094:9094 \ --network flwr-network \ --name supernode-1 \ --detach \ flwr/supernode:1.13.1 \ --insecure \ --superlink superlink:9092 \ --node-config "partition-id=0 num-partitions=2" \ --clientappio-api-address 0.0.0.0:9094 \ --isolation process
Understand the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.-p 9094:9094
: Map port9094
of the container to the same port ofthe host machine, allowing other services to access the SuperNode API onhttp://localhost:9094
.--network flwr-network
: Make the container join the network namedflwr-network
.--name supernode-1
: Assign the namesupernode-1
to the container.--detach
: Run the container in the background, freeing up the terminal.flwr/supernode:1.13.1
: This is the name of theimage to be run and the specific tag of the image.--insecure
: This flag tells the container to operate in an insecure mode, allowingunencrypted communication.--superlink superlink:9092
: Connect to the SuperLink’s Fleet API at the addresssuperlink:9092
.--node-config "partition-id=0 num-partitions=2"
: Set the partition ID to0
and thenumber of partitions to2
for the SuperNode configuration.--clientappio-api-address 0.0.0.0:9094
: Set the address and port number that theSuperNode is listening on to communicate with the ClientApp. Iftwo SuperNodes are started on the same machine, set two different port numbers for each SuperNode.(E.g. In the next step, we set the second SuperNode container to listen on port 9095)--isolation process
: Tells the SuperNode that the ClientApp is created by separateindependent process. The SuperNode does not attempt to create it.
Start the second container:
$ docker run --rm \ -p 9095:9095 \ --network flwr-network \ --name supernode-2 \ --detach \ flwr/supernode:1.13.1 \ --insecure \ --superlink superlink:9092 \ --node-config "partition-id=1 num-partitions=2" \ --clientappio-api-address 0.0.0.0:9095 \ --isolation process
Step 4: Start a ServerApp¶
The ServerApp Docker image comes with a pre-installed version of Flower and serves as a base for building your own ServerApp image. In order to install the FAB dependencies, you will need to create a Dockerfile that extends the ServerApp image and installs the required dependencies.
Create a ServerApp Dockerfile called
serverapp.Dockerfile
and paste the following code in:FROM flwr/serverapp:1.13.1 WORKDIR /app COPY pyproject.toml . RUN sed -i 's/.*flwr\[simulation\].*//' pyproject.toml \ && python -m pip install -U --no-cache-dir . ENTRYPOINT ["flwr-serverapp"]
Understand the Dockerfile
FROM flwr/serverapp:1.13.1
: This line specifies that the Docker imageto be built from is theflwr/serverapp
image, version1.13.1
.WORKDIR /app
: Set the working directory for the container to/app
.Any subsequent commands that reference a directory will be relative to this directory.COPY pyproject.toml .
: Copy thepyproject.toml
filefrom the current working directory into the container’s/app
directory.RUN sed -i 's/.*flwr\[simulation\].*//' pyproject.toml
: Remove theflwr
dependencyfrom thepyproject.toml
.python -m pip install -U --no-cache-dir .
: Run thepip
install command toinstall the dependencies defined in thepyproject.toml
fileThe-U
flag indicates that any existing packages should be upgraded, and--no-cache-dir
prevents pip from using the cache to speed up the installation.ENTRYPOINT ["flwr-serverapp"]
: Set the commandflwr-serverapp
to bethe default command run when the container is started.
Important
Note that flwr is already installed in the
flwr/clientapp
base image, so only other package dependencies such asflwr-datasets
,torch
, etc., need to be installed. As a result, theflwr
dependency is removed from thepyproject.toml
after it has been copied into the Docker image (see line 5).Afterward, in the directory that holds the Dockerfile, execute this Docker command to build the ServerApp image:
$ docker build -f serverapp.Dockerfile -t flwr_serverapp:0.0.1 .
Start the ServerApp container:
$ docker run --rm \ --network flwr-network \ --name serverapp \ --detach \ flwr_serverapp:0.0.1 \ --insecure \ --serverappio-api-address superlink:9091
Understand the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.--network flwr-network
: Make the container join the network namedflwr-network
.--name serverapp
: Assign the nameserverapp
to the container.--detach
: Run the container in the background, freeing up the terminal.flwr_serverapp:0.0.1
: This is the name of the image to be run and the specific tagof the image.--insecure
: This flag tells the container to operate in an insecure mode, allowingunencrypted communication. Secure connections will be added in future releases.--serverappio-api-address superlink:9091
: Connect to the SuperLink’s ServerAppIO APIat the addresssuperlink:9091
.
Step 5: Start the ClientApp¶
The procedure for building and running a ClientApp image is almost identical to the ServerApp image.
Similar to the ServerApp image, you will need to create a Dockerfile that extends the ClientApp image and installs the required FAB dependencies.
Create a ClientApp Dockerfile called
clientapp.Dockerfile
and paste the following code into it:1FROM flwr/clientapp:1.13.1 2 3WORKDIR /app 4COPY pyproject.toml . 5RUN sed -i 's/.*flwr\[simulation\].*//' pyproject.toml \ 6 && python -m pip install -U --no-cache-dir . 7 8ENTRYPOINT ["flwr-clientapp"]
Understand the Dockerfile
FROM flwr/clientapp:1.13.1
: This line specifies that the Docker imageto be built from is theflwr/clientapp
image, version1.13.1
.WORKDIR /app
: Set the working directory for the container to/app
.Any subsequent commands that reference a directory will be relative to this directory.COPY pyproject.toml .
: Copy thepyproject.toml
filefrom the current working directory into the container’s/app
directory.RUN sed -i 's/.*flwr\[simulation\].*//' pyproject.toml
: Remove theflwr
dependencyfrom thepyproject.toml
.python -m pip install -U --no-cache-dir .
: Run thepip
install command toinstall the dependencies defined in thepyproject.toml
fileThe-U
flag indicates that any existing packages should be upgraded, and--no-cache-dir
prevents pip from using the cache to speed up the installation.ENTRYPOINT ["flwr-clientapp"]
: Set the commandflwr-clientapp
to bethe default command run when the container is started.
Next, build the ClientApp Docker image by running the following command in the directory where the Dockerfile is located:
$ docker build -f clientapp.Dockerfile -t flwr_clientapp:0.0.1 .
Note
The image name was set as
flwr_clientapp
with the tag0.0.1
. Remember that these values are merely examples, and you can customize them according to your requirements.Start the first ClientApp container:
$ docker run --rm \ --network flwr-network \ --detach \ flwr_clientapp:0.0.1 \ --insecure \ --clientappio-api-address supernode-1:9094
Understand the command
docker run
: This tells Docker to run a container from an image.--rm
: Remove the container once it is stopped or the command exits.--network flwr-network
: Make the container join the network namedflwr-network
.--detach
: Run the container in the background, freeing up the terminal.--insecure
: This flag tells the container to operate in an insecure mode, allowingunencrypted communication. Secure connections will be added in future releases.flwr_clientapp:0.0.1
: This is the name of the image to be run and the specific tagof the image.--clientappio-api-address supernode-1:9094
: Connect to the SuperNode’s ClientAppIOAPI at the addresssupernode-1:9094
.
Start the second ClientApp container:
$ docker run --rm \ --network flwr-network \ --detach \ flwr_clientapp:0.0.1 \ --insecure \ --clientappio-api-address supernode-2:9095
Step 6: Run the Quickstart Project¶
Add the following lines to the
pyproject.toml
:[tool.flwr.federations.local-deployment] address = "127.0.0.1:9093" insecure = true
Run the
quickstart-docker
project and follow the ServerApp logs to track the execution of the run:$ flwr run . local-deployment --stream
Step 7: Update the Application¶
Change the application code. For example, change the
seed
inquickstart_docker/task.py
to43
and save it:# ... partition_train_test = partition.train_test_split(test_size=0.2, seed=43) # ...
Stop the current ServerApp and ClientApp containers:
Note
If you have modified the dependencies listed in your
pyproject.toml
file, it is essential to rebuild images.If you haven’t made any changes, you can skip steps 2 through 4.
$ docker stop $(docker ps -a -q --filter ancestor=flwr_clientapp:0.0.1) serverapp
Rebuild ServerApp and ClientApp images:
$ docker build -f clientapp.Dockerfile -t flwr_clientapp:0.0.1 . && \ docker build -f serverapp.Dockerfile -t flwr_serverapp:0.0.1 .
Launch one new ServerApp and two new ClientApp containers based on the newly built image:
$ docker run --rm \ --network flwr-network \ --name serverapp \ --detach \ flwr_serverapp:0.0.1 \ --insecure \ --serverappio-api-address superlink:9091 $ docker run --rm \ --network flwr-network \ --detach \ flwr_clientapp:0.0.1 \ --insecure \ --clientappio-api-address supernode-1:9094 $ docker run --rm \ --network flwr-network \ --detach \ flwr_clientapp:0.0.1 \ --insecure \ --clientappio-api-address supernode-2:9095
Run the updated project:
$ flwr run . local-deployment --stream
Step 8: Clean Up¶
Remove the containers and the bridge network:
$ docker stop $(docker ps -a -q --filter ancestor=flwr_clientapp:0.0.1) \
supernode-1 \
supernode-2 \
serverapp \
superlink
$ docker network rm flwr-network