xavier/nixos-infra
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
a3172f477f507b0437518e7b9b205c50ab47b2b7
nixos-infra/README.md
T

315 lines
15 KiB
Markdown
Raw Blame History

# 🏗️ **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. |
| **Servers named by service, not by application** | Indicate what the machine does (git01 = Git forge) rather than the software (Gitea). Allows changing the underlying app without renaming. | Hosts under `hosts/servers/<service>01` (e.g. `git01`, `pass01`, `dns01`). |
| **`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)
│ │ ├── hyper01/ # Hypervisor 1
│ │ │ └── configuration.nix
│ │ ├── hyper02/ # Hypervisor 2
│ │ │ └── configuration.nix
│ │ ├── dns01/ # LXC container for DNS (master)
│ │ │ └── configuration.nix
│ │ ├── dns02/ # LXC container for DNS (slave)
│ │ │ └── configuration.nix
│ │ ├── git01/ # LXC container for Git forge (e.g. Gitea)
│ │ │ └── configuration.nix
│ │ ├── pass01/ # LXC container for password manager (e.g. 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 |
| ----------| --------------------| -------------| ------| ------------|
| hyper01 | Hypervisor | Proxmox | | |
| hyper02 | Hypervisor | Proxmox | | |
| dns01 | LXC Container | DNS | | |
| git01 | LXC Container | Git forge | | |
| pass01 | LXC Container | Password mgr| | |
| rp01 | LXC Container | Reverse proxy| | |
| 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`.
- **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** :
- **Servers**: Name by service, not by application (e.g., `git01`, `pass01`, `dns01`).
- **Workstations**: Use descriptive hostnames (e.g., `sting`, `gaia`).
- **Hypervisors**: Prefix with `hyper` (e.g., `hyper01`, `hyper02`).
- **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)
---
Reference in New Issue View Git Blame Copy Permalink