hello-world

Minimal example clan service that greets the world

Experimental

This service is for demonstration purpose only and may change in the future.

The Hello-World Clan Service is a minimal example showing how to build and register your own service.

It serves as a reference implementation and is used in clan-core CI tests to ensure compatibility.

What it demonstrates🔗

• How to define a basic Clan-compatible service.
• How to structure your service for discovery and configuration.
• How Clan services interact with NixOS.

Testing🔗

This service demonstrates two levels of testing to ensure quality and stability across releases:

1. Unit & Integration Testing — via nix-unit
2. End-to-End Testing — via NixOS VM tests, which we extended to support container virtualization for better performance.

We highly advocate following the Practical Testing Pyramid:

• Write unit tests for core logic and invariants.
• Add one or two end-to-end (E2E) tests to confirm your service starts and behaves correctly in a real NixOS environment.

NixOS is untyped and frequently changes; tests are the safest way to ensure long-term stability of services.

               / \
              /   \
             / E2E \
            /-------\
           /         \
          /Integration\
         /-------------\
        /               \
       /    Unit Tests   \
       -------------------

nix-unit🔗

We highly advocate the usage of

nix-unit

Example in: tests/eval-tests.nix

If you use flake-parts you can use the native integration

If nix-unit succeeds, your NixOS evaluation should be mostly correct.

Tip

• Ensure most used 'settings' and variants are tested.
• Think about some important edge-cases your system should handle.

NixOS VM / Container Test🔗

Early Vars & clanTest

The testing system around vars is experimental

clanTest is still experimental and enables container virtualization by default. This is still early and might have some limitations.

Some minimal boilerplate is needed to use clanTest

nixosLib = import (inputs.nixpkgs + "/nixos/lib") { }
nixosLib.runTest (
    { ... }:
    {
        imports = [
            self.modules.nixosTest.clanTest
            # Example in tests/vm/default.nix
            testModule
        ];
        hostPkgs = pkgs;

        # Uncomment if you don't want or cannot use containers
        # test.useContainers = false;
    }
)

---

Roles🔗

The hello-world service has the following roles:

• evening
• morning

Options for the evening role🔗

greeting🔗

The greeting to use

Type: string

Default:

"Good evening"

Declared in: clanServices/hello-world/default.nix

Options for the morning role🔗

greeting🔗

The greeting to use

Type: string

Default:

"Good morning"

Declared in: clanServices/hello-world/default.nix