From bb3c7576f8470dba5fe01f2431976fb340e5fc3f Mon Sep 17 00:00:00 2001
From: devydave <yannick-dev@tutanota.com>
Date: Thu, 13 Aug 2026 20:34:14 +0200
Subject: [PATCH] docs: add setup documentation

---
 nix/hosts/README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++
 tests/README.md     |  3 +-
 2 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 nix/hosts/README.md

diff --git a/nix/hosts/README.md b/nix/hosts/README.md
new file mode 100644
index 00000000..ee7b2448
--- /dev/null
+++ b/nix/hosts/README.md
@@ -0,0 +1,67 @@
+# Hosts
+These hosts are VMs used for running the integration tests on your local machine.
+The hosts contain a client where abra with the tests will be run and a server
+to simulate a remote machine.
+
+## Prepare the host
+For this setup to work you need a machine with NixOS and flakes enabled.
+
+1. Import the abra flake
+The install example is based on the [using nix flakes wiki page](https://nixos.wiki/wiki/flakes#Using_nix_flakes_with_NixOS).
+```nix
+inputs = {
+  abra = {
+    url = "git+https://git.coopcloud.tech/toolshed/abra.git";
+  };
+};
+```
+2. Add the host module to your configuration
+Now add the host module to your configuration. At the toplevel of a flake it could look like this:
+```nix
+desktop = inputs.nixpkgs.lib.nixosSystem {
+  system = "x86_64-linux";
+  modules = [
+    abra.nixosModules.host
+    ./configuration.nix
+  ];
+  specialArgs = inputs;
+};
+```
+3. Adjust the required config
+There are to options defined for 
+```nix
+abra.testing = {
+  enable = true; # loads the required config, when set true
+  externalInterface = "eth1"; # adjust this to your network interface that has access to the internet
+};
+```
+You can look up the interface with `ip link`. After that rebuild your system and you are read to go.
+
+## Get started
+All commands are run on the repository root path.
+1. Set path to repo 
+The VM will create a shared volume from the content of the file `tests/resources/path_to_repo`.
+Set the content of the file to the path of your abra repository.
+This will share the repository from your machine with the VM and you can edit files while testing without rebuiling
+or restarting the VM.
+2. Create the VMs
+```sh
+make vm-client-create
+make vm-server-create
+```
+3. Start the VMs
+```sh
+make vm-client-start
+make vm-server-start
+```
+After running that command you should be able to ping the machines.
+The client runs on 10.0.0.2 and server 10.0.0.3
+4. Connect to the client
+Running the following command will connect to the client VM via SSH.
+```sh
+make vm-client-connect
+```
+5. Run the tests
+```sh
+make test-integration
+```
diff --git a/tests/README.md b/tests/README.md
index 73858fbc..8a7ccecd 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -7,4 +7,5 @@
 
 * Integration tests are in `./tests/integration`. Please see [these
   docs](https://docs.coopcloud.tech/abra/hack/#integration-tests) for
-  instructions and tips on how to run them.
+  instructions and tips on how to run them. If you want to run it locally via nix,
+  read the [nix testing docs](../nix/hosts/README.md).