diff --git a/clanModules/deltachat/README.md b/clanModules/deltachat/README.md new file mode 100644 index 00000000..66968b37 --- /dev/null +++ b/clanModules/deltachat/README.md @@ -0,0 +1,15 @@ +Email-based instant messaging for Desktop. + +!!! warning "Under construction" + +!!! info + This module will automatically configure an email server on the machine for handling the e-mail messaging seamlessly. + +## Features + +- [x] **Email-based**: Uses any email account as its backend. +- [x] **End-to-End Encryption**: Supports Autocrypt to automatically encrypt messages. +- [x] **No Phone Number Required**: Uses your email address instead of a phone number. +- [x] **Cross-Platform**: Available on desktop and mobile platforms. +- [x] **Automatic Server Setup**: Includes your own DeltaChat server for enhanced control and privacy. +- [ ] **Bake a cake**: This module cannot cake a bake. diff --git a/clanModules/deltachat.nix b/clanModules/deltachat/default.nix similarity index 100% rename from clanModules/deltachat.nix rename to clanModules/deltachat/default.nix diff --git a/clanModules/flake-module.nix b/clanModules/flake-module.nix index de70b0c8..83b35809 100644 --- a/clanModules/flake-module.nix +++ b/clanModules/flake-module.nix @@ -9,7 +9,7 @@ }; borgbackup = ./borgbackup.nix; ergochat = ./ergochat.nix; - deltachat = ./deltachat.nix; + deltachat = ./deltachat; graphical = ./graphical.nix; localbackup = ./localbackup.nix; localsend = ./localsend.nix; @@ -17,7 +17,7 @@ moonlight = ./moonlight.nix; sshd = ./sshd.nix; sunshine = ./sunshine.nix; - syncthing = ./syncthing.nix; + syncthing = ./syncthing; root-password = ./root-password; thelounge = ./thelounge.nix; vm-user = ./vm-user.nix; diff --git a/clanModules/root-password/README.md b/clanModules/root-password/README.md index fd940a7d..1fd0c2ec 100644 --- a/clanModules/root-password/README.md +++ b/clanModules/root-password/README.md @@ -1,4 +1,4 @@ -## Usage +Creates a root-password !!! tip "This module sets the password for the root user (automatically)." diff --git a/clanModules/syncthing/README.md b/clanModules/syncthing/README.md new file mode 100644 index 00000000..6f719e78 --- /dev/null +++ b/clanModules/syncthing/README.md @@ -0,0 +1,34 @@ +Syncthing is a free, open-source file synchronization application designed to allow users to synchronize files between multiple devices over the internet or local networks securely and privately. + +It is an alternative to cloud-based file sharing services. + +## Usage + +We recommend configuring this module as an sync-service through the provided options. Although it provides a Web GUI through which more usage scenarios are supported. + +## Features + +- **Private and Secure**: Syncthing uses TLS encryption to secure data transfer between devices, ensuring that only the intended devices can read your data. +- **Decentralized**: No central server is involved in the data transfer. Each device communicates directly with others. +- **Open Source**: The source code is openly available for audit and contribution, fostering trust and continuous improvement. +- **Cross-Platform**: Syncthing supports multiple platforms including Windows, macOS, Linux, BSD, and Android. +- **Real-time Synchronization**: Changes made to files are synchronized in real-time across all connected devices. +- **Web GUI**: It includes a user-friendly web interface for managing devices and configurations. (`127.0.0.1:8384`) + +## Configuration + +- **Share Folders**: Select folders to share with connected devices and configure permissions and synchronization parameters. + +!!! info + Clan automatically discovers other devices. Automatic discovery requires one machine to be an [introducer](#clan.syncthing.introducer) + + If that is not the case you can add the other device by its Device ID manually. + You can find and share Device IDs under the "Add Device" button in the Web GUI. (`127.0.0.1:8384`) + +## Troubleshooting + +- **Sync Conflicts**: Resolve synchronization conflicts manually by reviewing file versions and modification times in the Web GUI (`127.0.0.1:8384`). + +## Support + +- **Documentation**: Extensive documentation is available on the [Syncthing website](https://docs.syncthing.net/). diff --git a/clanModules/syncthing.nix b/clanModules/syncthing/default.nix similarity index 100% rename from clanModules/syncthing.nix rename to clanModules/syncthing/default.nix diff --git a/docs/nix/scripts/renderOptions.py b/docs/nix/scripts/renderOptions.py index a679936a..90e014ae 100644 --- a/docs/nix/scripts/renderOptions.py +++ b/docs/nix/scripts/renderOptions.py @@ -53,11 +53,28 @@ def render_option_header(name: str) -> str: return f"# {name}\n" -def render_option(name: str, option: dict[str, Any]) -> str: +def join_lines_with_indentation(lines: list[str], indent: int = 4) -> str: + """ + Joins multiple lines with a specified number of whitespace characters as indentation. + + Args: + lines (list of str): The lines of text to join. + indent (int): The number of whitespace characters to use as indentation for each line. + + Returns: + str: The indented and concatenated string. + """ + # Create the indentation string (e.g., four spaces) + indent_str = " " * indent + # Join each line with the indentation added at the beginning + return "\n".join(indent_str + line for line in lines) + + +def render_option(name: str, option: dict[str, Any], level: int = 2) -> str: read_only = option.get("readOnly") res = f""" -## {sanitize(name)} +{"#" * level} {sanitize(name)} {{#{sanitize(name)}}} {"Readonly" if read_only else ""} {option.get("description", "No description available.")} @@ -74,12 +91,13 @@ def render_option(name: str, option: dict[str, Any]) -> str: """ example = option.get("example", {}).get("text") if example: + example_indented = join_lines_with_indentation(example.split("\n")) res += f""" ???+ example ```nix - {example} +{example_indented} ``` """ if option.get("relatedPackages"): @@ -100,15 +118,17 @@ def render_option(name: str, option: dict[str, Any]) -> str: def module_header(module_name: str) -> str: - return f"""# {module_name} - -To use this module, import it like this: + return f"# {module_name}\n" + + +def module_usage(module_name: str) -> str: + return f"""To use this module, import it like this: ```nix - {{config, lib, inputs, ...}}: {{ +{{config, lib, inputs, ...}}: {{ imports = [ inputs.clan-core.clanModules.{module_name} ]; # ... - }} +}} ``` """ @@ -133,7 +153,9 @@ def produce_clan_core_docs() -> None: # Create seperate files for nested options if len(option_name.split(".")) <= 2: # i.e. clan-core.clanDir - output = core_outputs.get(outfile, module_header(module_name)) + output = core_outputs.get( + outfile, module_header(module_name) + module_usage(module_name) + ) output += render_option(option_name, info) # Update the content core_outputs[outfile] = output @@ -182,11 +204,17 @@ def produce_clan_modules_docs() -> None: if readme_map.get(module_name, None): output += f"{readme_map[module_name]}\n" + output += module_usage(module_name) + + output += "\n## Module Options\n" for option_name, info in options.items(): - output += render_option(option_name, info) + output += render_option(option_name, info, 3) outfile = Path(OUT) / f"clanModules/{module_name}.md" - outfile.parent.mkdir(parents=True, exist_ok=True) + outfile.parent.mkdir( + parents=True, + exist_ok=True, + ) with open(outfile, "w") as of: of.write(output) diff --git a/docs/site/getting-started/machines.md b/docs/site/getting-started/machines.md index 9e758b54..80b7fb18 100644 --- a/docs/site/getting-started/machines.md +++ b/docs/site/getting-started/machines.md @@ -25,7 +25,7 @@ This process involves preparing a suitable hardware and disk partitioning config 2. Boot the target machine and connect it to a network that makes it reachable from your setup computer. -=== "**Cloud Machines**" +=== "**Baremetal Machines**" - [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH. - [x] **Machine configuration**: See our basic [configuration guide](./configure.md) diff --git a/docs/site/getting-started/networking.md b/docs/site/getting-started/networking.md index 7a42e408..7d2e2d74 100644 --- a/docs/site/getting-started/networking.md +++ b/docs/site/getting-started/networking.md @@ -10,7 +10,7 @@ include a new machine into the VPN. The VPN controller is initially essential for providing configuration to new peers. Once addresses are allocated, the controller's continuous operation is not essential. -### Instructions: +### Instructions 1. **Designate a Machine**: Label a machine as the VPN controller in the clan, referred to as `` henceforth in this guide. @@ -74,3 +74,22 @@ To introduce a new machine to the VPN, adhere to the following steps: The new machine is now part of the VPN, and the ZeroTier configuration on NixOS within the Clan project is complete. +## Decision + +We chose zerotier because in our tests it was the easiest solution to bootstrap. You can selfhost a controller and the controller doesn't need to be globally reachable. + +In the future we plan to add additional network technologies like tinc, head/tailscale, yggdrassil and mycelium. + +## Specification + +By default all machines within one clan are connected via the chosen network technology. + +``` +Clan + Node A + <-> (zerotier / mycelium / ...) + Node B +``` + +If you select multiple network technologies at the same time. e.g. (zerotier + yggdrassil) +One of them is the primary network and the above statement holds for the primary network.