Skip to content

Environment Set Up

Purpose

This section prepares your platform and tooling so you can build and run a local Federator deployment reliably. The Federator runs as a set of containerised services. Before building or starting any components, your environment must meet the required platform and tooling standards.

Stage 1 - Prepare the Environment

How to Complete This Stage

You will:

  • Confirm your operating system is supported
  • Ensure you are working from a native Linux filesystem
  • Verify Docker is installed and running
  • Confirm Java 21 is active
  • Verify required command-line tools are available

1.1 Confirm supported platform

Supported operating systems

  • Linux
  • Windows with WSL2 only

macOS is not officially supported for this deployment pattern.

1.2 Prepare WSL2 environment (Windows Only)

If using Windows:

  • Run inside WSL2.
  • Work from the WSL Linux filesystem (for example ~/src).
  • Do not run this guide from /mnt/c.

Docker containers rely on native Linux filesystem semantics which are not reliably provided by the Windows-mounted filesystem under WSL2. Running from /mnt/c can cause:

  • Permission inconsistencies
  • Volume mount failures
  • File watcher instability
  • Significant performance degradation
  • Intermittent container startup issues

Always work inside your Linux home directory:

mkdir -p ~/src
cd ~/src

All clone, build, and Docker operations should occur within this directory.

Required tools

The following tools must be installed and available in your shell.

Verify Docker Installation

Install either:

  • Docker Desktop (with WSL2 integration enabled), or
  • Docker Engine + Docker Compose (Linux)

Verify Docker installation:

docker version
docker compose version

Both commands must complete without error. Test container execution:

docker run --rm hello-world
Expected behaviour
  • Docker pulls and runs the container successfully
  • Docker must be running before proceeding.

Verify Java 21

Federator builds require Java 21. Verify your Java version:

java -version

Output must show version 21. If not, switch to Java 21 before continuing.

Example (Ubuntu/Debian)
sudo update-alternatives --config java
Example (SDKMAN)
sdk use java 21.0.0-tem

Do not proceed to the build stage unless Java 21 is active.

Verify required CLI tools

Verify Git is installed:

git --version
curl

Verify curl is installed:

curl --version

1.6 Understand deployment assumptions

The local deployment assumes:

  • Kafka is provided via Docker Compose
  • Redis is provided via Docker Compose
  • A Management-Node is included
  • An Identity Provider is preconfigured
  • Certificates and trust relationships are predefined
  • This guide focuses on federation behaviour, not IA Node internals

You are not required to manually install Kafka or Redis outside Docker for this guide.

1.7 Check networking considerations

Federator topologies may start multiple services, including:

  • Producer-side Kafka broker
  • Consumer-side Kafka broker
  • Redis
  • Federator Producers
  • Federator Consumers
  • Management-Node
  • Identity Provider

If you are already running local Kafka or Redis services, you may encounter port conflicts.

To inspect open TCP ports:

ss -lnt

If conflicts exist, stop conflicting services before continuing.

Checkpoint

Before continuing, confirm:

  • Running on Linux or inside WSL2
  • Working from the Linux filesystem (not /mnt/c)
  • Docker and Docker Compose execute successfully
  • java -version reports Java 21
  • Git and curl are available
  • Docker can run containers (hello-world test succeeds)

You are now ready to configure identity and trust relationships for the Federator deployment.

Next step

Identity Set Up