From 2229717860e7c677ea8b9653be7b9fdd481172ec Mon Sep 17 00:00:00 2001
From: padreug <padreug@aiolabs.dev>
Date: Sun, 12 Oct 2025 08:25:10 +0200
Subject: [PATCH] Add initial deployment configuration and setup instructions

Introduced a new example-krops.nix file for deployment configuration, providing a template for machine-specific setups. Updated the .gitignore to include krops.nix, ensuring user-specific configurations are not tracked. Expanded the DEPLOYMENT-GUIDE.md with detailed initial setup instructions, including steps for creating and customizing krops.nix and machine configurations, enhancing the onboarding process for new users.
---
 .gitignore          |  4 +++
 DEPLOYMENT-GUIDE.md | 37 ++++++++++++++++++++
 example-krops.nix   | 83 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 124 insertions(+)
 create mode 100644 example-krops.nix

diff --git a/.gitignore b/.gitignore
index 41ea1dc..bea7366 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,10 @@ web-app
 lnbits
 lnbits-extensions
 
+# User-specific deployment configuration
+# Copy example-krops.nix to krops.nix and customize
+krops.nix
+
 # Machine-specific configurations (user creates these)
 # Keep example-machine as a template
 config/machines/*
diff --git a/DEPLOYMENT-GUIDE.md b/DEPLOYMENT-GUIDE.md
index 3ee36f5..94aab0e 100644
--- a/DEPLOYMENT-GUIDE.md
+++ b/DEPLOYMENT-GUIDE.md
@@ -7,6 +7,43 @@ This setup builds the web-app **locally** with machine-specific configuration, t
 - Machine-specific `.env` files
 - Machine-specific images in the `public` folder
 
+## Initial Setup
+
+When you first clone this repository, you need to set up your local configuration:
+
+### 1. Create your krops.nix
+
+```bash
+# Copy the example template
+cp example-krops.nix krops.nix
+```
+
+### 2. Create your first machine configuration
+
+```bash
+# Copy the example machine template
+cp -r config/machines/example-machine config/machines/my-machine
+
+# Edit the configuration
+# - Change the domain in configuration.nix
+# - Add your hardware-configuration.nix (from nixos-generate-config)
+```
+
+### 3. Update krops.nix
+
+Edit `krops.nix` and:
+- Replace `example-machine` with your machine name
+- Update the SSH target (`root@your-host`)
+- Add to the `inherit` list and `all` script
+
+### 4. Deploy!
+
+```bash
+nix-build ./krops.nix -A my-machine && ./result
+```
+
+**Note:** Your `krops.nix` and machine configs in `config/machines/*` are gitignored. You can safely pull updates without overwriting your local configuration.
+
 ## Structure
 
 ```
diff --git a/example-krops.nix b/example-krops.nix
new file mode 100644
index 0000000..107aa20
--- /dev/null
+++ b/example-krops.nix
@@ -0,0 +1,83 @@
+let
+  krops = builtins.fetchGit {
+    url = "https://cgit.krebsco.de/krops/";
+    ref = "master";
+  };
+
+  lib = import "${krops}/lib";
+  pkgs = import "${krops}/pkgs" {};
+
+  # Define sources for each machine
+  source = name: lib.evalSource [
+    {
+      # NixOS configuration entry point
+      nixos-config.symlink = "config-machine/configuration.nix";
+
+      # Use nixpkgs from local NIX_PATH (much smaller than git clone)
+      # This copies your local <nixpkgs> without .git history (~400MB vs 6GB)
+      nixpkgs.file = {
+        path = toString <nixpkgs>;
+        useChecksum = true;
+      };
+
+      # Shared configuration files (only shared modules and files)
+      config-shared.file = toString ./config/shared.nix;
+      config-modules.file = toString ./config/modules;
+      config-nginx.file = toString ./config/nginx.nix;
+      config-pict-rs.file = toString ./config/pict-rs.nix;
+      config-lnbits.file = toString ./config/lnbits.nix;
+
+      # Machine-specific configuration files (only this machine's config)
+      config-machine.file = toString (./config/machines + "/${name}");
+
+      # Pre-built web-app (built locally with machine-specific config)
+      web-app-dist.file = toString (./build + "/${name}/dist");
+
+      # LNBits flake source
+      lnbits-src.file = toString ./lnbits;
+
+      # LNBits extensions (deployed to /var/lib/lnbits/extensions)
+      # Uncomment if you have custom extensions to deploy
+      # lnbits-extensions.file = toString ./lnbits-extensions;
+    }
+  ];
+
+  # Example machine deployment (copy this block for each machine)
+  # Replace "example-machine" with your machine name
+  # Replace "root@your-host" with your SSH target
+  example-machine = pkgs.krops.writeDeploy "deploy-example-machine" {
+    source = source "example-machine";
+    target = "root@your-host-or-ip";
+
+    # Avoid having to create a sentinel file.
+    # Otherwise /var/src/.populate must be created on the target node to signal krops
+    # that it is allowed to deploy.
+    force = true;
+  };
+
+  # Add more machines here following the same pattern:
+  # machine1 = pkgs.krops.writeDeploy "deploy-machine1" {
+  #   source = source "machine1";
+  #   target = "root@machine1-host";
+  #   force = true;
+  # };
+
+  # Deploy to all machines (update this list with your machines)
+  all = pkgs.writeScript "deploy-all" ''
+    #!${pkgs.bash}/bin/bash
+    set -e
+    echo "Deploying to example-machine..."
+    ${example-machine}
+    # Add your machines here:
+    # echo "Deploying to machine1..."
+    # ${machine1}
+    echo "All deployments completed!"
+  '';
+
+in {
+  # Export your machine deployments here
+  inherit example-machine all;
+
+  # Add your machines to the inherit list:
+  # inherit example-machine machine1 machine2 all;
+}