The supervised Go-to-Rust cutover is documented in 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

nix develop

Or install direnv to automatically get the devshell going.

This provides agenix and dnscontrol.

Managing Secrets

Secrets are managed with agenix. If you're unfamiliar with agenix, here is a good introduction.

Adding a New User's Key

Get their SSH public key (ed25519 or RSA)
Add it to secrets/secrets.nix in the appropriate key list

Re-encrypt all secrets:

cd secrets
agenix -e pds-env.age  # repeat for each secret

Creating/Editing Secrets

cd secrets
agenix -e pds-env.age

This opens your $EDITOR with the decrypted content. Save and close to re-encrypt.

Adding New Secrets

Add the secret to secrets/secrets.nix:
```
"new-secret.age".publicKeys = allKeys;
```
Create it:
```
cd secrets
agenix -e new-secret.age
```

Reference it in your NixOS config:

age.secrets.new-secret = {
  file = ../../secrets/new-secret.age;
  mode = "0400";
  owner = "service-user";
};

Deployment

Manual Deployment

From the server:

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:

Pull latest git changes
Run nix flake update
Build, activate, and health-check the new configuration
Commit and push flake.lock only after successful validation

Setup required:

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

sudo systemctl start auto-update

Check status:

sudo systemctl status auto-update
sudo journalctl -u auto-update

Development

Updating Flake Inputs

nix flake update

Testing Changes Locally

nixos-rebuild build --flake .#asusmini

DNS Management

DNS is managed with dnscontrol (available in dev shell). See 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