### Before: Complex multi-service setup

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/migrate-inventory-services.md

This example demonstrates a complex setup with multiple services defined using the legacy `clanModules` format.

```nix
# Old format
services = {
    borgbackup.production = {
        roles.server.machines = [ "backup-server" ];
        roles.server.config = {
            directory = "/var/backup/borg";
        };
        roles.client.tags = [ "backup" ];
        roles.client.extraModules = [ "nixosModules/borgbackup.nix" ];
    };

    zerotier.company-network = {
        roles.controller.machines = [ "network-controller" ];
        roles.moon.machines = [ "moon-1" "moon-2" ];
        roles.peer.tags = [ "nixos" ];
    };

    sshd.internal = {
        roles.server.tags = [ "nixos" ];
        roles.client.tags = [ "nixos" ];
        config.certificate.searchDomains = [
            "internal.example.com"
            "vpn.example.com"
        ];
    };
};

```

--------------------------------

### Example: Flash ISO to USB Drive

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-physical.md

An example of flashing the NixOS installer ISO to a USB drive identified as '/dev/sdb'.

```bash
sudo dd if=nixos-installer-x86_64-linux.iso of=/dev/sdb bs=4M status=progress conv=fsync
```

--------------------------------

### After: Migrated complex multi-service setup

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/migrate-inventory-services.md

This example shows the migrated complex setup with multiple services using the new `clanServices` format.

```nix
# New format
instances = {
    borgbackup-production = {
        module = {
            name = "borgbackup";
            input = "clan-core";
        };
        roles.server.machines."backup-server" = { };
        roles.server.settings = {
            directory = "/var/backup/borg";
        };
        roles.client.tags = [ "backup" ];
        roles.client.extraModules = [ ../nixosModules/borgbackup.nix ];
    };

    zerotier-company-network = {
        module = {
            name = "zerotier";
            input = "clan-core";
        };
        roles.controller.machines."network-controller" = { };
        roles.moon.machines."moon-1".settings = {
            stableEndpoints = [ "10.0.0.1" "2001:db8::1" ];
        };
        roles.moon.machines."moon-2".settings = {
            stableEndpoints = [ "10.0.0.2" "2001:db8::2" ];
        };
        roles.peer.tags = [ "nixos" ];
    };

    sshd-internal = {
        module = {
            name = "sshd";
            input = "clan-core";
        };
        roles.server.tags = [ "nixos" ];
        roles.client.tags = [ "nixos" ];
        roles.client.settings = {
            certificate.searchDomains = [
                "internal.example.com"
                "vpn.example.com"
            ];
        };
    };
};

```

--------------------------------

### Full Inventory Configuration Example

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/inventory/intro-to-inventory.md

A comprehensive example demonstrating how to define machines, configure services like SSH and WiFi, set up user accounts, and manage backup tasks across different machines. This setup allows for scalable inventory management.

```nix
inventory.machines = {
  sally-laptop = {
    deploy.targetHost = "root@192.168.1.10";
    tags = [ "laptop" ];
  };
  fred-laptop = {
    deploy.targetHost = "root@192.168.1.11";
    tags = [ "laptop" ];
  };
  backup-server = {
    deploy.targetHost = "root@192.168.1.100";
    tags = [ "server" ];
  };
};

inventory.instances = {
  # SSH on everything
  sshd = {
    roles.server.tags = [ "all" ];
  };

  # WiFi on laptops
  wifi = {
    roles.default.tags = [ "laptop" ];
    roles.default.settings.networks.home = {};
  };

  # One user account per person, on their own machine
  user-sally = {
    module.name = "users";
    roles.default.machines."sally-laptop" = {};
    roles.default.settings.user = "sally";
  };
  user-fred = {
    module.name = "users";
    roles.default.machines."fred-laptop" = {};
    roles.default.settings.user = "fred";
  };

  # Backups: laptops → backup-server, every night at 2 AM
  borgbackup = {
    roles.client.tags = [ "laptop" ];
    roles.client.settings.startAt = "*-*-* 02:00:00";
    roles.server.machines."backup-server" = {};
  };
};
```

--------------------------------

### Complete Migration Example: After

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/migrate-admin-service.md

A full configuration example after migrating to 'sshd' and 'users' services.

```nix
{ 
  flake.clan.inventory.instances = {
    sshd = {
      roles.server.machines.my-server = { };
      roles.server.settings = {
        authorizedKeys = {
          "admin-key" = "ssh-ed25519 AAAA...xyz admin@workstation";
        };
        certificate.searchDomains = [ "internal.example.com" ];
      };
      roles.client.machines.my-server = { };
    };

    root-password = {
      module = {
        name = "users";
        input = "clan-core";
      };
      roles.default.machines.my-server = { };
      roles.default.settings = {
        user = "root";
        prompt = true;
      };
    };
  };
}
```

--------------------------------

### Complete Migration Example: Before

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/migrate-admin-service.md

A full configuration example before migrating from the 'admin' service.

```nix
{ 
  flake.clan.inventory.instances = {
    admin = {
      roles.default.machines.my-server = { };
      roles.default.settings = {
        allowedKeys = {
          "admin-key" = "ssh-ed25519 AAAA...xyz admin@workstation";
        };
        certificateSearchDomains = [ "internal.example.com" ];
      };
    };
  };
}
```

