docs: add a getting-started page for the nixos flake, module import and required options
This commit is contained in:
atlas
parent
1e2e93da59
commit
86ec5d12c3
1 changed files with 99 additions and 1 deletions
95
docs/getting-started/nixos.md
Normal file
95
docs/getting-started/nixos.md
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
# Adding hyperhive to a NixOS flake
|
||||
|
||||
How to take a NixOS machine you already manage with a flake to the point
|
||||
where `nixos-rebuild switch` brings hyperhive up. After the switch, continue
|
||||
with [`setup.md`](setup.md) for the steps that stay by hand.
|
||||
|
||||
## 1 · Add the flake input
|
||||
|
||||
In your host's `flake.nix`, add hyperhive next to nixpkgs:
|
||||
|
||||
```nix
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
|
||||
hyperhive.url = "git+https://forge.darkest.space/hyperhive/hyperhive";
|
||||
};
|
||||
```
|
||||
|
||||
Add `hyperhive` to the arguments of `outputs` too, so the next step can
|
||||
reach it.
|
||||
|
||||
## 2 · Import the module
|
||||
|
||||
Import `hyperhive.nixosModules.default`. It's the whole host stack in one
|
||||
import: the hive (`hive-c0re` and its gateway, bridge and resolver) and every
|
||||
swarm service. It also wires in hyperhive's own packages, so you set no
|
||||
package options.
|
||||
|
||||
Importing `default` turns nothing on. Every service stays off until you
|
||||
enable it, and a host that imports it and enables nothing evaluates without
|
||||
any of the options below.
|
||||
|
||||
```nix
|
||||
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
|
||||
system = "x86_64-linux";
|
||||
modules = [
|
||||
hyperhive.nixosModules.default
|
||||
{ services.hyperhive = { /* step 3 */ }; }
|
||||
];
|
||||
};
|
||||
```
|
||||
|
||||
`claude-code` is unfree. Hyperhive scopes the allowance to itself, so you
|
||||
don't set `allowUnfree`.
|
||||
|
||||
## 3 · Set the required options
|
||||
|
||||
All of these live under `services.hyperhive`. Evaluation fails with a message
|
||||
naming the option when one is missing. None of them has a default, because a
|
||||
guessed value here is a wrong hostname that evaluates cleanly and deploys.
|
||||
|
||||
| option | what it does | without it |
|
||||
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
|
||||
| `deploy.hive-controller.enable` | Runs a hive on this host: `hive-c0re`, which owns every agent container, plus the bridge and gateway for the agents. | No agents can run here. Leave it off on a host that only runs shared swarm services. |
|
||||
| `swarm.domain` | The swarm's DNS domain. Each hive lives in a sub-domain of it. Use the same value on every host of the swarm. | Eval fails on any host that runs a hyperhive service. |
|
||||
| `deploy.hive-controller.hiveName` | This hive's label inside the swarm, and the first part of its address, `<hiveName>.<swarm.domain>`. It's also the hive's identity in the secret store. | Eval fails on a host that runs a hive. |
|
||||
| `swarm.hives` | The directory of every hive in the swarm, this one included. Entries need no fields: each `domain` defaults to `<name>.<swarm.domain>`. Every host of the swarm shares one identical copy. | Eval fails, naming the missing entry for `hiveName`. |
|
||||
|
||||
An all-local swarm, with every shared service and the hive on this one box,
|
||||
adds one switch:
|
||||
|
||||
| option | what it does |
|
||||
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `deploy.singleHostSwarm` | Turns on the shared swarm services, the swarm controller, and `/etc/hosts` entries so the swarm's names resolve on the box itself. Leave it off if the services run on other hosts. |
|
||||
|
||||
The smallest working config, as in the README's
|
||||
[all-local quick start](../../README.md#quick-start-an-all-local-swarm):
|
||||
|
||||
```nix
|
||||
services.hyperhive = {
|
||||
deploy.singleHostSwarm = true;
|
||||
deploy.hive-controller.enable = true;
|
||||
swarm.domain = "hive.example";
|
||||
deploy.hive-controller.hiveName = "pr1ma";
|
||||
swarm.hives.pr1ma = { };
|
||||
};
|
||||
```
|
||||
|
||||
Run `nixos-rebuild switch --flake .#my-host`. The swarm UI then answers at
|
||||
`https://<swarm.domain>/`.
|
||||
|
||||
## Everything else is optional
|
||||
|
||||
Leave the other options at their defaults until you need them:
|
||||
|
||||
- Spreading a swarm over more than one host, and the credentials a split swarm
|
||||
needs: [`swarm/README.md`](../swarm/README.md) and
|
||||
[`swarm/credentials.md`](../swarm/credentials.md).
|
||||
- Every option, with its type and default:
|
||||
[the options reference](https://hyperhive.darkest.space/options/).
|
||||
- The secret store's seal and the granter: [`swarm/bao.md`](../swarm/bao.md).
|
||||
|
||||
## Next
|
||||
|
||||
[`setup.md`](setup.md): initialize the secret store, create your SSO account
|
||||
and your first agents.
|
||||
Loading…
Reference in a new issue