Add SD image pipeline, documentation overhaul, and fix module issues

- Add automatic SD image builds for Raspberry Pi via Forgejo Actions - Enable binfmt emulation on cryodev-main for aarch64 cross-builds - Add sd-image.nix module to cryodev-pi configuration - Create comprehensive docs/ structure with installation guides - Split installation docs into: first-install (server), reinstall, new-client (Pi) - Add lib/utils.nix and apps/rebuild from synix - Fix headplane module for new upstream API (tale/headplane) - Fix various module issues (mailserver stateVersion, option conflicts) - Add placeholder secrets.yaml files for both hosts - Remove old INSTRUCTIONS.md (content moved to docs/)
2026-03-11 08:41:58 +01:00 · 2026-03-11 08:41:58 +01:00 · 5ba78886d2
commit 5ba78886d2
parent a5261d8ff0
44 changed files with 3570 additions and 609 deletions
--- a/docs/services/mailserver.md
+++ b/docs/services/mailserver.md
@ -0,0 +1,147 @@
+# Mailserver
+
+NixOS mailserver module providing a complete email stack with Postfix and Dovecot.
+
+## References
+
+- [Simple NixOS Mailserver](https://gitlab.com/simple-nixos-mailserver/nixos-mailserver)
+
+## Setup
+
+### DNS Records
+
+| Type | Hostname | Value |
+|------|----------|-------|
+| A | `mail` | `<SERVER_IP>` |
+| AAAA | `mail` | `<SERVER_IPV6>` |
+| MX | `@` | `10 mail.cryodev.xyz.` |
+| TXT | `@` | `"v=spf1 mx ~all"` |
+| TXT | `_dmarc` | `"v=DMARC1; p=none"` |
+
+DKIM records are generated automatically after first deployment.
+
+### Generate Password Hashes
+
+```bash
+nix-shell -p mkpasswd --run 'mkpasswd -sm bcrypt'
+```
+
+### Add to Secrets
+
+```bash
+sops hosts/cryodev-main/secrets.yaml
+```
+
+```yaml
+mailserver:
+  accounts:
+    admin: "$2y$05$..."
+    forgejo: "$2y$05$..."
+```
+
+### Configuration
+
+```nix
+# hosts/cryodev-main/services/mailserver.nix
+{ config, ... }:
+{
+  sops.secrets."mailserver/accounts/admin" = { };
+  sops.secrets."mailserver/accounts/forgejo" = { };
+  
+  mailserver = {
+    enable = true;
+    fqdn = "mail.cryodev.xyz";
+    domains = [ "cryodev.xyz" ];
+    
+    loginAccounts = {
+      "admin@cryodev.xyz" = {
+        hashedPasswordFile = config.sops.secrets."mailserver/accounts/admin".path;
+      };
+      "forgejo@cryodev.xyz" = {
+        hashedPasswordFile = config.sops.secrets."mailserver/accounts/forgejo".path;
+        sendOnly = true;
+      };
+    };
+  };
+}
+```
+
+## DKIM Setup
+
+After first deployment, get the DKIM public key:
+
+```bash
+sudo cat /var/dkim/cryodev.xyz.mail.txt
+```
+
+Add this as a TXT record:
+
+| Type | Hostname | Value |
+|------|----------|-------|
+| TXT | `mail._domainkey` | `v=DKIM1; k=rsa; p=...` |
+
+## Testing
+
+### Send Test Email
+
+```bash
+echo "Test" | mail -s "Test Subject" recipient@example.com
+```
+
+### Check Mail Queue
+
+```bash
+sudo postqueue -p
+```
+
+### View Logs
+
+```bash
+sudo journalctl -u postfix -f
+sudo journalctl -u dovecot2 -f
+```
+
+### Test SMTP
+
+```bash
+openssl s_client -connect mail.cryodev.xyz:587 -starttls smtp
+```
+
+### Verify DNS Records
+
+- [MXToolbox](https://mxtoolbox.com/)
+- [Mail-tester](https://www.mail-tester.com/)
+
+## Troubleshooting
+
+### Emails Not Sending
+
+Check Postfix status:
+
+```bash
+sudo systemctl status postfix
+```
+
+Check firewall (ports 25, 465, 587 must be open):
+
+```bash
+sudo iptables -L -n | grep -E '25|465|587'
+```
+
+### DKIM Failing
+
+Verify the DNS record matches the generated key:
+
+```bash
+dig TXT mail._domainkey.cryodev.xyz
+```
+
+### SPF Failing
+
+Verify SPF record:
+
+```bash
+dig TXT cryodev.xyz
+```
+
+Should return: `"v=spf1 mx ~all"`