# NixOS Configuration

My personal Nix and NixOS configuration for reproducible, declarative systems and environments across multiple hosts.
This is a personal configuration with limited applicability to others, though some patterns may be useful for reference.
Common self-hosting services have been extracted to a separate project, [Eilean](https://github.com/RyanGibb/eilean-nix).

## Usage

### NixOS

See the [NixOS manual](https://nixos.org/manual/nixos/stable/#ch-installation) for how to install NixOS.

1. Clone this repository to `/etc/nixos/` on a NixOS system.
2. Set up the host configuration in `/etc/nixos/hosts/<hostname>/`.
3. Deploy the host with `nixos-rebuild switch`.

### Remote Deployment

[`deploy-rs`](https://github.com/serokell/deploy-rs) can be used to update remote hosts via SSH with `deploy .#hostname`.

### Home Manager

For non-NixOS systems, you can use Home Manager standalone:

1. Install [Nix](https://nixos.org/download/) and [enable flakes](https://nixos.wiki/wiki/flakes#Other_Distros.2C_without_Home-Manager).
2. Clone this repository and follow the [Home Manager manual](https://nix-community.github.io/home-manager/index.xhtml#sec-install-standalone).
3. Deploy the profile with `home-manager switch`.

### Nix-on-Droid

See [upstream](https://github.com/nix-community/nix-on-droid/).

## Repository Structure

- [`flake.nix`](./flake.nix) - Entry point where inputs, outputs, and [overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays) are defined.
  The [`flake.lock`](./flake.lock) file locks these inputs for reproducibility.
- [`hosts/`](./hosts/) - Host-specific configurations where each subdirectory represents a separate machine.
  - Hosts are named after animals, following a rough naming scheme where,
    - Stationary hosts are mammals.
      - Servers are even-toed ungulates ([Artiodactyls](https://en.wikipedia.org/wiki/Artiodactyl)), e.g. the [Network-Attached Storage (NAS) server](https://ryan.freumh.org/nas.html) [`elephant`](./hosts/elephant).
      - SBCs are small mammals ([Eulipotyphla](https://en.wikipedia.org/wiki/Eulipotyphla)), e.g. the [Home Assistant](https://www.home-assistant.io/) server and [Zigbee](https://en.wikipedia.org/wiki/Zigbee) bridge [`shrew`](./hosts/shrew).
      - Desktops are carnivores ([Carnivora](https://en.wikipedia.org/wiki/Carnivora)), e.g. the tower PC [`vulpine`](./hosts/vulpine).
    - Mobile (battery powered) hosts are reptiles, e.g. the laptop [`gecko`](./hosts/gecko).
    - Virtual hosts are birds, e.g. the virtual private server (VPS) [`owl`](./hosts/owl).
    - Work-associated hosts are aquatic, e.g. the VPSs for [Eon](https://github.com/RyanGibb/eon) experiments [`duck`](./hosts/duck), and running the [EEG](https://www.cst.cam.ac.uk/research/eeg) infrastructure including using the federated [Shibboleth](https://www.shibboleth.net/) identity server to provision [Matrix](https://matrix.org/) accounts [`swan`](./hosts/swan).
    - [`barnacle`](./hosts/barnacle/default.nix) builds an ISO image that can be written to media like a USB flash drive to create a read-only live USB that can be booted to provide the custom environment on all my other hosts and used to, for example, install an operating system, with the [`install.sh`](./hosts/barnacle/install.sh) script.
  - Each host directory typically contains,
    - `default.nix` - Main configuration entry point that imports other modules.
    - `hardware-configuration.nix` - Hardware-specific configuration generated by `nixos-generate-config`.
    - `minimal.nix` - A minimal configuration that can be useful when updating with insufficient disk space.
      The minimal configuration can be build, the `default.nix` system garbage collected, and then the updated configuration built.
      Note this precludes trivial rollback.
    - Other modules separating functionality, such as `services.nix`.
- [`modules/`](./modules/) - NixOS modules of common functionality extracted into modular components which can be enabled by host configurations.
- [`pkgs/`](./pkgs/) - Custom package definitions for packages not available in nixpkgs or requiring modifications.
- [`home/`](./home/) - Home-manager NixOS modules configurations.
- [`secrets/`](./secrets/) - Encrypted secrets managed by agenix.
- [`scripts/`](./scripts/) - Miscellaneous scripts.
- [`nix-on-droid/`](./nix-on-droid/) - [Nix-on-Droid](./#nix-on-droid) configuration.

## Managing Secrets

Secrets are managed using [agenix](https://github.com/ryantm/agenix).
To add a new secret, update [secrets.nix](./secrets/secrets.nix) and run `cd secrets && agenix -e <secret-name>.age`.
To update an existing secret you need only do the latter.