3.8 KiB
Getting Started
Welcome to your simple guide on starting a new Clan project.
What's Inside
We've put together a straightforward guide to help you out:
- Starting with a New Clan Project: Create a new Clan from scratch.
- Integrating Clan using Flake-Parts
Starting with a New Clan Project
Create your own clan with these initial steps.
Prerequisites
Linux
Clan depends on nix installed on your system. Run the following command to install nix.
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
NixOS
If you run NixOS the nix
binary is already installed.
You will also need to enable the flakes
and nix-commands
experimental features.
# /etc/nix/nix.conf or ~/.config/nix/nix.conf
experimental-features = nix-command flakes
Other
Clan doesn't offer dedicated support for other operating systems yet.
Step 1: Add Clan CLI to Your Shell
Add the Clan CLI into your development workflow:
nix shell git+https://git.clan.lol/clan/clan-core#clan-cli
Step 2: Initialize Your Project
Set the foundation of your Clan project by initializing it as follows:
clan flakes create my-clan
This command creates the flake.nix
and .clan-flake
files for your project.
Step 3: Verify the Project Structure
Ensure that all project files exist by running:
tree
This should yield the following:
.
├── flake.nix
├── machines
│ ├── jon
│ │ ├── configuration.nix
│ │ └── hardware-configuration.nix
│ └── sara
│ ├── configuration.nix
│ └── hardware-configuration.nix
└── modules
└── shared.nix
5 directories, 6 files
!!! success
You just successfully bootstrapped your first clan directory.
What's Next?
- Deploy Machines: Learn how to deploy to any remote machine.
- Machine Configuration: Declare behavior and configuration of machines.
Edit Flake.nix
Open the flake.nix
file and set a unique clanName
if you want you can also set an optional clanIcon
or even a per machineIcon
. These will be used by our future clan GUI.
Remote into the target machine
Right now clan assumes that you already have NixOS running on the target machine.
If that is not the case you can use our installer image that automatically generates an endpoint reachable over TOR with a random ssh password.
On the remote execute:
-
Generate a hardware-config.nix
nixos-generate-config --root /etc/nixos --no-filesystems
-
Copy it over and put it into you
machines/jon/hardware-config.nix
folderscp -r root@<jon-ip>:/etc/nixos/hardware-config.nix ./machines/jon
-
Find the remote disk id by executing on the remote:
lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-
Edit the following fields inside the
flake.nix
clan.networking.targetHost = pkgs.lib.mkDefault "root@<IP_ADDRESS>";
clan.diskLayouts.singleDiskExt4 = { device = "/dev/disk/by-id/__CHANGE_ME__"; };
-
Generate secrets used by clan modules by executing
clan facts generate
Next Steps
Ready to expand? Explore how to install a new machine with the helpful documentation here. Ready to explore more?
-
Adding New Machines to your setup. Follow our templates
-
Use a USB drive to Set Up Machines: Setting up new computers remotely is easy with an USB stick. Learn how.