services/syncthing: Add basic usage documentation

clanServices/syncthing/README.md

@@ -1,129 +1,20 @@
-# Syncthing Service
-
-This service provides automatic Syncthing peer discovery and configuration for clan machines.
-
-## Features
-
-- Automatic peer discovery across all clan machines
-- Integration with ZeroTier for reliable connectivity
-- Configurable firewall rules for Syncthing ports
-- Certificate and key management through clan vars
-- Folder synchronization configuration
-
 ## Usage
 
 ```nix
 {
-  services.syncthing = {
+      instances.syncthing = {
-    instances.default = {
+        roles.peer.tags.all = { };
-      # Configure folders and external devices for all peers
+        roles.peer.settings.folders = {
-      roles.peer.settings = {
+          documents = {
-        extraDevices = {
+            path = "~/syncthing/documents";
-          phone = {
-            id = "P56IOI7-MZJNU2Y-IQGDREY-DM2MGTI-MGL3BXN-PQ6W5BM-TBBZ4TJ-XZWICQ2";
-            name = "My Phone";
-            addresses = [ "dynamic" ];
-          };
-          tablet = {
-            id = "A12BC34-DEFG567-HIJK890-LMNO123-PQRS456-TUVW789-XYZA012-BCDE345";
-            name = "Family Tablet";
-          };
-        };
-        
-        folders = {
-          shared-docs = {
-            path = "/home/shared/documents";
-            type = "sendreceive";
-          };
-          backup = {
-            path = "/home/backup";
-            type = "sendonly";
-            devices = [ "machine1" "machine2" ]; # Only share with specific machines
-            versioning = {
-              type = "simple";
-              params.keep = "10";
-            };
-          };
-          photos = {
-            path = "/home/photos";
-            devices = [ "phone" "tablet" ]; # Only share with mobile devices
-            type = "receiveonly";
           };
         };
       };
-      
-      # Per-machine configuration
-      roles.peer.machines = {
-        machine1 = {
-          folders = {
-            machine1-only = {
-              path = "/home/user/private";
-              type = "sendonly";
-            };
-          };
-        };
-        machine2 = {
-          openDefaultPorts = false; # Disable firewall rules
-          folders = {
-            machine2-photos = {
-              path = "/home/user/Pictures";
-              type = "receiveonly";
-            };
-          };
-        };
-      };
-    };
-  };
 }
 ```
 
-## Configuration Options
+Now the folder `~/syncthing/documents` will be shared with all your machines.
 
-### `openDefaultPorts`
-- **Type**: `bool`
-- **Default**: `true`
-- **Description**: Whether to open the default syncthing ports in the firewall
 