--------------------------------

### Clan Nix Configuration for PostgreSQL Backups

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/backup-advanced.md

This example demonstrates a complete `clan.nix` configuration for setting up PostgreSQL with Clan's backup system. It includes inventory setup, service definitions for BorgBackup and SSH, user management, and specific NixOS configurations for the PostgreSQL server, including enabling the Clan PostgreSQL module and defining pre/post backup scripts.

```nix
{ # Ensure this is unique among all clans you want to use.
  meta.name = "MY-HETZNER-CLAN";
  meta.domain = "myhetznerclan.lol";

  inventory.machines = {
    postgres-server = {
      deploy.targetHost = "root@<IP-ADDRESS>"; # REPLACE WITH POSTGRES-SERVER'S IP ADDRESS; keep "root@"
      tags = [ ];
    };
    backup-server = {
      deploy.targetHost = "root@<IP-ADDRESS>"; # REPLACE WITH BACKUP-SERVER'S IP ADDRESS; keep "root@"
      tags = [ ];
    };
  };

  # Docs: See https://clan.lol/docs/{{ version }}/services/definition
  inventory.instances = {

    borgbackup = {
      roles.client.machines."postgres-server" = { };
      roles.server.machines."backup-server" = {
        settings.address = "<IP-ADDRESS>"; # REPLACE WITH BACKUP-SERVER'S IP ADDRESS
        settings.directory = "/var/lib/borgbackup";
      };
    };

    # Docs: https://clan.lol/docs/{{ version }}/services/official/sshd
    # SSH service for secure remote access to machines.
    # Generates persistent host keys and configures authorized keys.
    sshd = {
      roles.server.tags.all = { };
      roles.server.settings.authorizedKeys = {
        # Insert the public key that you want to use for SSH access.
        # All keys will have ssh access to all machines ("tags.all" means 'all machines').
        # Alternatively set 'users.users.root.openssh.authorizedKeys.keys' in each machine
        "admin-machine-1" = "[PASTE_YOUR_KEY_HERE]";
      };
    };

    # Docs: https://clan.lol/docs/{{ version }}/services/official/users
    # Root password management for all machines.
    user-root = {
      module = {
        name = "users";
      };
      roles.default.tags.all = { };
      roles.default.settings = {
        user = "root";
        prompt = true;
      };
    };

  };

  # Additional NixOS configuration can be added here.
  # machines/server/configuration.nix will be automatically imported.
  # See: https://clan.lol/docs/{{ version }}/guides/inventory/autoincludes
  machines = {

    postgres-server =
      { config, ... }:
      {
        services.postgresql = {
          enable = true;
          ensureDatabases = [ "mydatabase" ];
        };

        clan.core.postgresql.enable = true;
        clan.core.postgresql.databases.mydatabase = { };

        clan.core.state."postgresql" = {
          folders = [ ];
          preBackupScript = ''
            systemctl stop postgresql
          '';
          postBackupScript = ''
            systemctl start postgresql
          '';
        };
      };

  };
}

```

--------------------------------

### Role-Wide Service Settings

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/services/intro-to-services-revised.md

Apply settings to all machines within a specific role. This example sets the start time for borgbackup clients.

```nix
inventory.instances = {
  borgbackup = {
    roles.client.tags = [ "laptop" ];
    roles.client.settings.startAt = "*-*-* 02:00:00";
    roles.server.machines."backup-server" = {};
  };
};
```

--------------------------------

### Install NixOS

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/disk-encryption.md

Install NixOS onto the prepared and partitioned disks.

```bash
clan machines install <mymachine> --target-host root@nixos-installer.local --phases install
```

--------------------------------

### Install Backup Server

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/backup-advanced.md

Install the backup server first to ensure its SSH host key is available for client connections. This command initiates the installation process on the backup server.

```bash
clan machines install backup-server --target-host root@<BACKUP-IP>
```

--------------------------------

### Example: service-dummy-test

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/testing.md

This example demonstrates the two-step process for running the `service-dummy-test`, first generating its variables and then executing the test.

```bash
# First, generate the test vars
nix run .#checks.x86_64-linux.service-dummy-test.update-vars

# Then run the test
nix run .#checks.x86_64-linux.service-dummy-test
```

--------------------------------

### Nix Configuration Example (Good Practice)

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/styleguide.md

A Nix configuration snippet presented following the styleguide's 'good' example principles, avoiding excessive comments.

```nix
{
  clan.networking.targetHost = "192.168.XXX.XXX";
  services.openssh.enable = true;
}
```

--------------------------------

### Full User Firewall Configuration Example

Source: https://github.com/clan/clan-core/blob/main/nixosModules/user-firewall/README.md

A comprehensive example showing how to configure exempt users and allowed network interfaces, including common VPN and localhost interfaces.

