Improved Quickstart

docs/quickstart.md

@@ -28,34 +28,85 @@ If `.clan-flake` is missing, `clan-cli` will instead search for other indicators
 
 # Migrating Existing NixOS Configuration Flake
 
-## Integrating with Existing NixOS Machines
+Absolutely, let's break down the migration step by step, explaining each action in detail:
 
-If you already manage NixOS machines using a flake, you can integrate them with the clan-core as shown in the example below:
+#### Before You Begin
+
+1. **Backup Your Current Configuration**: Always start by making a backup of your current NixOS configuration to ensure you can revert if needed.
+
+   ```shell
+   cp -r /etc/nixos ~/nixos-backup
+   ```
+
+2. **Update Flake Inputs**: The patch adds a new input named `clan-core` to your `flake.nix`. This input points to a Git repository for Clan Core. Here's the addition:
 
    ```nix
-{
+   inputs.clan-core = {
-  description = "My custom NixOS flake";
+     url = "git+https://git.clan.lol/clan/clan-core";
+     inputs.nixpkgs.follows = "nixpkgs";
+   };
+   ```
 
-  inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core";
+   - `url`: Specifies the Git repository URL for Clan Core.
+   - `inputs.nixpkgs.follows`: Tells Nix to use the same `nixpkgs` input as your main input (in this case, it follows `nixpkgs`).
 
-  outputs = { clan-core, ... }: {
+3. **Update Outputs**: Then modify the `outputs` section of your `flake.nix` to adapt to Clan Core's new provisioning method. The key changes are as follows:
+
+   Add `clan-core` to the output
+
+   ```diff
+   -  outputs = { self, nixpkgs,  }:
+   +  outputs = { self, nixpkgs, clan-core }:
+   ```
+
+   Previous configuration:
+
+   ```nix
+   nixosConfigurations.example-desktop = nixpkgs.lib.nixosSystem {
+       system = "x86_64-linux";
+       modules = [
+           ./configuration.nix
+       ];
+       [...]
+   };
+   ```
+
+   After change:
+
+   ```nix
    nixosConfigurations = clan-core.lib.buildClan {
        directory = ./.;
        machines = {
-        turingmachine = {
+           example-desktop = {
-          nixpkgs.pkgs = nixpkgs.legacyPackages.aarch64-linux;
+               nixpkgs.hostPlatform = "x86_64-linux";
                imports = [
                    ./configuration.nix
                ];
            };
        };
    };
-  };
-}
    ```
 
-In this configuration:
-
-- `description`: Provides a brief description of the flake.
-- `inputs.clan-core.url`: Specifies the Clan Core template's repository URL.
    - `nixosConfigurations`: Defines NixOS configurations, using Clan Core’s `buildClan` function to manage the machines.
+   - Inside `machines`, a new machine configuration is defined (in this case, `example-desktop`).
+   - Inside `example-desktop` which is the target machine hostname, `nixpkgs.hostPlatform` specifies the host platform as `x86_64-linux`.
+
+4. **Rebuild and Switch**: Rebuild your NixOS configuration using the updated flake:
+
+   ```shell
+   sudo nixos-rebuild switch --flake .
+   ```
+
+   - This command rebuilds and switches to the new configuration. Make sure to include the `--flake .` argument to use the current directory as the flake source.
+
+5. **Test Configuration**: Before rebooting, verify that your new configuration builds without errors or warnings.
+
+6. **Reboot**: If everything is fine, you can reboot your system to apply the changes:
+
+   ```shell
+   sudo reboot
+   ```
+
+7. **Verify**: After the reboot, confirm that your system is running with the new configuration, and all services and applications are functioning as expected.
+
+By following these steps, you've successfully migrated your NixOS Flake configuration to include the `clan-core` input and adapted the `outputs` section to work with Clan Core's new machine provisioning method.