clan-core/creating-your-first-clan.md at d634f2c9aeda5b5a3803f04d316dfdfe36a82592

Files

Johannes Kirschbauer 90b1033870 docs: unify markdown files with documentation titles

This is preparational work to reduce the surface are of the different mappings

We want to reduce the following:

/guides/secrets.md -> Guides/getting started/How to use flakes with sops -> with '# Secrets Management'

- Title
- URI
- Filepath

should follow a stricter pattern to make it easy to maintain

2025-10-03 16:08:20 +02:00

3.4 KiB

Raw Blame History

Ready to manage your fleet of machines?

We will create a declarative infrastructure using clan, git, and nix flakes.

You'll finish with a centrally managed fleet, ready to import your existing NixOS configuration.

Prerequisites

Make sure you have the following:

💻 Administration Machine: Run the setup commands from this machine.

🛠️ Nix: The Nix package manager, installed on your administration machine.

??? info "How to install Nix (Linux / MacOS / NixOS)"

  **On Linux or macOS:**

  1.  Run the recommended installer:
      ```shellSession
      curl --proto '=https' --tlsv1.2 -sSf -L [https://install.determinate.systems/nix](https://install.determinate.systems/nix) | sh -s -- install
      ```

  2.  After installation, ensure flakes are enabled by adding this line to `~/.config/nix/nix.conf`:
      ```
      experimental-features = nix-command flakes
      ```

  **On NixOS:**

  Nix is already installed. You only need to enable flakes for your user in your `configuration.nix`:

  ```nix
  {
    nix.settings.experimental-features = [ "nix-command" "flakes" ];
  }
  ```
  Then, run `nixos-rebuild switch` to apply the changes.

🎯 Target Machine(s): A remote machine with SSH, or your local machine (if NixOS).

Create a New Clan

Navigate to your desired directory:
```
cd <your-directory>
```

Create a new clan flake:

Note: This creates a new directory in your current location

nix run https://git.clan.lol/clan/clan-core/archive/main.tar.gz#clan-cli --refresh -- flakes create

Enter a name in the prompt:
```
Enter a name for the new clan: my-clan
```

Project Structure

Your new directory, my-clan, should contain the following structure:

my-clan/
├── clan.nix
├── flake.lock
├── flake.nix
├── modules/
└── sops/

!!! note "Templates" This is the structure for the default template.

Use `clan templates list` and `clan templates --help` for available templates & more. Keep in mind that the exact files may change as templates evolve.

Activate the Environment

To get started, cd into your new project directory.

cd my-clan

Now, activate the environment using one of the following methods.

=== "Automatic (direnv, recommended)" Prerequisite: You must have nix-direnv installed.

Run `direnv allow` to automatically load the environment whenever you enter this directory.
```shellSession
direnv allow
```

=== "Manual (nix develop)" Run nix develop to load the environment for your current shell session.

```shellSession
nix develop
```

Verify the Setup

Once your environment is active, verify that the clan command is available by running:

clan show

You should see the default metadata for your new clan:

Name: __CHANGE_ME__
Description: None

This confirms your setup is working correctly.

You can now change the default name by editing the meta.name field in your clan.nix file.

{
  # Ensure this is unique among all clans you want to use.
  meta.name = "__CHANGE_ME__";

  # ...
  # elided
}

3.4 KiB Raw Blame History