From b1f3683e3aede12e3783c5b954e86a93de78f964 Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Mon, 26 Jan 2026 09:46:38 +0000
Subject: [PATCH] issue: create 2909 - NixOS username exceeds 31 char limit

---
 2909-nixos-username-length-limit.md | 69 +++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 2909-nixos-username-length-limit.md

diff --git a/2909-nixos-username-length-limit.md b/2909-nixos-username-length-limit.md
new file mode 100644
index 0000000..ac3fb71
--- /dev/null
+++ b/2909-nixos-username-length-limit.md
@@ -0,0 +1,69 @@
+# NixOS Username Length Exceeds 31 Character Limit
+
+**ID:** 2909
+
+## Problem
+
+The NixOS module generates usernames that exceed the 31-character limit enforced by Linux/NixOS. When deploying ngit-grasp with domain-based instance names, the generated username format `ngit-grasp-{domain}` can easily exceed this limit.
+
+**Error:**
+```
+error: evaluation aborted with the following error message: 'Username 'ngit-grasp-ngit-danconwaydev-com' is longer than 31 characters which is not allowed!'
+```
+
+**Example:**
+- Domain: `ngit.danconwaydev.com`
+- Generated username: `ngit-grasp-ngit-danconwaydev-com` (36 characters)
+- Limit: 31 characters
+- Overflow: 5 characters too long
+
+**Location:** `nix/module.nix` - username generation logic in the NixOS module
+
+## Plan
+
+- [ ] Phase 1: Analyze current username generation logic in `nix/module.nix`
+- [ ] Phase 2: Design username truncation/hashing strategy that maintains uniqueness
+- [ ] Phase 3: Implement fix with proper testing for various domain lengths
+- [ ] Phase 4: Update documentation if username format changes
+
+## Progress
+
+### 2026-01-26 [Session 00:00]
+- Started: Issue created to track NixOS username length bug
+- Context: Discovered during deployment attempt to nixos-vps1
+- Impact: Blocks deployment of instances with longer domain names
+
+## Notes
+
+### Potential Solutions
+
+1. **Truncate domain**: Limit domain portion to fit within 31 chars
+   - Risk: Potential collisions with similar domains
+   
+2. **Hash domain**: Use short hash of domain instead of full name
+   - Example: `ngit-grasp-a7f2b3c4` (20 chars)
+   - Pro: Guaranteed uniqueness, always fits
+   - Con: Less human-readable
+   
+3. **Hybrid approach**: Use truncated domain + short hash
+   - Example: `ngit-ngit-danc-a7f2` (20 chars)
+   - Pro: Some readability, guaranteed uniqueness
+   - Con: More complex logic
+
+4. **Fixed prefix**: Use shorter prefix than `ngit-grasp-`
+   - Example: `ngrasp-{domain}` or `ng-{domain}`
+   - Pro: Simple, more space for domain
+   - Con: Still can overflow with long domains
+
+### Related Files
+
+- `nix/module.nix` - NixOS module with username generation
+- `docs/reference/configuration.md` - May need updates if format changes
+- Deployment configs using the module
+
+### Testing Considerations
+
+- Test with various domain lengths (short, medium, long)
+- Verify uniqueness across multiple instances
+- Check that existing deployments aren't broken by changes
+- Validate username format meets Linux requirements (alphanumeric, hyphens, no leading digits)