181 lines
4.9 KiB
Markdown
181 lines
4.9 KiB
Markdown
# Commons Computing NixOS Configuration
|
|
|
|
Infrastructure-as-code for Commons Computing's ATProto services.
|
|
|
|
## Services
|
|
|
|
This flake manages the following services on `asusmini`:
|
|
|
|
- **PDS** (Personal Data Server) - `pds.commonscomputer.com:5556`
|
|
- **Tangled Knot** (Rust Git forge) - HTTP `5555`, Git SSH `2223`
|
|
- **Tangled Spindle** (CI runner) - `spindle.commonscomputer.com:6555`
|
|
|
|
All services are proxied through Caddy with automatic HTTPS.
|
|
|
|
The supervised Go-to-Rust cutover is documented in [TANGLED-MIGRATION.md](TANGLED-MIGRATION.md).
|
|
Do not activate the new configuration before following its backup and migration steps.
|
|
Administrative SSH stays on port 22; Git SSH on 2223 needs explicit client routing.
|
|
|
|
## Setup
|
|
|
|
### Prerequisites
|
|
|
|
```bash
|
|
nix develop
|
|
```
|
|
|
|
Or install direnv to automatically get the devshell going.
|
|
|
|
This provides `agenix` and `dnscontrol`.
|
|
|
|
### Managing Secrets
|
|
|
|
Secrets are managed with [agenix](https://github.com/ryantm/agenix). If you're unfamiliar with agenix, [here](https://www.splitbrain.org/blog/2025-07/27-agenix) is a good introduction.
|
|
|
|
#### Adding a New User's Key
|
|
|
|
1. Get their SSH public key (ed25519 or RSA)
|
|
2. Add it to `secrets/secrets.nix` in the appropriate key list
|
|
3. Re-encrypt all secrets:
|
|
```bash
|
|
cd secrets
|
|
agenix -e pds-env.age # repeat for each secret
|
|
```
|
|
|
|
#### Creating/Editing Secrets
|
|
|
|
```bash
|
|
cd secrets
|
|
agenix -e pds-env.age
|
|
```
|
|
|
|
This opens your `$EDITOR` with the decrypted content. Save and close to re-encrypt.
|
|
|
|
#### Adding New Secrets
|
|
|
|
1. Add the secret to `secrets/secrets.nix`:
|
|
```nix
|
|
"new-secret.age".publicKeys = allKeys;
|
|
```
|
|
2. Create it:
|
|
```bash
|
|
cd secrets
|
|
agenix -e new-secret.age
|
|
```
|
|
3. Reference it in your NixOS config:
|
|
```nix
|
|
age.secrets.new-secret = {
|
|
file = ../../secrets/new-secret.age;
|
|
mode = "0400";
|
|
owner = "service-user";
|
|
};
|
|
```
|
|
|
|
### Deployment
|
|
|
|
#### Manual Deployment
|
|
|
|
From the server:
|
|
```bash
|
|
cd /etc/nixos # or wherever this repo is cloned
|
|
git pull
|
|
sudo nixos-rebuild switch --flake .#asusmini
|
|
```
|
|
|
|
#### Auto-Update
|
|
|
|
The timer is gated until `scripts/upgrade-knot.sh` completes the Tangled
|
|
migration and smoke tests. It then resumes weekly updates, including Tangled.
|
|
The initial lock selects tested v1.20.0 packages with their own dependencies
|
|
so the cutover reuses copied binaries without recompilation.
|
|
|
|
A systemd timer runs weekly to:
|
|
1. Pull latest git changes
|
|
2. Run `nix flake update`
|
|
3. Build, activate, and health-check the new configuration
|
|
4. Commit and push flake.lock only after successful validation
|
|
|
|
**Setup required:**
|
|
```bash
|
|
# On the server, generate SSH key for git push
|
|
ssh-keygen -t ed25519 -f /root/.ssh/commons-nix-deploy -N ""
|
|
cat /root/.ssh/commons-nix-deploy.pub
|
|
# Add the public key as a deploy key with write access to the GitHub repo
|
|
|
|
# Configure git to use the key
|
|
cat >> /root/.ssh/config <<EOF
|
|
Host github.com
|
|
IdentityFile /root/.ssh/commons-nix-deploy
|
|
EOF
|
|
```
|
|
|
|
**Manual trigger:**
|
|
```bash
|
|
sudo systemctl start auto-update
|
|
```
|
|
|
|
**Check status:**
|
|
```bash
|
|
sudo systemctl status auto-update
|
|
sudo journalctl -u auto-update
|
|
```
|
|
|
|
## Development
|
|
|
|
### Updating Flake Inputs
|
|
|
|
```bash
|
|
nix flake update
|
|
```
|
|
|
|
### Testing Changes Locally
|
|
|
|
```bash
|
|
nixos-rebuild build --flake .#asusmini
|
|
```
|
|
|
|
### DNS Management
|
|
|
|
DNS is managed with dnscontrol (available in dev shell). See [dns/README.md](dns/README.md) for details.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ Internet (HTTPS) │
|
|
└────────────────┬────────────────────────┘
|
|
│
|
|
┌───────▼────────┐
|
|
│ Caddy (80/443)│
|
|
└───────┬────────┘
|
|
│
|
|
┌───────────┼───────────────┐
|
|
│ │ │
|
|
┌────▼─────┐ ┌──▼────┐ ┌───────▼──────┐
|
|
│PDS (5556)│ │Knot │ │Spindle (6555)│
|
|
│ │ │(5555) │ │ │
|
|
└──────────┘ └───────┘ └──────────────┘
|
|
```
|
|
|
|
|
|
## Key Files
|
|
|
|
- `flake.nix` - Main flake configuration
|
|
- `hosts/asusmini/` - Server-specific configuration
|
|
- `default.nix` - Base system config
|
|
- `atproto.nix` - ATProto service configs
|
|
- `hardware-configuration.nix` - Hardware-specific settings
|
|
- `secrets/secrets.nix` - Secret encryption keys
|
|
- `secrets/*.age` - Encrypted secrets
|
|
|
|
## Admin Contact
|
|
|
|
Primary admin: Anish
|
|
|
|
## Notes
|
|
|
|
- System uses NixOS unstable
|
|
- All services run under dedicated system users
|
|
- Secrets are encrypted at rest and decrypted on boot to `/run/agenix/`
|
|
- Keep at least one personal SSH key in addition to the system key for emergency access
|