≪ 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 08:21] – 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 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 112: Line 142:
 #### Installing NixOS Quickly #### Installing NixOS Quickly
  
-Install NixOS directly by flashing it onto the hard drive using a SATA-to-USB +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. 
-or NVME-to-USB adapter. This will save you the trouble of having to transfer + 
-this repository over to the machine's live environment. These two commands +If you're inside the Nix develop environment, you can run: 
-will be very handy:+ 
 +```sh 
 +sudo disko-install \ 
 +  --mode format \ 
 +  --disk '<machine-disk>' '/dev/sdXY' \ 
 +  --flake "path://$PWD#<machine>" 
 +``` 
 + 
 +> **Note:** Use `path://$PWD` rather than `.` since `disko` has buggy Flake subdirectory support. 
 + 
 +> **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. 
 + 
 +If you're doing this from the NixOS live environment, and you want to install directly into the same machine, you can run:
  
 ```sh ```sh
Line 138: Line 180:
 ### Adding Bitwarden Secrets to a Machine ### Adding Bitwarden Secrets to a Machine
  
-If you're here, chances are you're already added into the administration group +Moved to [a separate playbook](/infrastructure/playbook/bitwarden-sops-nix).
-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 +
-$ cat .envrc +
-export BITWARDENCLI_APPDATA_DIR="$HOME/.config/bitwarden-dma-space" +
-... +
-``` +
- +
-Then, you'll need to obtain your Bitwarden API key. For this, follow the +
-[Bitwarden official documentation](https://bitwarden.com/help/cli/#using-an-api-key). +
-You may choose to add these as environment variables as well: +
- +
-```sh +
-$ 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 +
-and return a session key which contains the unlocked vault. You may choose to +
-add this key as well: +
- +
-```sh +
-$ cat .envrc +
-export BW_SESSION="your-session-key" +
-``` +
- +
-Doing this is not recommended however, since it exposes your session key (and +
-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 +
- +
-Head to the Bitwarden web app or extension, then navigate to the **Server +
-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 +
-field with the name being the SOPS path you want to store the secret at relative +
-to `/run/secrets`. +
- +
-For example, do add a secret at `/run/secrets/authentik/secret_key`, you would +
-add a new hidden field with the name `authentik/secret_key` and the value being +
-the value of the secret. +
- +
-#### Onboard the Machine to SOPS +
- +
-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 +
-[direnv]: https://direnv.net/ +
-[sops-nix]: https://github.com/Mic92/sops-nix+