```nix
{
  networking.user-firewall = {
    # Users who are exempt from network restrictions
    exemptUsers = [
      "alice"
      "admin"
    ];

    # Network interfaces that all users can use
    # Default includes common VPN interfaces
    allowedInterfaces = [
      "lo" # localhost (required for local services)
      "tun*" # OpenVPN, OpenConnect
      "wg*" # WireGuard (wg0, wg-home, etc.)
      "tailscale*" # Tailscale
      # Add custom interfaces as needed
    ];
  };
}
```

--------------------------------

### Advanced Multi-Network Setup with Priority

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/networking/networking.md

Set up multiple networks with defined priorities, starting with direct internet, then VPN, and finally Tor as a fallback.

```nix
{ ... }:
let
  clan = clan-core.lib.clan {
    inventory.instances = {
      # Priority 1: Try direct connection first
      internet = {
        roles.default.machines.publicserver = {
          settings.host = "public.example.com";
        };
      };

      # Priority 2: VPN for internal machines
      zerotier = {
        roles.controller.machines."controller" = { };
        roles.peer.tags = [ "nixos" ];
      };

      # Priority 3: Tor as universal fallback
      tor = {
        roles.server.tags = [ "nixos" ];
      };
    };
  };
in
{
  inherit (clan.config) nixosConfigurations;
}
```

--------------------------------

### Complex Yggdrasil Setup with Multiple Services

Source: https://github.com/clan/clan-core/blob/main/clanServices/yggdrasil/README.md

This example demonstrates a sophisticated setup combining Yggdrasil with other network services like 'internet', 'mycelium', and 'tor'. It sets a custom domain 'ccc' for accessing machines and leverages Yggdrasil's ability to find the best routing path through available network transports.

```nix
inventory = {

  machines = {
    peer1 = { };
    peer2 = { };
  };

  meta.domain = "ccc";

  instances = {

    # Deploy yggrdasil on all machines
    yggdrasil = {
      roles.default.tags = [ "all" ];
    };

    internet = {
      roles.default.machines = {
        peer1.settings.host = "85.139.10.1";
        peer2.settings.host = "85.139.10.2";
      };
    };

    mycelium = {
      roles.peer.tags = [ "all" ];
    };

    tor = {

      roles.client.tags = [ "all" ];
      roles.server.tags = [ "all" ];

      roles.server.settings = {

        secretHostname = false;

        # yggdrasil ports need to be mapped
        portMapping = [
          {
            port = 6443;
            target.port = 6443;
          }
          {
            port = 6446;
            target.port = 6446;
          }
        ];
      };
    };
  };
};

```

--------------------------------

### Start Local Development Server

Source: https://github.com/clan/clan-core/blob/main/docs/README.md

Run the 'clan-site' command to start the development server. It watches for changes in 'docs/src/' and reloads the browser automatically.

```bash
clan-site
```

--------------------------------

### Install Client Machine

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/backup-advanced.md

Install the client machine, such as alice-laptop, after the backup server. This ensures the client can securely connect to the backup server using its generated SSH host key.

```bash
clan machines install alice-laptop --target-host root@<ALICE-IP>
```

--------------------------------

### Install 'cbonsai' Package on 'server'

Source: https://github.com/clan/clan-core/blob/main/clanServices/packages/README.md

Demonstrates how to install the 'cbonsai' application to a machine named 'server' using the service's configuration.

```nix
instances.packages = {
    roles.default.machines."server".settings = {
        packages = [ "cbonsai" ];
    };
};

```

--------------------------------

### Pre and Post Backup Scripts for Services

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/backup-intro.md

Execute custom scripts before and after backup operations to manage service states. This example stops and starts Nextcloud services to ensure data consistency during backup.

```nix
clan.core.state.nextcloud = {
  folders = [ "/var/lib/nextcloud" ];
  preBackupScript = ''
    export PATH=${ 
      lib.makeBinPath [
        config.systemd.package
      ]
    }

      systemctl stop phpfpm-nextcloud.service
      systemctl stop nextcloud-cron.timer
  '';

  postBackupScript = ''
    export PATH=${ 
      lib.makeBinPath [
        config.systemd.package
      ]
    }

    systemctl start phpfpm-nextcloud.service
    systemctl start nextcloud-cron.timer
  '';
};

```

--------------------------------

### Configure CA and Trust

Source: https://github.com/clan/clan-core/blob/main/clanServices/certificates/README.md

Example Nix configuration to set up a CA for a top-level domain and ensure client and server machines trust the CA. This setup is useful for internal SSL-secured service hosting.

```nix
inventory = {
  machines.ca = {};
  machines.client = {};
  machines.server = {};

  instances."certificates" = {
    module.name = "certificates";
    module.input = "self";

    roles.ca.machines.ca.settings.tlds = [ "foo" ];
    roles.default.machines.client = {};
    roles.default.machines.server = {};
  };
};

```

--------------------------------

### Configure Machine as Installer

Source: https://github.com/clan/clan-core/blob/main/clanServices/installer/README.md

This snippet shows how to configure a machine named 'jon' to be an installer image. The ISO can then be built using the provided command.

```nix
inventory.instances = {
  installer = {
    module = {
      name = "installer";
      input = "clan-core";
    };
    roles.iso.machines."jon" = { };
  };
};

```

--------------------------------

### Before: Admin Service Configuration

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/migrate-admin-service.md

Example of the 'admin' service configuration before migration.

