Skip to content

Build Components

Purpose

The section builds the Federator Java artefacts and Docker images required to run a local federation deployment. The Federator runtime is delivered as containerised services. These containers embed Java artefacts built from source. Before > any services can be started, the Java modules must be compiled and packaged, and Docker images must be built.

Stage 3 - Build Federator Components

How to complete this stage

You will:

  • Clone the Federator repository
  • Configure Maven access to GitHub Packages (first-time setup only)
  • Build all Java modules using the Maven Wrapper
  • Build Docker images using the compiled artefacts
  • Verify that build artefacts are produced successfully

Do not proceed to Run & Validate unless this stage completes successfully.

3.1 Clone the Repository

All Federator functionality (Producer, Consumer, filtering logic, gRPC interfaces, shared libraries) is built from the source repository. Ensure you are working from your Linux filesystem (for example ~/src):

cd ~/src
git clone https://github.com/National-Digital-Twin/federator.git
cd federator

Optional : Deploy a Federator client or server using Helm charts

Federator components can be deployed using Helm charts.

  • Set up your environment using the Helm Chart installation guide
  • Clone the helm-charts repository
  • Create requisite namespaces, secrets and user identities
  • Install the Federator client or server
git clone https://github.com/National-Digital-Twin/helm-charts.git

helm upgrade --install federator-client ./charts/federator --namespace org-a --values ./charts/federator/examples/values-client-example.yaml
helm upgrade --install federator-server ./charts/federator --namespace org-b --values ./charts/federator/examples/values-server-example.yaml

Checkpoint

  • The federator repository is available locally
  • You can see directories such as:
  • docker/
  • src/
  • pom.xml
  • configuration files

3.2 Configure Maven access (first-time setup only)

The build retrieves certain dependencies from the National Digital Twin GitHub Package Registry.

If Maven is not configured, you may encounter:

  • 401 Unauthorized
  • 403 Forbidden
Step 1 — Create a GitHub Personal Access Token (PAT)

Create a GitHub PAT with the following scope: - read:packages

Step 2 — Configure Maven settings.xml

Edit or create: Linux / WSL:

~/.m2/settings.xml

Windows:

%USERPROFILE%\.m2\settings.xml

Add the following configuration (replace placeholders with your GitHub details):

<settings>
  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
        </repository>
        <repository>
          <id>github</id>
          <url>https://maven.pkg.github.com/National-Digital-Twin/*</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <servers>
    <server>
      <id>github</id>
      <username>YOUR_GITHUB_USERNAME</username>
      <password>YOUR_GITHUB_TOKEN</password>
    </server>
  </servers>
</settings>

Once configured, proceed to the build step.

3.3 Build the Java artefacts

From the root of the federator repository, run:

./mvnw clean install

This command:

  • Compiles all Federator modules
  • Resolves and verifies dependencies
  • Produces server and client JAR files in the target/ directories

If the build fails, check:

  • Java version reports Java 21
  • GitHub Package access is configured correctly
  • The PAT includes read:packages

Do not continue if this step fails.

Checkpoint

  • Maven completes without errors
  • Producer and Consumer JARs are generated
  • target/ directories contain compiled artefacts

3.4 Build the Docker images

After the Maven build completes successfully, build the container images. Example (multiple-clients / multiple-server topology):

docker compose \
  --file docker/docker-compose-multiple-clients-multiple-server.yml \
  build

This step:

  • Packages the built JAR files into Docker images
  • Prepares Producer and Consumer runtime containers
  • Ensures the images match the locally built source code

Docker must be running before executing this command.

If this stage fails:

  • Confirm Docker is running
  • Confirm the Maven build completed successfully
  • Review build logs for image build errors
  • Ensure that the version number specified in federator/docker/.env is the latest version

Checkpoint

  • Docker images build successfully
  • No image build errors are reported
  • Images are available locally (verify with: docker images)

Operational notes

  • Run all commands from the repository root.
  • Use the Maven Wrapper (mvnw).
  • Docker images must correspond to locally built artefacts.
  • Do not run docker compose up until images build successfully.

Build completion checklist

Before proceeding:

  • Repository cloned successfully
  • Maven access configured (if required)
  • ./mvnw clean install completed without errors
  • Docker images built successfully
  • No unresolved dependency errors
  • Java 21 confirmed

You are now ready to start a Federator deployment.

Next step

Proceed to: Run and Validate