Skip to main content

Docker Client Template

BranchKey provides a production-ready Docker client template for building containerised federated learning leaf nodes. This template serves as both a validation tool and a development foundation for custom clients.

Purpose​

The Docker client template has two primary uses:

  1. Connectivity Validation - Test and verify your BranchKey platform deployment is operational
  2. Client Development Base - Foundation for building production federated learning Docker containers

What It Does​

Out of the box, the template validates the complete BranchKey federated learning workflow:

  • Connect - Verify client authentication with the BranchKey API
  • Upload - Confirm clients can upload model weights to the platform
  • Aggregate - Validate the platform triggers aggregation correctly
  • Download - Test clients can retrieve aggregated weights
  • Verify - Ensure downloaded files can be opened and validated

Key Features​

  • Python 3.12 with latest BranchKey client library
  • Docker Compose for multi-leaf testing scenarios
  • YAML Configuration for easy deployment customisation
  • Production-Ready containerisation with structured logging
  • Extension Points - Clear patterns for adding your ML models

Target Audience​

  • ML Engineers building federated learning clients
  • DevOps Teams deploying BranchKey platform installations
  • System Administrators validating new deployments
  • Developers creating production leaf node containers

Use Cases​

  • Build custom federated learning clients using Docker
  • Validate BranchKey platform connectivity and deployment
  • Test multi-leaf federation workflows
  • Debug client integration and API authentication
  • Deploy containerised leaf nodes to edge devices or cloud

Getting Started​

The Docker client template is available as an open-source repository:

Repository: branchkey/demo-applications/dockerised-implementation

For detailed quick start instructions, configuration options, and integration patterns, see the repository README.

Setup for Invited Users​

If you've been invited to join an existing tree with a pre-existing branch, follow these steps to create your leaf and connect to the federation:

Step 1: Create Your Leaf​

  1. Log in to the BranchKey platform at https://app.branchkey.com
  2. Navigate to your tree (you should have access if you were invited)
  3. Create a new leaf entity for your client node
  4. The platform will generate credentials and display them in a modal
Important

The credential modal shows a message: "Save this information now - the token will only be shown once!" Make sure to copy these credentials immediately.

Step 2: Save Your Credentials​

The platform provides credentials in JSON format:

{
  "id": "xxxxxxxx-7332-4e0d-8d9f-6d19385ce6d2",
  "type": "leaf",
  "name": "your-leaf-name",
  "owner_id": "xxxxxxxx-5ce7-48c4-9506-b6604b9da8dd",
  "parent_id": "xxxxxxxx-d6ef-407c-b985-b1ca8d028787",
  "tree_id": "xxxxxxxx-077b-4f71-8b53-d739e4d416f7",
  "branch_id": "xxxxxxxx-d6ef-407c-b985-b1ca8d028787",
  "created_at": "2026-01-01T01:01:01.243327033Z",
  "updated_at": "2026-01-01T01:01:01.243327033Z",
  "session_token": "xxxxxxxx-9c86-40ed-adca-3f1954a4f983"
}

Save these credentials:

# Create the secrets directory
mkdir -p secret

# Save your credentials to secret/leaf-1.json
# (You can use any name: leaf-2.json, my-client.json, etc.)
Security

The secret/ directory is gitignored to protect your credentials. Never commit credential files to version control.

Step 3: Configure and Run​

Now you can proceed with the Quick Start below, using your saved credentials from secret/leaf-1.json.

Quick Start Summary​

# 1. Create configuration
cp application.yaml.example application.yaml
# Edit application.yaml with your API_HOST

# 2. Save leaf credentials to secret/leaf-1.json

# 3. Run from registry (no build required)
docker run --rm \
  -v $(pwd)/application.yaml:/app/application.yaml:ro \
  -v $(pwd)/secret/leaf-1.json:/app/credentials.json:ro \
  registry.gitlab.com/branchkey/demo-applications/dockerised-implementation:latest

Next Steps​

  • Review the repository README for detailed documentation
  • See models/README.md in the repository for guidance on integrating your ML models
  • Use Docker Compose for multi-leaf federation testing
  • Extend the template with your machine learning frameworks (PyTorch, TensorFlow, etc.)