```nix
instances = {
  admin = {
    roles.default.tags = [ "all" ];
    roles.default.settings = {
      allowedKeys = {
        "my-key" = "ssh-ed25519 AAAA...";
      };
      certificateSearchDomains = [ "mydomain.com" ];
      rsaHostKey.enable = true;
    };
  };
};
```

--------------------------------

### Install NixOS

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/quick-start.md

Builds and installs NixOS on the target machine. You will be prompted for confirmation, WiFi credentials, and a root password. Replace <INSTALLER-IP> with the actual IP address of the installer.

```bash
clan machines install test-machine --target-host root@<INSTALLER-IP>
```

--------------------------------

### Deploy KDE Plasma Service

Source: https://github.com/clan/clan-core/blob/main/clanServices/kde/README.md

Example of how to deploy the KDE Plasma service on all machines or specific hosts within your inventory.

```nix
inventory = {
  instances = {
    kde = {

      # Deploy on all machines
      roles.default.tags = [ "all" ];

      # Or individual hosts
      roles.default.machines.laptop = { };
    };
  };
};

```

--------------------------------

### Before: Simple services definition

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/migrate-inventory-services.md

This is an example of a simple service definition using the old `clanModules` format.

```nix
services = {
    admin = {
        simple = {
            roles.default.tags = [ "all" ];

            roles.default.config = {
                allowedKeys = {
                    "key-1" = "ssh-ed25519 AAAA...0J jon@jon-os";
                };
            };
        };
    };
};

```

--------------------------------

### Start Storybook

Source: https://github.com/clan/clan-core/blob/main/pkgs/clan-app/README.md

Navigate to the ui directory and run this command to start Storybook for UI component development.

```console
cd ui && npm run storybook
```

--------------------------------

### Installer SSH Prompt

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/quick-start.md

This is the expected output when successfully SSH'd into the NixOS installer environment.

```text
[root@nixos-installer:~]#
```

--------------------------------

### Install Database Server

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/backup-advanced.md

Install the database server after the backup server. This ensures that any cross-machine dependencies, like SSH keys, are correctly established.

```bash
clan machines install postgres-server --target-host root@<POSTGRES-IP>
```

--------------------------------

### Install a machine configuration

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/services/intro-to-services-revised.md

Use the `clan machines install` command to deploy the initial Clan configuration to a machine. This command is used when setting up a machine for the first time.

```bash
clan machines install sally-laptop
```

--------------------------------

### Multiple Workstations with Different Backup Schedules

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/backup-advanced.md

This example demonstrates configuring three workstations to back up to a NAS, each with a unique daily backup schedule.

```nix
# clan.nix
{
  inventory.machines = {
    laptop = {
      deploy.targetHost = "root@192.168.1.10";
      tags = [ "workstation" ];
    };
    desktop = {
      deploy.targetHost = "root@192.168.1.11";
      tags = [ "workstation" ];
    };
    work-pc = {
      deploy.targetHost = "root@192.168.1.12";
      tags = [ "workstation" ];
    };
    nas = {
      deploy.targetHost = "root@192.168.1.50";
    };
  };

  inventory.instances = {
    borgbackup = {
      roles.client.machines = {
        "laptop" = {
          settings.startAt = "*-*-* 02:00:00";
        }; # 2 AM
        "desktop" = {
          settings.startAt = "*-*-* 03:00:00";
        }; # 3 AM
        "work-pc" = {
          settings.startAt = "*-*-* 04:00:00";
        }; # 4 AM
      };
      roles.server.machines."nas" = {
        settings.address = "192.168.1.50";
        settings.directory = "/data/backups";
      };
    };
  }
}
```

--------------------------------

### Admin Keypair Output Example

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/vars/sops/secrets.md

This is an example of the output you will receive after generating your admin keypair. It includes your public key and the location of your generated private key.

```console
Public key: age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7

Generated age private key at '/home/joerg/.config/sops/age/keys.txt' for your user. Please back it up on a secure location or you will lose access to your secrets.
Also add your age public key to the repository with 'clan secrets users add YOUR_USER age1wkth7uhpkl555g40t8hjsysr20drq286netu8zptw50lmqz7j95sw2t3l7' (replace YOUR_USER with your actual username)
```

--------------------------------

### Nix Configuration Example

Source: https://github.com/clan/clan-core/blob/main/docs/src/test.md

A Nix configuration snippet showing instance settings for dynamic DNS. It includes comments and highlighted lines.

```nix
inventory.instances = {
  dyndns = {
    roles.default.machines."jon" = { }; # [!code --]
    roles.default.settings = { # [!code ++]
      period   = 15;                # minutes
      settings = {
        "all-jon-blog" = {
          provider         = "porkbun";
          domain           = "jon.blog";

          # (1) tell the secret-manager which key we are going to store
          secret_field_name = "secret_api_key";

          # everything below is copied verbatim into config.json
          extraSettings = {
            host         = "@,home,test";   # (2) comma-separated list of sub-domains [!code highlight]
            ip_version   = "ipv4";
            ipv6_suffix  = "";
            api_key      = "pk1_4bb2b231275a02fdc23b7e6f3552s01S213S"; # (3) public – safe to commit
          };
        };
      };
    };
  };
};
```

