# 🏗️ **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** ```bash 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 :** ```bash git clone https://github.com/xlagraula/nixos-infra.git /etc/nixos-infra ``` 2. **Link the configuration :** ```bash ln -s /etc/nixos-infra/hosts/workstations/dev-xavier/configuration.nix /etc/nixos/configuration.nix ``` 3. **Apply the configuration :** ```bash sudo nixos-rebuild switch ``` --- --- ## **🔐 Secret Management** - **Tool** : `agenix` (recommended) or `sops-nix`. - **Process** : 1. Encrypt secrets with `age` : ```bash echo "my-secret" | age -r age1... -o secrets/bitwarden/password.age ``` 2. Integrate into the configuration : ```nix 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](https://nixos.org/manual/) - [Nix Flakes (for future reference)](https://nixos.wiki/wiki/Flakes) - [Agenix for secrets](https://github.com/ryantm/agenix) - [Proxmox + LXC Documentation](https://pve.proxmox.com/wiki/Linear_Container) - [Example NixOS Infrastructure Repository](https://github.com/NixOS/nixos-infrastructure) ---