ngit-grasp/2909-nixos-username-length-limit.md

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)