--------------------------------

### Initialize Hardware Configuration

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/quick-start.md

Detects the target machine's hardware and saves it to your project. Replace <INSTALLER-IP> with the actual IP address of the installer.

```bash
clan machines init-hardware-config test-machine --target-host root@<INSTALLER-IP>
```

--------------------------------

### Basic WireGuard Setup with Single Controller

Source: https://github.com/clan/clan-core/blob/main/clanServices/wireguard/README.md

Configure a single WireGuard controller with its public endpoint and optional port. Peers require no specific configuration in this setup.

```nix
# In your clan.nix
{
  instances = {
    wireguard = {
      module.name = "wireguard";
      module.input = "clan-core";
      roles.controller = {
        machines.server1 = { };
        settings = {
          # Public endpoint where this controller can be reached
          endpoint = "vpn.example.com";
          # Optional: Change the UDP port (default: 51820)
          port = 51820;
        };
      };
      roles.peer = {
        # No configuration needed if only one controller exists
        machines.laptop1 = { };
      };
    };
  };
}

```

--------------------------------

### Syncthing Configuration Example

Source: https://github.com/clan/clan-core/blob/main/clanServices/syncthing/README.md

Defines Syncthing roles and folder configurations. Use absolute paths for folder locations to ensure reliable synchronization.

```nix
{ instances.syncthing = { roles.peer.tags = [ "all" ]; roles.peer.settings.folders = { documents = { path = "/home/youruser/syncthing/documents"; }; }; }; }
```

--------------------------------

### Start Storybook Instance

Source: https://github.com/clan/clan-core/blob/main/pkgs/clan-app/ui/README.md

Launches Storybook, a tool for developing and showcasing UI components in isolation. Refer to Storybook documentation for writing stories.

```bash
npm run storybook
```

--------------------------------

### Basic Nix Code Example

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/styleguide.md

A simple Nix code snippet demonstrating basic syntax.

```nix
let
  is = nix: nix;
in
{
  this = is "valid";
}
```

--------------------------------

### Example Disk Template Structure

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/disko-templates/community.md

A Disko disk template consists of two files: `default.nix` and `README.md`.

```text
└── ext4-single-disk
    ├── default.nix
    └── README.md
```

--------------------------------

### Configure Single Garage Instance

Source: https://github.com/clan/clan-core/blob/main/clanServices/garage/README.md

Example Nix configuration to provision a single instance of Garage. Customize behavior via `services.garage.settings`.

```nix
instances = {
    garage = {
        roles.default.machines."server" = {};
    };
};

```

--------------------------------

### Start Development Server with New Tab

Source: https://github.com/clan/clan-core/blob/main/docs/README.md

Use the '-b' flag with 'clan-site dev' to open the development site in a new browser tab.

```bash
clan-site dev -b
```

--------------------------------

### Run Nix Anywhere with Default Version

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/CONTRIBUTING.md

Example of how clan-cli invokes nixos-anywhere with a default pinned version.

```python
run(
    nix_shell(
        ["nixos-anywhere"],
        cmd,
    ),
    RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
)
```

--------------------------------

### After: sshd Service Configuration

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/migrate-admin-service.md

Example of the 'sshd' service configuration after migration, replacing 'admin' service settings.

```nix
instances = {
  sshd = {
    roles.server.tags = [ "all" ];
    roles.server.settings = {
      authorizedKeys = {
        "my-key" = "ssh-ed25519 AAAA...";
      };
      certificate.searchDomains = [ "mydomain.com" ];
      hostKeys.rsa.enable = true;
    };
    # Optional: add client role if you want machines to trust the CA
    roles.client.tags = [ "all" ];
  };
};
```

--------------------------------

### Confirm SSH Access to Installer

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/quick-start.md

Verify that you can SSH into the installer environment using the copied SSH key. This confirms successful SSH setup.

```sh
ssh root@<INSTALLER-IP>
```

--------------------------------

### Original disko.nix with clanModules.disk-id

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/disk-id.md

Example of a disko.nix file that imports and uses clanModules.disk-id for dynamic disk configuration.

```nix
{ 
  lib,
  clan-core,
  config,
  ... 
}:

let
  suffix = config.clan.core.vars.generators.disk-id.files.diskId.value;
in
{
  imports = [
    clan-core.clanModules.disk-id
  ];

  # DO NOT EDIT THIS FILE AFTER INSTALLATION of a machine
  # Otherwise your system might not boot because of missing partitions / filesystems
  boot.loader.grub.efiSupport = lib.mkDefault true;
  boot.loader.grub.efiInstallAsRemovable = lib.mkDefault true;
  disko.devices = {
    disk = {
      "main" = {
        # suffix prevents disk name collisions
        name = "main-" + suffix;
        type = "disk";
        # Set the following in flake.nix for each machine:
        # device = $DISK_UUID;
        content = {};
      };
    };
  };
}

```

--------------------------------

### Run Development Server

Source: https://github.com/clan/clan-core/blob/main/pkgs/clan-app/ui/README.md

Starts the application in development mode, enabling hot-reloading for edits. Access the app at http://localhost:3000.

