aether/README.md

# *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 ...
>
> — 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,
software dependencies, and site content to be deployed and provisioned
automatically.

In short, it's my personal web server.

## Modules

As with all good NixOS configurations, Aether is split into *modules* that
each provide different functionality. These are stored in the `modules/` directory.

### Module Checklist

- [x] `wireless` - WiFi support
- [x] `ssh` - SSH configuration
- [x] `forgejo` - Code forge
- [x] `fail2ban` - IP moderation
- [ ] `site` - Personal website
- [ ] `mail` - Mail server
- [ ] `backup` - Automated backup system
- [ ] `cachix` - Nix build caching

## 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.

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/`.

## External Usage

If you use NixOS and are interested in any of these modules, you can import
them for your own config!

Add this repository as a flake input:

``` nix
{
  inputs.aether.url = "https://git.tokinanpa.dev/toki/aether/archive/main.tar.gz";
}
```

Aether modules are then exposed under `nixosModules.<name>` and deployments
under `nixosModules.deploy-<name>`. You can activate a module by adding it
to your `imports`:

``` nix
{
  imports = with aether.nixosModules; [
    # Deployment
    deploy-rpi5
    # Modules
    forgejo
    ssh
  ];

  # Required by forgejo module
  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.

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).