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. 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*. 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.<name>`, 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 support
- [ ] `site` - Static site hosting
- [x] `fail2ban` - IP moderation
- [x] `forgejo` - Code forge
- [ ] `mail` - Mail server
- [ ] `cachix` - Nix build caching
- [ ] `backup` - Automated backup system

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

Each deployment module is exposed as `nixosModules.deploy-<name>`. 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/`, 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!

### Flake-Based Configuration

Add this repository as a flake input:

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

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; [
    # Deployment
    deploy-rpi5
    # Modules
    forgejo
    ssh
  ];

  # Required module option
  aether.domain = "...";
}
```

For a more complete example of how to use Aether modules, my personal server
config can be found in the `aether/` directory.

[^1]: Adapted from
      [Book II.1](http://classics.mit.edu/Aristotle/heavens.2.ii.html).