```bash
npm run dev
```

```bash
npm start
```

--------------------------------

### Create New Machine Command

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/styleguide.md

Example of a Clan CLI command to create a new machine, demonstrating a 'good' practice for presenting commands.

```bash
clan machines create --name webserver
```

--------------------------------

### Add Packages to a Machine Configuration

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-hetzner.md

Declare packages to be installed on a specific machine within your `clan.nix` configuration file. This example adds 'bat', 'btop', and 'tldr'.

```nix
inventory.instances = {
    packages = {
      roles.default.machines."test-machine".settings = {
        packages = [ "bat" "btop" "tldr" ];
      };
    };
    # ... existing wifi service ...
  };
```

--------------------------------

### Example NixOS Flake Configuration

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/convert-existing-NixOS-configuration.md

A common Nix flake structure defining NixOS configurations for multiple hosts. This serves as the starting point for migration to Clan.

```nix
{
  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

  outputs =
    { self, nixpkgs, ... }:
    {

      nixosConfigurations = {

        berlin = nixpkgs.lib.nixosSystem {
          system = "x86_64-linux";
          modules = [ ./machines/berlin/configuration.nix ];
        };

        cologne = nixpkgs.lib.nixosSystem {
          system = "x86_64-linux";
          modules = [ ./machines/cologne/configuration.nix ];
        };
      };
    };
}

```

--------------------------------

### Get User Password for Alice's Laptop

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/intro-to-backups.md

Retrieves the user password for Alice's laptop from Clan's variable store. This is typically used during initial setup or for SSH access.

```bash
clan vars get alice-laptop user-password-alice/user-password
```

--------------------------------

### Create Welcome Markdown File

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/intro-to-backups.md

Creates a markdown file named 'welcome.md' in the 'documents' directory and adds 'Hello World!' content. This is part of setting up files for backup.

```bash
cd documents
nano welcome.md
```

```text
Hello World!
```

--------------------------------

### Install NixOS on Target Machine

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-hetzner.md

Install NixOS on the target machine using the clan machines install command. You will be prompted to confirm the installation and set a root password.

```bash
clan machines install test-machine
```

--------------------------------

### Build, Preview, and Open in Browser

Source: https://github.com/clan/clan-core/blob/main/pkgs/clan-site/README.md

Builds the site for production, previews it locally, and opens it in a new browser tab. This is a convenient command for testing the final output.

```sh
clan-site build -b
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/clan/clan-core/blob/main/pkgs/clan-app/ui/README.md

Installs project dependencies using npm, pnpm, or yarn. Ensure you have one of these package managers installed.

```bash
$ npm install # or pnpm install or yarn install
```

--------------------------------

### Copy SSH Public Key to Installer

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/quick-start.md

Use `ssh-copy-id` to copy your SSH public key to the installer environment. This allows passwordless SSH access to the installer IP address. Replace `<INSTALLER-IP>` with the IP address shown on the installer's screen.

```sh
ssh-copy-id -i ~/.ssh/id_ed25519.pub root@<INSTALLER-IP>
```

--------------------------------

### Initialize Clan Project

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/quick-start.md

Downloads the Clan CLI and starts the project creation process. You will be prompted to enter a project name and domain. Remember to back up the generated age key.

```bash
nix run https://clan.lol/install/{{ version }} --refresh -- init
```

--------------------------------

### Define a Wi-Fi Instance

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/inventory/intro-to-inventory.md

This example shows how to define an instance of the `wifi` service. It assigns the default role to all machines tagged `laptop` and configures a home network.

```nix
inventory.instances = {
  wifi = {
    roles.default.tags = [ "laptop" ];
    roles.default.settings.networks.home = {};
  };
};
```

--------------------------------

### Install Nix with Flakes Enabled

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/install-nix.md

Installs Nix using the official installer script. The `--enable-flakes` flag ensures that Nix features required by Clan are enabled without interactive prompts.

```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/nix-installer | sh -s -- install --enable-flakes
```

--------------------------------

### Verify clan-cli installation

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/migrations/convert-existing-NixOS-configuration.md

After entering the development shell, verify the clan-cli installation by listing machines.

```console
❯ nix develop
[user@host:~/my-nixos-config]$ clan machines list
berlin
cologne
```

--------------------------------

### Create a Backup for Alice's Laptop

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/intro-to-backups.md

Initiates a backup process for 'alice-laptop' from the setup machine. This command triggers Clan to collect and store the stateful folders.

```bash
clan backups create alice-laptop
```

--------------------------------

### Download NixOS Installer ISO (aarch64)

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-physical.md

Download the NixOS installer ISO image for aarch64 (ARM) architecture.

```bash
wget https://github.com/nix-community/nixos-images/releases/download/nixos-26.05/nixos-installer-aarch64-linux.iso
```

--------------------------------

### Install Pre-commit Hook

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/CONTRIBUTING.md

Installs a git hook that runs Nix formatter and lint checks on staged files before each commit.

```bash
./scripts/pre-commit
```

--------------------------------

### Initialize Hardware Configuration

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-aws.md

Gather hardware configuration from the target machine. Ensure you replace `<IP-ADDRESS>` with the actual IP and specify the correct username.

```bash
clan machines init-hardware-config test-machine --target-host ubuntu@<IP-ADDRESS>
```

--------------------------------

### Copy SSH Public Key to Installer

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/disk-encryption.md

Ensure your SSH public key is available on the NixOS installer to allow remote access.

```bash
ssh-copy-id root@nixos-installer.local -i ~/.config/clan/nixos-anywhere/keys/id_ed25519
```

--------------------------------

### Building and Previewing Production Site

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/writing-documentation.md

Use `clan-site build -s` to build the production version of the site and serve it locally for preview. The `-s` flag enables serving, and `-b` can be added to automatically open it in a browser.

```bash
clan-site build -s
```

--------------------------------

### Example Output of Vars List

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/vars/intro-to-vars.md

This is an example of the output you might see when listing vars for a machine. Sensitive values are hidden with asterisks.

```console
user-password-root/user-password-hash ********
user-password-root/user-password ********
openssh/ssh.id_ed25519.pub ssh-ed25519 AAAA...
```

--------------------------------

### Enter Project Directory and Activate Environment

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/quick-start.md

Navigates into your newly created project directory and enables the development environment, making all Clan tools accessible.

```bash
cd MY-CLAN-1
direnv allow
```

--------------------------------

### Search for Container Test Examples

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/testing.md

Use ripgrep to find existing examples of NixOS container tests within the clan-core project.

```console
rg self.clanLib.test.containerTest
```

--------------------------------

### Example Filetree Structure

Source: https://github.com/clan/clan-core/blob/main/lib/README.md

Demonstrates a typical file organization for clan-specific Nix modules, showing how features and subfeatures are structured within directories. This helps in understanding the project's modular design.

```sh
.
├── default.nix
├── clan
│   ├── default.nix
│   └── test.nix
└── inventory
    ├── services-subfeature
    │   ├── default.nix
    │   └── test.nix
    ├── instances-subfeature # <- We immediately see that this feature is not tested on itself.
    │   └── default.nix
    ├── default.nix
    └── test.nix
