≪ View Page

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
infrastructure:nixos-boxes [2025/12/21 07:46] – diamondinfrastructure:nixos-boxes [2026/01/08 09:12] (current) – move bitwarden-sops out into a page diamond
Line 4: Line 4:
  
 As the name describes, these boxes run NixOS, but they're also managed using GitOps. Their code lives in [dma/infra/nixos](https://codeberg.org/dma/infra/tree/main/nixos). Any commits pushed to `main` will automatically get deployed within 10 seconds to all machines. As the name describes, these boxes run NixOS, but they're also managed using GitOps. Their code lives in [dma/infra/nixos](https://codeberg.org/dma/infra/tree/main/nixos). Any commits pushed to `main` will automatically get deployed within 10 seconds to all machines.
 +
 +## Pages
 +
 +```dokuwiki
 +<catlist infrastructure:nixos-boxes: -noHead>
 +```
  
 ## Structure ## Structure
Line 48: Line 54:
 ``` ```
  
-> [!TIP]+> **Tip:**
 > >
 > You may have a need to save secret environment variables such as Bitwarden > You may have a need to save secret environment variables such as Bitwarden
Line 54: Line 60:
 > local gitignore by running: > local gitignore by running:
 > >
-> ```sh +> `echo ".envrc" >> "$(git rev-parse --show-toplevel)/.git/info/exclude"` 
-> echo ".envrc" >> "$(git rev-parse --show-toplevel)/.git/info/exclude" + 
-> ```+## Deployment 
 + 
 +All NixOS boxes are automatically deployed with GitOps practices. The following diagram briefly explains its architecture: 
 + 
 +```dokuwiki 
 +<div centeralign> 
 +<mermaid> 
 +    flowchart TD 
 +        codeberg[dma/infra @ main] 
 +        codeberg --[pull every 15s]--> comin_a 
 +        codeberg --[pull every 15s]--> comin_b 
 +        subgraph nixos_machine_a[NixOS Machine A] 
 +            nixos_rebuild_a[nixos-rebuild] 
 +            comin_a[comin.service] --> nixos_rebuild_a 
 +        end 
 +        subgraph nixos_machine_b[NixOS Machine B] 
 +            nixos_rebuild_b[nixos-rebuild] 
 +            comin_b[comin.service] --> nixos_rebuild_b 
 +        end 
 +</mermaid> 
 +</div> 
 +``` 
 + 
 +Whenever a new commit is pushed to the `main` branch, all machines race to deploy this new commit. This way, we achieve GitOps without requiring an actual CI/CD pipeline, simplifying the deployment pipeline by a lot. 
 + 
 +To see how caught up the deployments are on the NixOS fleet, run `just watch`. This spawns a dashboard of machines and their commits which refreshes every 5 seconds. Use this immediately after pushing to comprehensively view how the machines are going along. 
 + 
 +### Testing Branches 
 + 
 +[comin](https://github.com/nlewo/comin), the GitOps tool we use, supports using testing branches to try out configurations without persisting them to the next reboot. 
 + 
 +To use this, simply push a new commit to a new `testing-{machine}` branch, where `{machine}` is the name of the machine. For example, a commit that updates `home-assistant-one`'s configuration would be pushed to `testing-home-assistant-one`. 
 + 
 +Once everything is tested to be working, you can simply `git checkout main` then `git rebase testing-{machine}` to add your new commits on top. Then, push to main as usual. 
  
 ## Common Operations ## Common Operations
Line 66: Line 106:
 just just
 ``` ```
- 
-A few notable recipes include: 
- 
-- `just deploy <machine>` - Deploy the given machine. Machines are assumed to 
-  have the hostname of `<machine>` but this may change in the future. 
-- `just ssh <machine>` - SSH into the given machine. Machine hostnames follow 
-  the above rule. 
-- `just sync-bitwarden-secrets <machine>` - Sync Bitwarden secrets for the given 
-  machine. See 
-  [Adding Bitwarden Secrets to a Machine](#adding-bitwarden-secrets-to-a-machine). 
  
 ## Playbooks ## Playbooks
Line 86: Line 116:
 machine, but rather the recommendations for setting it up: machine, but rather the recommendations for setting it up:
  
-- Create a `machines/<machine>/configuration.nix` manually. For most machines +#### Creating a configuration.nix
-  (especially common Thinkcentre models), it should be enough to just import +
-  `nixos-hardware` directly.+
  
-  After creating this file, add it to the local `flake.nix`, under +Create a `machines/<machine>/configuration.nix` manually. For most machines 
-  `.nixosConfigurations.<machine>`. **Use `self.lib.nixosSystem`** unless you +(especially common Thinkcentre models), it should be enough to just import 
-  have a good reason not to.+`nixos-hardware` directly.
  
-- Create a `machines/<machine>/disko.nix` containing the disk layout using +After creating this file, add it to the local `flake.nix`, under 
-  [disko][disko].+`.nixosConfigurations.<machine>`. **Use `self.lib.nixosSystem`** unless you 
 +have a good reason not to.
  
-  **It is strongly recommended to use full disk encryption via LUKS + Btrfs**, +#### Disk Partitioning
-  unless you are absolutely sure the machine will not store any secrets or run +
-  any secure workloads. You may refer to existing NixOS machines for disko +
-  examples.+
  
-  Don't forget to add the file to the local `flake.nix`, under +Create a `machines/<machine>/disko.nix` containing the disk layout using 
-  `.diskoConfigurations.<machine>` as well. Prefer `self.lib.diskoConfiguration` +[disko][disko].
-  for this.+
  
-- Install NixOS directly by flashing it onto the hard drive using a SATA-to-USB +**It is strongly recommended to use full disk encryption via LUKS + Btrfs**, 
-  or NVME-to-USB adapter. This will save you the trouble of having to transfer +unless you are absolutely sure the machine will not store any secrets or run 
-  this repository over to the machine's live environment. These two commands +any secure workloads. You may refer to existing NixOS machines for disko 
-  will be very handy:+examples.
  
-  ```sh +Don't forget to add the file to the local `flake.nix`, under 
-  nix run 'nixpkgs#disko' -- --mode destroy,format,mount --flake '.#<machine>' +`.diskoConfigurations.<machine>` as well. Prefer `self.lib.diskoConfiguration` 
-  nixos-install --no-channel-copy --flake '.#<machine>' +for this.
-  ```+
  
-- For convenience, import the few core modules: `network`, `sanity`, and `ssh`. +#### Installing NixOS Quickly
-  See existing `configuration.nix` files for reference.+
  
-- After installation, set up Secure Boot and TPM2 unlocking as soon as you can. +Install NixOS directly by flashing it onto the hard drive using a SATA-to-USB or NVME-to-USB adapter. This will save you the trouble of having to transfer this repository over to the machine's live environment.
-  The `secureboot` module should aid you in this process, but refer to +
-  [Lanzaboote][lanzaboote]'s existing documentation for more details: +
-  - [Prepare Your System](https://github.com/nix-community/lanzaboote/blob/master/docs/getting-started/prepare-your-system.md) +
-  - [Enable Secure Boot](https://github.com/nix-community/lanzaboote/blob/master/docs/getting-started/enable-secure-boot.md)+
  
-### Adding Bitwarden Secrets to a Machine +If you're inside the Nix develop environment, you can run:
- +
-If you're here, chances are you're already added into the administration group +
-for Bitwarden users. If not, please reach out to an existing administrator first +
-to be added before continuing. +
- +
-Before continuing, **it is strongly advised that you have [Nix][nix] and +
-[Direnv][direnv] installed**. This will allow you to store your Bitwarden +
-secrets much easier. +
- +
-#### Preparing the Bitwarden CLI +
- +
-First, set the `BITWARDENCLI_APPDATA_DIR` environment variable to prevent the +
-CLI from using or overriding your personal Bitwarden configuration. It is +
-strongly recommended to set this in `.envrc` so you don't forget:+
  
 ```sh ```sh
-$ cat .envrc +sudo disko-install \ 
-export BITWARDENCLI_APPDATA_DIR="$HOME/.config/bitwarden-dma-space" +  --mode format \ 
-...+  --disk '<machine-disk>' '/dev/sdXY' \ 
 +  --flake "path://$PWD#<machine>"
 ``` ```
  
-Then, you'll need to obtain your Bitwarden API key. For this, follow the +> **Note:** Use `path://$PWD` rather than `.` since `disko` has buggy Flake subdirectory support.
-[Bitwarden official documentation](https://bitwarden.com/help/cli/#using-an-api-key). +
-You may choose to add these as environment variables as well:+
  
-```sh +> **Note:** This doesn't set the root password. If you're one of the infra admins, you should have your SSH keys inside `./modules/ssh/public_keys.txt` and SSH directly into the box's LAN IP to continue provisioning.
-$ cat .envrc +
-export BW_CLIENTID="your-client-id" +
-export BW_CLIENTSECRET="your-client-secret" +
-```+
  
-Now, proceed to run `bw unlock`. This will prompt you for your master password +If you're doing this from the NixOS live environment, and you want to install directly into the same machine, you can run:
-and return a session key which contains the unlocked vault. You may choose to +
-add this key as well:+
  
 ```sh ```sh
-$ cat .envrc +nix run 'nixpkgs#disko' -- --mode destroy,format,mount --flake '.#<machine>' 
-export BW_SESSION="your-session-key"+nixos-install --no-channel-copy --flake '.#<machine>'
 ``` ```
  
-Doing this is not recommended however, since it exposes your session key (and +#### Re-using Modules
-therefore essentially your entire vault) in plaintext on disk, and the key will +
-never expire. Instead, prefer exporting it manually in the current shell +
-session.+
  
-#### Adding a Secret+For convenience, import the few core modules: `network`, `sanity`, and `ssh`. 
 +See existing `configuration.nix` files for reference.
  
-Head to the Bitwarden web app or extension, then navigate to the **Server +#### Secure Boot
-Credentials/NixOS Machines** collection. Here, you will find 1 secret item per +
-machine.+
  
-To add a secret to a machine, open the corresponding item, then add a new hidden +After installation, set up Secure Boot and TPM2 unlocking as soon as you can. 
-field with the name being the SOPS path you want to store the secret at relative +The `secureboot` module should aid you in this process, but refer to 
-to `/run/secrets`.+[Lanzaboote][lanzaboote]'s existing documentation for more details:
  
-For example, do add a secret at `/run/secrets/authentik/secret_key`, you would +- [Prepare Your System](https://github.com/nix-community/lanzaboote/blob/master/docs/getting-started/prepare-your-system.md) 
-add a new hidden field with the name `authentik/secret_key` and the value being +- [Enable Secure Boot](https://github.com/nix-community/lanzaboote/blob/master/docs/getting-started/enable-secure-boot.md)
-the value of the secret.+
  
-#### Onboard the Machine to SOPS +### Adding Bitwarden Secrets to a Machine
- +
-This step only needs to be done once per machine. To validate that a machine is +
-ready for SOPS, ensure it has the `sops.*` options in its `configuration.nix`. +
- +
-If not, start by referring to +
-[sops-nix's step 3 of Usage Examples](https://github.com/Mic92/sops-nix?tab=readme-ov-file#usage-example). +
-Essentially, you need to do the following steps: +
- +
-1. Grab the machine's age key from its host SSH key using `ssh-to-age`. +
-2. Add it to `vars.nix` under `<machine>.sops.hostPubKey`. +
-3. Find the Bitwarden secret ID. There are 2 ways to do this: +
-   - Using `just get-bitwarden-secret-id <machine>`, which will match a secret +
-     with the exact name given, but this is not guaranteed to be in the correct +
-     collection. +
-   - Using the `&itemId=<UUID>` value when you click on the secret item in the +
-     Bitwarden web app. +
-4. Add it to `vars.nix` under `<machine>.sops.bitwardenSecretID`. +
- +
-Then, add the boilerplate snippet to the machine's `configuration.nix`: +
- +
-```nix +
-{ +
-  sops = { +
-    defaultSopsFile = ./secrets.bitwarden.yaml; +
-    age.sshKeyPaths = [ "/etc/ssh/ssh_host_ed25519_key" ]; +
-  }; +
-} +
-``` +
- +
-#### Synchronizing Secrets +
- +
-First, make sure that the local Bitwarden vault is up to date by running +
-`bw sync`. +
- +
-Then, run `just sync-bitwarden-secrets <machine>` to synchronize the secrets +
-from Bitwarden to the `./machines/<machine>/secrets.bitwarden.yaml` file. The +
-SOPS file will automatically be generated with the host SSH key being the only +
-decrypting recipient. +
- +
-Having more than just the host's recipient key is not recommended. Instead, +
-prefer regenerating the secret file from source Bitwarden if needed. This way, +
-the secrets are always up to date with Bitwarden. +
- +
-#### Using the Secrets +
- +
-You may use the secrets in your machine like any other [sops-nix][sops-nix] +
-secrets. For example: +
- +
-```nix +
-sops.secrets."authentik/secret_key" = { +
-  owner = "authentik"; +
-}; +
-``` +
- +
-This will place the secret at `/run/secrets/authentik/secret_key` with the owner +
-being the `authentik` user. +
- +
-Deploy the machine using `just deploy <machine>` to push the updated secrets to +
-the machine.+
  
-[nix]: https://nixos.org/download.html +Moved to [a separate playbook](/infrastructure/playbook/bitwarden-sops-nix).
-[direnv]: https://direnv.net/ +
-[sops-nix]: https://github.com/Mic92/sops-nix+