From 8ef4845300d07c6ea7aa7bbc5903f29ae1465afc Mon Sep 17 00:00:00 2001 From: Kiana Sheibani Date: Fri, 22 Nov 2024 18:41:33 -0500 Subject: [PATCH] docs: rewrite README --- README.md | 88 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 980cb53..e1be651 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,40 @@ # *Aἰθήρ* -> [*Aither*] as a whole neither came into being nor admits of destruction, -> but is one and eternal, with no end or beginning of its total -> duration, containing and embracing in itself the infinity of time ... +> [*Aither*] as a whole neither came into being nor admits of destruction, but +> is one and eternal, with no end or beginning of its total duration, containing +> and embracing in itself the infinity of time ... > > — Aristotle, *On the Heavens* [^1] Aether is a fully automated web server configured via **pure** and -**declarative** package management, powered by [NixOS](https://nixos.org). -This allows for all aspects of the server's operation, including config files, +**declarative** package management, powered by [NixOS](https://nixos.org). This +allows for all aspects of the server's operation, including config files, software dependencies, and site content to be deployed and provisioned automatically. -In short, it's my personal web server. +In short, it's my personal web server. It's also a NixOS codebase to support +that server, designed for generic use in other configurations. ## Modules -As with all good NixOS configurations, Aether is split into *modules* that -each provide different functionality. These are stored in the `modules/` directory. +As with all good NixOS configurations, Aether is split into *modules*. Each is +stored as a subdirectory of the `modules/` directory and defines an specific +function of the server. + +Modules are publicly exposed by this flake as `nixosModules.`, and can be +imported to activate their functionality. Any number of modules can be imported +independently, and the special `nixosModules.all` flake output can be used to +import every module at once. + +Some modules have options that can be used to configure their effects. If a +module has options, they can be found in the `options.nix` file inside the +module directory. More general options used by multiple modules are documented +in `modules/options.nix`. ### Module Checklist - [x] `basic` - Basic Internet support -- [x] `ssh` - SSH configuration +- [x] `ssh` - SSH support - [ ] `site` - Static site hosting - [x] `fail2ban` - IP moderation - [x] `forgejo` - Code forge @@ -33,19 +45,29 @@ each provide different functionality. These are stored in the `modules/` directo ## Deployment Aether is designed to separate individual machine details from the abstract -specification of the system, allowing for its code to be used for many -different types of system. This is handled using *deployments* in the -`deploy/` directory. +specification of the system, allowing for its code to be used for many different +types of system. This is handled using *deployments* in the `deploy/` directory. + +Each deployment module is exposed as `nixosModules.deploy-`. Only one +deployment should be imported; if Aether detects that more than one is imported, +it will prevent the configuration from building. Currently, I deploy Aether physically to a [Raspberry Pi 5](https://wiki.nixos.org/wiki/NixOS_on_ARM/Raspberry_Pi_5) running a [modified UEFI bootloader](https://github.com/worproject/rpi5-uefi) -to provide Linux support. The NixOS code for this can be found in `deploy/rpi5/`. +to provide Linux support. The NixOS code for this can be found in +`deploy/rpi5/`, and it is exposed as `nixosModules.deploy-rpi5`. + +> [!IMPORTANT] A complete rewrite of the deployment system using +> [NixOps 4](https://github.com/nixops4/nixops4) is planned once that project is +> stabilized. This may result in breaking changes to Aether's public interface. ## External Usage -If you use NixOS and are interested in any of these modules, you can import -them for your own config! +If you use NixOS and are interested in any of these modules, you can import them +for your own config! + +### Flake-Based Configuration Add this repository as a flake input: @@ -55,13 +77,25 @@ Add this repository as a flake input: } ``` -Aether modules are then exposed under `nixosModules.` and deployments -under `nixosModules.deploy-`. You can activate a module by adding it -to your `imports`: +Aether's modules can then be accessed as flake outputs. In particular, the +`specialArgs` parameter can be used to expose the modules in your configuration: ``` nix +nixpkgs.lib.nixosSystem { + specialArgs = { + aether = aether.nixosModules; + }; + modules = [ + ./config.nix + ]; +} +``` + +``` nix +# -- config.nix -- +{ aether, ... }: { - imports = with aether.nixosModules; [ + imports = with aether; [ # Deployment deploy-rpi5 # Modules @@ -69,19 +103,13 @@ to your `imports`: ssh ]; - # Required by forgejo module + # Required module option aether.domain = "..."; } ``` -Any number of modules can be activated at once, and the special -`nixosModules.aether` output can be used to refer to every module at once. -Activating more than one deployment will cause issues, so that should be -avoided. +For a more complete example of how to use Aether modules, my personal server +config can be found in the `aether/` directory. -Some modules have options that can be used to configure their effects. If a -module has options, they can be found in the `options.nix` file inside the -module directory. More general options used by multiple modules are -documented in `modules/options.nix`. - -[^1]: Adapted from [Book II.1](http://classics.mit.edu/Aristotle/heavens.2.ii.html). +[^1]: Adapted from + [Book II.1](http://classics.mit.edu/Aristotle/heavens.2.ii.html).