```

--------------------------------

### Minimal Synapse and Element Setup

Source: https://github.com/clan/clan-core/blob/main/clanServices/matrix-synapse/README.md

This configuration sets up Synapse with the Element web client, backed by PostgreSQL and nginx. It also defines an admin user and a regular user.

```nix
instances = {
    matrix-synapse = {
        roles.default.machines."jon".settings = {
            acmeEmail = "admins@clan.lol";
            server_tld = "clan.test";
            app_domain = "matrix.clan.test";
            users.admin.admin = true;
            users.someuser = { };
        };
    };
};

```

--------------------------------

### Create a Google Cloud Server Instance

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-google.md

Launches a new Ubuntu 22.04 LTS server instance on Google Cloud with specified configurations. Ensure you have the gcloud CLI installed and authenticated.

```text
gcloud compute instances create linux-server-01 \
    --machine-type=e2-medium \
    --image-family=ubuntu-2204-lts \
    --image-project=ubuntu-os-cloud \
    --boot-disk-size=20GB \
    --metadata="ssh-keys=$(whoami):$(cat ~/.ssh/id_ed25519.pub)" \
    --no-shielded-secure-boot \
    --no-shielded-vtpm \
    --no-shielded-integrity-monitoring
```

--------------------------------

### Install nix-darwin

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/macos.md

Install nix-darwin on a macOS device by running the darwin-rebuild command with a specific flake. Ensure your Clan flake is uploaded to the device first.

```bash
sudo nix run nix-darwin/master#darwin-rebuild -- switch --flake .#yourmachine
```

--------------------------------

### Configure Additional Per-Machine WiFi Networks

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/inventory/intro-to-inventory.md

Extends the per-machine WiFi settings example by adding more networks for a third laptop. Demonstrates how per-machine settings merge with role-wide settings.

```nix
inventory.instances = {
  wifi = {
    roles.default.settings.networks.home = {};      # All laptops get home WiFi
    roles.default.machines."sally-laptop" = {
      settings.networks.office = {};                # Sally also gets office WiFi
    };
    roles.default.machines."fred-laptop" = {
      settings.networks.office = {};                # Fred gets office WiFi
      settings.networks.guest = {};                 # Fred also gets the guest network
    };
  };
};
```

--------------------------------

### Download NixOS Installer ISO

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/quick-start.md

Use wget to download the NixOS installer ISO for x86_64 machines. Replace `x86_64` with `aarch64` for ARM machines.

```bash
wget https://github.com/nix-community/nixos-images/releases/download/nixos-26.05/nixos-installer-x86_64-linux.iso
```

--------------------------------

### Verify Package Installation

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-hetzner.md

Check if packages have been successfully installed on the remote machine by using the 'which' command. This confirms the binaries are available in the system's PATH.

```bash
which bat
which btop
which tldr
```

--------------------------------

### Interactive VM Test Commands

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/contributing/testing.md

Example commands to run within an interactive VM test shell. Use `start_all()` to begin and then execute commands on individual machines.

```python
start_all()
machine1.succeed("echo hello")
```

--------------------------------

### User Configuration of Multiple Service Instances

Source: https://github.com/clan/clan-core/blob/main/docs/src/decisions/01-Clan-Modules.md

Demonstrates how a user configures two instances of the 'networking' service with different settings for roles and machines.

```nix
{ 
  inventory.services = {
    # anything inside an instance is instance specific
    networking."instance1" = {
      roles.client.tags = [ "all" ];
      machines.foo.config = { ... /* machine specific settings */ };

      # this will not apply to `clients` outside of `instance1`
      roles.client.config = { ... /* client specific settings */ };
    };
    networking."instance2" = {
      roles.server.tags = [ "all" ];
      config = { ... /* applies to every machine that runs this instance */ };
    };
  };
}

