117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# *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).
|