docs: move getting-started out of guides

2025-10-03 16:50:10 +02:00
parent 90b1033870
commit b1f6dd58f3
17 changed files with 43 additions and 45 deletions
--- a/docs/site/getting-started/add-services.md
+++ b/docs/site/getting-started/add-services.md
@@ -0,0 +1,75 @@
+A service in clan is a self-contained, reusable unit of system configuration that provides a specific piece of functionality across one or more machines.
+
+Think of it as a recipe for running a tool — like automatic backups, VPN networking, monitoring, etc.
+
+In Clan Services are multi-Host & role-based:
+
+- Roles map machines to logical service responsibilities, enabling structured, clean deployments.
+
+- You can use tags instead of explicit machine names.
+
+To learn more: [Guide about clanService](/guides/inventory/clanServices.md)
+
+!!! Important
+    It is recommended to add at least one networking service such as `zerotier` that allows to reach all your clan machines from your setup computer across the globe.
+
+## Configure a Zerotier Network (recommended)
+
+```{.nix title="clan.nix" hl_lines="8-16"}
+{
+    inventory.machines = {
+        jon = { };
+        sara = { };
+    };
+
+    inventory.instances = {
+        zerotier = { # (1)
+            # Replace with the name (string) of your machine that you will use as zerotier-controller
+            # See: https://docs.zerotier.com/controller/
+            # Deploy this machine first to create the network secrets
+            roles.controller.machines."jon" = { }; # (2)
+            # Peers of the network
+            # this line means 'all' clan machines will be 'peers'
+            roles.peer.tags.all = { }; # (3)
+        };
+    };
+    # ...
+    # elided
+}
+```
+
+1. See [reference/clanServices](/reference/clanServices/index.md) for all available services and how to configure them.
+   Or read [authoring/clanServices](/guides/services/community.md) if you want to bring your own
+
+2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine.
+
+3. This line will add all machines of your clan as `peer` to zerotier
+
+## Adding more recommended defaults
+
+Adding the following services is recommended for most users:
+
+```{.nix title="clan.nix" hl_lines="7-14"}
+{
+    inventory.machines = {
+        jon = { };
+        sara = { };
+    };
+    inventory.instances = {
+        admin = { # (1)
+            roles.default.tags.all = { };
+            roles.default.settings = {
+                allowedKeys = {
+                    "my-user" = "ssh-ed25519 AAAAC3N..."; # (2)
+                };
+            };
+        };
+        # ...
+        # elided
+    };
+}
+```
+
+1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration.
+2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](/getting-started/add-machines.md#configuring-a-machine)
+3. Adds `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment.