initial ESS Community NixOS module

2026-05-10 22:54:27 +02:00 · 2026-05-10 22:54:27 +02:00 · 997726aecd
commit 997726aecd
parent 18b970a750
11 changed files with 443 additions and 39 deletions
--- a/README.md
+++ b/README.md
@ -1 +1,118 @@
 # ess-helm-nixos
+
+NixOS configuration for hosting [Element Server Suite Community](https://element.io/server-suite/community) on a single VPS using K3s, Helm, and NixOS-managed nginx as the TLS-terminating reverse proxy.
+
+## Architecture
+
+```
+Internet
+   |
+   v :80 / :443
+NixOS nginx  (TLS via Let's Encrypt / ACME)
+   |
+   v :30080 (plain HTTP)
+K3s ingress-nginx
+   |
+   v ClusterIP
+ESS Helm chart
+   ├── Synapse          ess-helm.de
+   ├── MAS              auth.ess-helm.de
+   ├── Element Web      chat.ess-helm.de
+   ├── Element Admin    admin.ess-helm.de
+   └── Matrix RTC SFU   mrtc.ess-helm.de  (:30001 TCP / :30002 UDP direct)
+```
+
+Matrix user IDs: `@user:ess-helm.de`
+
+## DNS setup
+
+Create the following **A records** pointing to the VPS public IP:
+
+Record | Type | Value
+---|---|---
+`ess-helm.de` | A | `<VPS public IP>`
+`auth.ess-helm.de` | A | `<VPS public IP>`
+`chat.ess-helm.de` | A | `<VPS public IP>`
+`admin.ess-helm.de` | A | `<VPS public IP>`
+`mrtc.ess-helm.de` | A | `<VPS public IP>`
+
+## Firewall
+
+| Port | Protocol | Purpose |
+|---|---|---|
+| 80 | TCP | HTTP (ACME challenge + redirect to HTTPS) |
+| 443 | TCP | HTTPS (all ESS services via nginx) |
+| 30001 | TCP | Matrix RTC WebRTC TCP transport |
+| 30002 | UDP | Matrix RTC WebRTC muxed UDP transport |
+
+## Verification
+
+- Element Web: [chat.ess-helm.de](https://chat.ess-helm.de)
+- Federation tester: [federationtester.matrix.org/?server_name=ess-helm.de](https://federationtester.matrix.org/?server_name=ess-helm.de)
+- Matrix client well-known: [ess-helm.de/.well-known/matrix/client](https://ess-helm.de/.well-known/matrix/client)
+
+## Usage
+
+```nix
+# flake.nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
+
+    ess-helm.url = "github:sid/ess-helm";
+    ess-helm.inputs.nixpkgs.follows = "nixpkgs";
+
+    synix.url = "git+https://git.sid.ovh/sid/synix.git?ref=release-25.11";
+    synix.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = { self, nixpkgs, ess-helm, synix, ... }: {
+    nixosConfigurations.my-server = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        ess-helm.nixosModules.ess-helm
+        synix.nixosModules.nginx
+        ./configuration.nix
+      ];
+    };
+  };
+}
+```
+
+```nix
+# configuration.nix
+{
+  services.ess-helm = {
+    enable = true;
+    serverName = "example.com";
+    openFirewall = true;
+    configureNginx = true;
+  };
+
+  security.acme.defaults.email = "admin@example.com";
+  services.nginx = {
+    enable = true;
+    openFirewall = true;
+    forceSSL = true;
+  };
+}
+```
+
+Subdomains default to `auth.`, `chat.`, `admin.`, `mrtc.`. Override individually if needed:
+
+```nix
+services.ess-helm.elementWeb.subdomain = "element";  # -> element.example.com
+```
+
+Upgrade the ESS or ingress-nginx chart version:
+
+```nix
+services.ess-helm.ess = {
+  version = "26.X.Y";
+  hash = "...";
+};
+```
+
+## References
+
+- [ESS Community](https://element.io/en/server-suite/community)