# 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