🏗️ NixOS Infrastructure Project Canvas

Centralized NixOS configuration management project for Xavier Lagraula's infrastructure

📌 Context and Objectives

• Scope: Centralized management of NixOS configurations for a complete infrastructure (hypervisors, workstations, LXC containers, services).
• Environment:
  • One Proxmox hypervisor currently, a second one coming soon.
  • Several workstations (e.g., dev-xavier, mao-julien, office).
  • LXC Containers (on Proxmox) VE for infrastructure services (DNS, Gitea, Bitwarden, etc.) and applications.
  • 2 main users (Xavier, Frida) + system users (root, admin, guest).
• Hardware: ThinkCentre m710q (16 GB RAM, i3) with KDE 6.3.

Objectives

Objective	Description	Priority
Centralize configurations	A single Git repository for all machines.	⭐⭐⭐
Modularity	Reusable modules for services, machine types, and user profiles.	⭐⭐⭐
Automation	Scripts to deploy configurations to machines and containers.	⭐⭐⭐
Security	Secret management with sops-nix or agenix.	⭐⭐
Portability	Autonomous modules via callPackage.	⭐⭐
Maintenance	Clear documentation and simplified update processes.	⭐

---

🔍 Key Decisions

Decision	Justification	Impact
No flakes	Simplify onboarding and avoid a steep learning curve.	Configuration via configuration.nix + callPackage.
Modular structure	Separate configurations by machine type and service.	Clear and maintainable directory tree.
callPackage for modules	Make modules autonomous, portable, and reusable.	Each module is an independent Nix package.
Separation of user-profiles/ and users/	Distinguish generic roles (e.g., admin) from concrete users (e.g., xavier).	Flexibility to apply profiles to multiple users.
deploy.sh script	Automate deployment on existing machines.	Clone/update the repo + nixos-rebuild switch.
create-lxc-nixos.sh script	Automate the creation of NixOS LXC containers on Proxmox.	Ready-to-use container with initial configuration.
Initial configuration (initial-configuration.nix)	Prepare an LXC container so it can update itself via Git.	Self-sufficient containers.
Secret management with agenix	Encrypt secrets (passwords, keys) for secure storage.	Enhanced security for sensitive data.
Unprivileged LXC containers (--unprivileged 0)	NixOS requires privileges to function correctly in LXC.	Functional containers with NixOS.
IPv4, IPv6, VLAN support	Final target is IPv6-first, or even IPv6-only.	IP plan management to be designed.

---

📂 File Structure

Git Repository Structure

nixos-infra/
├── configuration.nix          # Main entry point
├── README.md
│
├── hosts/                      # Machine configurations
│   ├── servers/                # Servers (hypervisors, VMs, LXCs)
│   │   ├── pve01/            # Hypervisor 1
│   │   │   └── configuration.nix
│   │   ├── pve02/            # Hypervisor 2
│   │   │   └── configuration.nix
│   │   ├── dns01/              # LXC container for DNS (master)
│   │   │   └── configuration.nix
│   │   ├── dns02/              # LXC container for DNS (slave)
│   │   │   └── configuration.nix
│   │   ├── gitea01/            # LXC container for Gitea
│   │   │   └── configuration.nix
│   │   ├── vaultwarden/        # LXC container for Vaultwarden
│   │   │   └── configuration.nix
│   │   └── rp01/               # LXC container for reverse proxy
│   │       └── configuration.nix
│   │
│   └── workstations/           # Workstations
│       ├── sting/              # Xavier's station (admin, dev, audio)
│       │   └── configuration.nix
│       ├── PC-FRIDA/           # Frida's station (office)
│       │   └── configuration.nix
│       └── gaia/               # Xavier's laptop (audio)
│           └── configuration.nix
│
├── modules/                    # Autonomous modules
│   ├── machine-types/          # Machine types
│   │   ├── hypervisor.nix      # Module for hypervisors
│   │   ├── vm.nix              # Module for VMs
│   │   ├── lxc.nix             # Module for LXC containers
│   │   └── workstation.nix     # Module for workstations
│   │
│   ├── services/               # Services
│   │   ├── dns/
│   │   │   ├── default.nix     # Implementation
│   │   │   └── options.nix     # Exposed options
│   │   ├── gitea/
│   │   │   └── default.nix
│   │   ├── password-manager/
│   │   │   └── default.nix
│   │   ├── reverse-proxy/
│   │   │   └── default.nix
│   │   └── ...
│   │
│   └── user-profiles/          # User profiles (roles)
│       ├── admin.nix           # Administrator profile
│       ├── dev.nix             # Developer profile
│       ├── mao.nix             # Audio production profile
│       └── standard.nix        # Standard profile
│
├── users/                      # Specific users
│   ├── root/
│   │   └── configuration.nix
│   ├── xavier/
│   │   └── configuration.nix
│   ├── frida/
│   │   └── configuration.nix
│   └── guest/
│       └── configuration.nix
│
├── scripts/                    # Utility scripts
│   ├── deploy.sh               # Deployment for existing machines
│   ├── create-lxc-nixos.sh     # LXC container creation on Proxmox
│   └── initial-configuration.nix # Initial configuration for new containers
│
├── secrets/                    # Secrets (excluded from Git)
│   └── .gitignore
│
└── overlays/                   # Overlays for custom packages
    └── custom-pkgs.nix