-### `extraDevices`
+## Documentation 
-- **Type**: `attrsOf (submodule)`
+Extensive documentation is available on the [Syncthing](https://docs.syncthing.net/) website.
-- **Default**: `{}`
-- **Description**: External syncthing devices not managed by clan (e.g., mobile phones)
-
-#### Extra Device Options
-- `id` (str): Device ID of the external syncthing device
-- `name` (str): Human readable name for the device (defaults to device key name)
-- `addresses` (listOf str): List of addresses for the device (default: ["dynamic"])
-
-### `folders`
-- **Type**: `attrsOf (submodule)`
-- **Default**: `{}`
-- **Description**: Folders to synchronize between peers
-
-#### Folder Options
-- `path` (str): Path to the folder to sync
-- `devices` (listOf str): List of device names to share this folder with. Empty list means all peers and extraDevices (default: [])
-- `type` (enum): Folder type - "sendreceive", "sendonly", or "receiveonly" (default: "sendreceive")
-- `ignorePerms` (bool): Ignore permission changes (default: false)
-- `rescanIntervalS` (int): Rescan interval in seconds (default: 3600)
-- `versioning` (submodule, optional): Versioning configuration
-  - `type` (enum): "external", "simple", "staggered", or "trashcan"
-  - `params` (attrs): Versioning parameters
-
-## Network Requirements
-
-When `openDefaultPorts` is true, this service opens the following firewall ports:
-- TCP 8384: Syncthing web GUI (on ZeroTier interfaces and public)
-- TCP/UDP 22000: Syncthing sync traffic (on ZeroTier interfaces)
-- UDP 21027: Syncthing discovery (on ZeroTier interfaces)
-
-## ZeroTier Integration
-
-When machines have ZeroTier configured, the service automatically adds ZeroTier IP addresses as preferred connection addresses for more reliable peer-to-peer communication.
-
-## Generated Variables
-
-The service generates the following variables for each machine:
-- `syncthing/key`: Private key for TLS
-- `syncthing/cert`: Certificate for TLS
-- `syncthing/api`: API key for web interface
-- `syncthing/id`: Device identifier (public)

clanServices/syncthing/default.nix

@@ -2,8 +2,13 @@
 {
   _class = "clan.service";
   manifest.name = "clan-core/syncthing";
-  manifest.description = "Syncthing file synchronization with automatic peer discovery";
+  manifest.description = "Syncthing is a continuous file synchronization program with automatic peer discovery";
-  manifest.categories = [ "File Sync" ];
+  manifest.categories = [
+    "Utility"
+    "System"
+    "Network"
+  ];
+  manifest.readme = builtins.readFile ./README.md;
 
   roles.peer = {
     interface =
@@ -152,11 +157,11 @@
                 value = {
                   name = machine;
                   id = readMachineVar machine "syncthing/id/value" "";
-                  addresses = [
+                  addresses =
-                    "dynamic"
+                    [
-                  ]
+                      "dynamic"
-                  ++
+                    ]
-                    lib.optional (readMachineVar machine "zerotier/zerotier-ip/value" null != null)
+                    ++ lib.optional (readMachineVar machine "zerotier/zerotier-ip/value" null != null)
                       "tcp://[${readMachineVar machine "zerotier/zerotier-ip/value" ""}]:22000";
                 };
               })

clanServices/syncthing/tests/vm/default.nix

@@ -18,7 +18,6 @@
           documents = {
             path = "/var/lib/syncthing/documents";
             type = "sendreceive";
-            rescanIntervalS = 1;
           };
           partly_shared = {
             devices = [
@@ -85,12 +84,12 @@
       machine1.succeed("echo music > /var/lib/syncthing/music/music")
       machine3.succeed("echo picture > /var/lib/syncthing/pictures/picture")
 
-      machine2.wait_for_file("/var/lib/syncthing/documents/document")
+      machine2.wait_for_file("/var/lib/syncthing/documents/document", 20)
-      machine3.wait_for_file("/var/lib/syncthing/documents/document")
+      machine3.wait_for_file("/var/lib/syncthing/documents/document", 20)
-      machine4.wait_for_file("/var/lib/syncthing/documents/document")
+      machine4.wait_for_file("/var/lib/syncthing/documents/document", 20)
 
-      machine4.wait_for_file("/var/lib/syncthing/music/music")
+      machine4.wait_for_file("/var/lib/syncthing/music/music", 20)
 
-      machine4.wait_for_file("/var/lib/syncthing/pictures/picture")
+      machine4.wait_for_file("/var/lib/syncthing/pictures/picture", 20)
     '';
 }

clanServices/syncthing/tests/vm/sops/machines/machine1/key.json

@@ -3,4 +3,4 @@
     "publickey": "age1numxr6m52fxrm9a7sdw4vdpkp463mm8qtuf5d0p0jde04wydfgtscwdx78",
     "type": "age"
   }
-]
+]

clanServices/syncthing/tests/vm/sops/machines/machine2/key.json

@@ -3,4 +3,4 @@
     "publickey": "age1aqng9vmlgth5aucu5ty2wa0kk9tvk7erj4s07hq03s6emu72fgxsqkrqql",
     "type": "age"
   }
-]
+]

clanServices/syncthing/tests/vm/sops/machines/machine3/key.json

@@ -3,4 +3,4 @@
     "publickey": "age1kul02mg50nxccsl38nvma0enrgx454wq0qdefllj4l0adqkllvls5wuhfr",
     "type": "age"
   }
-]
+]

clanServices/syncthing/tests/vm/sops/machines/machine4/key.json

@@ -3,4 +3,4 @@
     "publickey": "age1kqgx4elusxx4u8409gml5z6tvrsayqsphewsl93mtqn7pl2p5dwq9lujpj",
     "type": "age"
   }
-]
+]

docs/mkdocs.yml

@@ -100,6 +100,7 @@ nav:
               - reference/clanServices/packages.md
               - reference/clanServices/sshd.md
               - reference/clanServices/state-version.md
+              - reference/clanServices/syncthing.md
               - reference/clanServices/trusted-nix-caches.md
               - reference/clanServices/users.md
               - reference/clanServices/wifi.md