```

--------------------------------

### Verify Nix Installation

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/install-nix.md

Confirms that Nix has been installed correctly by checking its version. If the command is not found, restarting the terminal is recommended to update the PATH environment variable.

```bash
nix --version
```

--------------------------------

### Run kexec and Partition Disks

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/disk-encryption.md

Initiate the kexec process and partition the disks using the specified machine configuration.

```bash
clan machines install <mymachine> --target-host root@nixos-installer.local --phases kexec,disko
```

--------------------------------

### Configure Multiple Backups for a Single Client

Source: https://github.com/clan/clan-core/blob/main/docs/src/guides/backups/backup-advanced.md

This Nix configuration demonstrates backing up a 'postgres-server' to both a local VM and a Hetzner storage box simultaneously. Ensure unique meta.name and meta.domain for each clan.

```nix
{ 
  # Ensure this is unique among all clans you want to use.
  meta.name = "MY-BACKUP-CLAN";
  meta.domain = "mybackupclan.lol";

  inventory.machines = {
    postgres-server = {
      deploy.targetHost = "root@<IP-ADDRESS>"; # REPLACE WITH POSTGRES-SERVER'S IP ADDRESS; keep "root@"
      tags = [ ];
    };
    backup-server = {
      deploy.targetHost = "root@<IP-ADDRESS>"; # REPLACE WITH BACKUP-SERVER'S IP ADDRESS; keep "root@"
      tags = [ ];
    };
  };

  # Docs: See https://clan.lol/docs/{{ version }}/services/definition
  inventory.instances = {

    borgbackup = {
      roles.client.machines."postgres-server" = {
        # declares postgres-server a client (ONE time)
        settings.destinations."storagebox" = {
          # Destination #1
          repo = "<HETZNER-USER>@<HETZNER-USER>.your-storagebox.de:/./borgbackup"; # REPLACE <HETZNER-USER> with your Hetzner storage box username
          rsh = "ssh -p 23 -oStrictHostKeyChecking=accept-new -i /run/secrets/vars/borgbackup/borgbackup.ssh";
        };
      };
      roles.server.machines."backup-server" = {
        # default server
        settings.address = "<IP-ADDRESS>"; # REPLACE WITH BACKUP-SERVER'S IP ADDRESS
        settings.directory = "/var/lib/borgbackup";
      };
    };

    # Docs: https://clan.lol/docs/{{ version }}/services/official/sshd
    # SSH service for secure remote access to machines.
    sshd = {
      roles.server.tags.all = { };
      roles.server.settings.authorizedKeys = {
        "admin-machine-1" = "PASTE_YOUR_KEY_HERE";
      };
    };

    # Docs: https://clan.lol/docs/{{ version }}/services/official/users
    # Root password management for all machines.
    user-root = {
      module = {
        name = "users";
      };
      roles.default.tags.all = { };
      roles.default.settings = {
        user = "root";
        prompt = true;
      };
    };
  };

  # Additional NixOS configuration can be added here.
  machines = {

    postgres-server =
      { config, ... }:
      {
        services.postgresql = {
          enable = true;
          ensureDatabases = [ "mydatabase" ];
        };

        clan.core.postgresql.enable = true;
        clan.core.postgresql.databases.mydatabase = { };

        clan.core.state."postgresql" = {
          folders = [ ];
          preBackupScript = ''
            systemctl stop postgresql
          '';
          postBackupScript = ''
            systemctl start postgresql
          '';
        };
      };

  }
}

```

--------------------------------

### Activate Network Connection with nmtui

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-physical.md

Use nmtui to activate a network connection from the command line during installation. This is useful for establishing internet access before the main installation is complete.

```bash
nmtui
```

--------------------------------

### Create Machine Configuration

Source: https://github.com/clan/clan-core/blob/main/docs/src/getting-started/getting-started-virtualbox.md

Add a new machine to your Clan inventory. Replace 'test-machine' with your desired machine name.

```bash
clan machines create test-machine
```

--------------------------------

### ClanLib Structure Example

Source: https://github.com/clan/clan-core/blob/main/lib/README.md

Illustrates how functions within lib can depend on each other to create new abstractions, forming a recursive attribute set. This example shows the final clanLib being constructed with dependencies on itself.

```nix
#     ↓ The final clanLib
{ lib, clanLib, ... }:
# ↓ portion to add to clanLib
{
  inventory.resolveTags = tags: inventory.machines; # implementation
  inventory.buildMachines = x: clanLib.inventory.resolveTags x; # implementation
}
```