From bad7d624bdf3f3d2ff759a3db1bf988366c38fc2 Mon Sep 17 00:00:00 2001
From: Luis-Hebendanz <luis.nixos@gmail.com>
Date: Wed, 30 Aug 2023 15:25:20 +0200
Subject: [PATCH] Improved Quickstart

---
 docs/quickstart.md | 101 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 76 insertions(+), 25 deletions(-)

diff --git a/docs/quickstart.md b/docs/quickstart.md
index 950e6783c..63cb208ca 100644
--- a/docs/quickstart.md
+++ b/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
 
-```nix
-{
-  description = "My custom NixOS flake";
+1. **Backup Your Current Configuration**: Always start by making a backup of your current NixOS configuration to ensure you can revert if needed.
 
-  inputs.clan-core.url = "git+https://git.clan.lol/clan/clan-core";
+   ```shell
+   cp -r /etc/nixos ~/nixos-backup
+   ```
 
-  outputs = { clan-core, ... }: {
-    nixosConfigurations = clan-core.lib.buildClan {
-      directory = ./.;
-      machines = {
-        turingmachine = {
-          nixpkgs.pkgs = nixpkgs.legacyPackages.aarch64-linux;
-          imports = [
-            ./configuration.nix
-          ];
-        };
-      };
-    };
-  };
-}
-```
+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:
 
-In this configuration:
+   ```nix
+   inputs.clan-core = {
+     url = "git+https://git.clan.lol/clan/clan-core";
+     inputs.nixpkgs.follows = "nixpkgs";
+   };
+   ```
 
-- `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.
+   - `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`).
+
+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 = {
+           example-desktop = {
+               nixpkgs.hostPlatform = "x86_64-linux";
+               imports = [
+                   ./configuration.nix
+               ];
+           };
+       };
+   };
+   ```
+
+   - `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.