---

---

🖥️ Machine Profiles and Services

Machine Profiles

Profile	Description	File	Usage
hypervisor	Common configuration for hypervisors (KVM, libvirtd, etc.).	modules/machine-types/hypervisor.nix	Proxmox hypervisors.
vm	Common configuration for virtual machines.	modules/machine-types/vm.nix	VMs under Proxmox.
lxc	Common configuration for LXC containers.	modules/machine-types/lxc.nix	LXC containers under Proxmox.
workstation	Common configuration for workstations.	modules/machine-types/workstation.nix	Development, audio production, office stations.

Profile	Description	File
admin	Administrator access (sudo, service management).	modules/user-profiles/admin.nix
dev	Development environment (tools, permissions).	modules/user-profiles/dev.nix
cam	Computer assisted music (cam).	modules/user-profiles/cam.nix
standard	Standard user profile (basic access).	modules/user-profiles/standard.nix

---

📋 Reference Tables

1. Machine List

Name	Machine Type	Services	IPv4	IPv6 Token
pve01	Hypervisor	Proxmox
pve02	Hypervisor	Proxmox
dns01	LXC Container	DNS
gitea01	LXC Container	Gitea
vault01	LXC Container	Vaultwarden
sting	Workstation
PC-FRIDA	Workstation

---

2. List of User Profiles

Name	Role
admin	Superuser
dev	Developer
standard	Web & Office
guest	Guest

---

3. User List

Name	Role	SSH Access
root	Superuser	❌
xavier	Main user	✅
frida	User	✅
guest	Guest	❌

---

4. User/Machine/Profile Mappings

User	Machine	Applied Profiles	Role
root	All	-	Superuser
xavier	All	admin	Development + administration
xavier	sting	admin, dev	Hypervisor management
frida	PC-FRIDA	standard	Development
guest	None	guest	Guest user
xavier	sting	admin, dev	Hypervisor management
frida	PC-FRIDA	standard	Development
guest	None	guest	Guest user

---

---

🔄 Deployment Workflow

For LXC containers (Proxmox)

1. Create the container :

• Use create-lxc-nixos.sh to create a container from the NixOS template.
• The script installs the initial configuration (initial-configuration.nix).

2. Deploy the final configuration :

• The deploy.sh script is executed automatically to apply the specific configuration to the container (e.g., hosts/servers/dns01/configuration.nix).

3. Update :

• git pull in /etc/nixos-infra + nixos-rebuild switch.

For workstations and hypervisors

1. Clone the repository :

    git clone https://github.com/xlagraula/nixos-infra.git /etc/nixos-infra
   

2. Link the configuration :

    ln -s /etc/nixos-infra/hosts/workstations/dev-xavier/configuration.nix /etc/nixos/configuration.nix
   

3. Apply the configuration :

    sudo nixos-rebuild switch
   

---

---

🔐 Secret Management

• Tool : agenix (recommended) or sops-nix.
• Process :
  1. Encrypt secrets with age :

   echo "my-secret" | age -r age1... -o secrets/bitwarden/password.age
  

  2. Integrate into the configuration :

   age.secrets.bitwarden-password = {
     path = ./secrets/bitwarden/password.age;
     mode = "600";
   };
  

  3. Never commit secrets in plain text (add secrets/ to .gitignore).

---

---

📅 Roadmap

Step	Description	Status	Priority
Test the NixOS LXC template	Verify that the template works under Proxmox.	⬜	⭐⭐⭐
Finalize create-lxc-nixos.sh	Test the creation of an LXC container.	⬜	⭐⭐⭐
Write the DNS module	Module for the DNS service (Bind).	⬜	⭐⭐⭐
Configure agenix	Encrypt the first secrets.	⬜	⭐⭐
Document the process	README.md to explain deployment.	⬜	⭐⭐
Automate with Ansible	Playbook to create multiple containers.	⬜	⭐
Integrate CI/CD	Test configurations before deployment.	⬜	⭐

---

---

💡 Notes and Best Practices

• Naming :
  • Use explicit names for machines (e.g., dns01, gitea01).
  • For LXC containers, prefer short and descriptive names.
• Security :
  • Disable root SSH access once deployment is complete.
  • Use SSH keys for authentication.
• Maintenance :
  • Update nixpkgs regularly (nix-channel --update).
  • Document changes in the CHANGELOG.md.
• Backups :
  • Backup configurations (/etc/nixos-infra) and secrets (secrets/).
  • For LXC containers under Proxmox, use Proxmox backups.

---

---

📚 Useful Resources

• NixOS Manual
• Nix Flakes (for future reference)
• Agenix for secrets
• Proxmox + LXC Documentation
• Example NixOS Infrastructure Repository

---