docs: rewrite README
This commit is contained in:
parent
c409cde8f2
commit
8ef4845300
GPG key ID:
6CB106C25E86A9F7
88
README.md
88
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.<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 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-<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/`.
|
||||
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.<name>` and deployments
|
||||
under `nixosModules.deploy-<name>`. 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).
|
||||
|
|
|
|||
Loading…
Reference in a new issue