Developer guide
Pseudo-distributed sandbox
Note
These instructions are for users wanting to set up a bare-minimum local deployment of FEDn (without FEDn Studio). We here assume practical knowledge of Docker and docker-compose. We recommend all new users of FEDn to start by taking the Getting Started tutorial: Getting started with FEDn
During development on FEDn, and when working on own extentions including aggregators and helpers, it is useful to have a local development setup of the core FEDn server-side services (controller, combiner, database, object store). We provide Dockerfiles and docker-compose template for an all-in-one local sandbox:
This starts up local services for MongoDB, Minio, the API Server (Controller), one Combiner. You can verify the deployment on localhost using these urls:
API Server: http://localhost:8092/get_controller_status
Minio: http://localhost:9000
Mongo Express: http://localhost:8081
To run a client in this setup, you can use the CLI to connect to the API Server.
pip install -e .
cd examples/mnist-pytorch
fedn run client --api-url http://localhost:8092 --local-package
The –local-package flag is used to indicate that the package is available locally in the current directory. This will enable you to modify the machine learning scripts in the client folder while the client is running. In otrher words, you don’t need to rebuild and upload the compute package every time you make a change. Obs that this feature is also available in FEDn Studio.
You can also connect directly to the Combiner (gRPC) without using the API Server (REST-API):
fedn run client --combiner=localhost --combiner-port=12080 --local-package
Observe that you need to create an initial model seed.npz in the current directory before starting any new session:
fedn run build --path client
Please observe that this local sandbox deployment does not include any of the security and authentication features available in a Studio Project, so we will not require authentication of clients (insecure mode) when using the APIClient:
from fedn import APIClient
client = APIClient(host="localhost", port=8092)
client.set_active_model("seed.npz")
client.start_session(rounds=10, timeout=60)
Access message logs and validation data from MongoDB
You can access and download event logs and validation data via the API, and you can also as a developer obtain the MongoDB backend data using pymongo or via the MongoExpress interface:
Username and password are found in ‘docker-compose.yaml’.
Access global models
You can obtain global model updates from the ‘fedn-models’ bucket in Minio:
Username and password are found in ‘docker-compose.yaml’.
Reset the FEDn deployment
To purge all data from a deployment incuding all session and round data, access the MongoExpress UI interface and
delete the entire fedn-network collection. Then restart all services.
Clean up
You can clean up by running
docker compose down -v
Connecting clients using Docker:
If you like to run the client in docker as well we have added an extra docker-compose file in the examples folders for this purpose. This will allow you to run the client in a separate container and connect to the API server using the service name api-server:
docker compose \
-f ../../docker-compose.yaml \
-f docker-compose.override.yaml \
up
Distributed deployment on a local network
You can use different hosts for the various FEDn services. These instructions shows how to set up FEDn on a local network using a single workstation or laptop as the host for the servier-side components, and other hosts or devices as clients.
Note
For a secure and production-grade deployment solution over public networks, explore the FEDn Studio service at fedn.scaleoutsystems.com.
Alternatively follow this tutorial substituting the hosts local IP with your public IP, open the neccesary ports (see which ports are used in docker-compose.yaml), and ensure you have taken additional neccesary security precautions.
Prerequisites - One host workstation and atleast one client device - Python 3.9, 3.10, 3.11 or 3.12 - Docker - Docker Compose
Launch a distributed FEDn Network
Start by noting your host’s local IP address, used within your network. Discover it by running ifconfig on UNIX or ipconfig on Windows, typically listed under inet for Unix and IPv4 for Windows.
Continue by following the standard procedure to initiate a FEDn network, for example using the provided docker-compose template. Once the network is active, upload your compute package and seed (for comprehensive details, see the quickstart tutorials).
Note
This guide covers general local networks where server and client may be on different hosts but able to communicate on their private IPs. A common scenario is also to run fedn and the clients on localhost on a single machine. In that case, you can replace <host local ip> by “127.0.0.1” below.
Configuring and Attaching Clients
On your client device, continue with initializing your client. To connect to the host machine we need to ensure we are routing the correct DNS to our hosts local IP address. We can do this using the standard FEDn client.yaml:
network_id: fedn-network
discover_host: api-server
discover_port: 8092
We can then run a client using docker by adding the hostname:ip mapping in the docker run command:
docker run \
-v $PWD/client.yaml:<client.yaml file location> \
<potentiel data pointers>
—add-host=api-server:<host local ip> \
—add-host=combiner:<host local ip> \
<image name> client start -in client.yaml --name client1
Alternatively updating the /etc/hosts file, appending the following lines for running naitively:
<host local ip> api-server
<host local ip> combiner