Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,10 @@ just add-machine NAME # Onboard + bootstrap an already-reachable machine via S
`site.yml` runs roles in tagged phases. Notable wiring:

- `bitwarden` resolves `BW_SESSION` (env, `/tmp/bw_session`, or interactive unlock), runs `bw sync` with a 15s timeout, and sets a `bw_unlocked` host fact. All BW-using roles gate on `when: bw_unlocked | default(false)`.
- `kube` fetches `~/.kube/config` + `~/.talos/config` from Bitwarden — desktops only.
- the `kube` unit fetches `~/.kube/config` + `~/.talos/config` from Bitwarden — desktops only.
- `ssh_keys` round-trips per-machine ed25519 keys through Bitwarden, building cross-machine `authorized_keys`.

After the playbook, `just apply*` runs bash **units** (`units/`, via mise through `scripts/run-units.sh`; see [`docs/src/units.md`](docs/src/units.md)): `omp`, `chezmoi`, `atuin`, `shell-ai`. `home/` is the chezmoi source for shell, git, neovim and atuin config; `ssh_keys` remains an Ansible role.
After the playbook, `just apply*` runs bash **units** (`units/`, via mise through `scripts/run-units.sh`; see [`docs/src/units.md`](docs/src/units.md)): `chezmoi`, `fonts`, `omp`, `atuin`, `shell-ai`, `github`, `kube`, `forgejo-registry`. `home/` is the chezmoi source for shell, git, neovim and atuin config; `ssh_keys` remains an Ansible role.

Roles are conditional on inventory group (`desktop`, `server`, `vps`, `test_fleet`, `termux_hosts`; `llm` is dormant/commented out) and on `skip_*` flags / `machine_profile` in `host_vars/`. See [`docs/src/roles/`](docs/src/roles/) for the full reference.

Expand Down
2 changes: 1 addition & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
## Playbook

- **Role** — an Ansible role that configures one concern (e.g. `tailscale`, `proxy`, `ssh_keys`). The interface is `tasks/main.yml`; the implementation is templates, files, and handlers.
- **Unit** — an idempotent bash script in `units/` run in parallel by mise after the playbook (`omp`, `chezmoi`, `atuin`, `shell-ai`). A failing step does not stop the rest of the unit. See `docs/src/units.md`.
- **Unit** — an idempotent bash script in `units/` run in parallel by mise after the playbook (`chezmoi`, `fonts`, `omp`, `atuin`, `shell-ai`, `github`, `kube`, `forgejo-registry`). A failing step does not stop the rest of the unit. See `docs/src/units.md`.
- **Phase** — a logical grouping of roles in `site.yml` (Phase 1: system + packages, Phase 2: secrets + auth, Phase 3: desktop, Phase 4: services). Phases are documented in comments, not enforced by the playbook.
- **Tag** — an Ansible tag applied to roles so `just apply-tags <tag>` can target a subset.

Expand Down
8 changes: 4 additions & 4 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@

## Dotfiles

- [shell_fonts](roles/shell_fonts.md)
- [shell_fonts (unit)](roles/shell_fonts.md)
- [shell_dotfiles (chezmoi)](roles/shell_dotfiles.md)
- [shell_atuin (chezmoi + unit)](roles/shell_atuin.md)
- [shell_ai (unit)](roles/shell_ai.md)
Expand All @@ -74,10 +74,10 @@
- [bitwarden](roles/bitwarden.md)
- [ssh_keys](roles/ssh_keys.md)
- [ssh_mesh](roles/ssh_mesh.md)
- [github](roles/github.md)
- [github (unit)](roles/github.md)
- [tailscale](roles/tailscale.md)
- [kube](roles/kube.md)
- [forgejo_registry](roles/forgejo_registry.md)
- [kube (unit)](roles/kube.md)
- [forgejo_registry (unit)](roles/forgejo_registry.md)

## Desktop

Expand Down
12 changes: 4 additions & 8 deletions docs/src/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,15 +62,11 @@ Every role in `site.yml` carries one or more tags. Tags fall into two kinds: **p
| System + packages | `homebrew` | `packages`, `homebrew` |
| System + packages | `termux_packages` | `system`, `packages`, `termux` |
| System + packages | `bitwarden` | `secrets`, `bitwarden` |
| System + packages | `shell_fonts` | `dotfiles`, `shell`, `fonts` |
| System + packages | `omp` unit | `dotfiles`, `omp` |
| System + packages | `hive_ops` | `hive`, `hive_ops` |
| Secrets + auth | `ssh_keys` | `secrets`, `ssh`, `ssh_keys` |
| Secrets + auth | `ssh_mesh` | `ssh`, `mesh_check` |
| Secrets + auth | `github` | `secrets`, `github` |
| Secrets + auth | `tailscale` | `secrets`, `tailscale` |
| Secrets + auth | `kube` | `secrets`, `kube` |
| Secrets + auth | `forgejo_registry` | `secrets`, `forgejo`, `registry` |
| Desktop apps | `flatpak` | `packages`, `desktop`, `flatpak` |
| Desktop apps | `bluefin_common` | `desktop`, `bluefin` |
| Desktop apps | `gnome` | `desktop`, `gnome` |
Expand All @@ -86,11 +82,11 @@ Every role in `site.yml` carries one or more tags. Tags fall into two kinds: **p
| Services | `server_hardening` | `system`, `hardening`, `security` |
| Services | `fleet_facts` | `facts`, `fleet_facts` |

Shell, git, neovim and atuin config, omp, and the shell/atuin secrets are not roles: they are [units](units.md) (`chezmoi`, `omp`, `atuin`, `shell-ai`) that `just apply*` runs after the playbook. The old tags `dotfiles`, `shell`, `git`, `neovim`, `editor`, `atuin`, `ai`, `secrets`, `omp` still select them through `scripts/run-units.sh`.
Shell, git, neovim and atuin config, fonts, omp, the shell/atuin/GitHub/Forgejo secrets and the kubeconfigs are not roles: they are [units](units.md) (`chezmoi`, `fonts`, `omp`, `atuin`, `shell-ai`, `github`, `kube`, `forgejo-registry`) that `just apply*` runs after the playbook. The old tags `dotfiles`, `shell`, `fonts`, `git`, `neovim`, `editor`, `atuin`, `ai`, `secrets`, `github`, `kube`, `forgejo`, `registry`, `omp` still select them through `scripts/run-units.sh`.

Common phase-wide selections:

- `--tags secrets` — every BW-backed role only (`bitwarden`, `ssh_keys`, `github`, `tailscale`, `kube`, `forgejo_registry`)
- `--tags secrets` — every BW-backed role only (`bitwarden`, `ssh_keys`, `tailscale`; the `atuin`, `shell-ai`, `github`, `kube` and `forgejo-registry` units also run for this tag)
- `--tags desktop` — every desktop-app role (`flatpak`, `bluefin_common`, `gnome`, `zen_browser`, `pipewire_audio`)
- `--tags services` — every long-running service role (`syncthing`, `systemd`, `bst_dashboard`, `kirocrew`, `proxy`, `tailscale_cert`)
- `--skip-tags secrets` — everything except BW-backed roles. `just apply-nosecrets`, bootstrap's first phase and `phone-apply.service` also pass `--no-secrets` to units.
Expand Down Expand Up @@ -129,8 +125,8 @@ Every flag `site.yml` reads, all defaulting to `false` (`| default(false)`). Set
|------|--------------|---------------------------------|---------------------|
| `skip_sudo` | `sudo` | — | `termux` |
| `skip_ssh_mesh` | `ssh_mesh` | not `vm-test` | — |
| `skip_kube` | `kube` | desktop, not `vm-test` | `mumbai`, `termux` |
| `skip_forgejo` | `forgejo_registry` | not `vm-test` | — |
| `skip_kube` | `kube` unit | desktop, not `vm-test` | `mumbai`, `termux` |
| `skip_forgejo` | `forgejo-registry` unit | not `vm-test` | — |
| `skip_flatpak` | `flatpak` | desktop, not `vm-test` | `mumbai`, `termux` |
| `skip_bluefin` | `bluefin_common` | desktop, not `vm-test` | `mumbai`, `termux` |
| `skip_gnome` | `gnome` | desktop, not `vm-test` | `mumbai`, `termux` |
Expand Down
6 changes: 3 additions & 3 deletions docs/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,9 @@ The `llm` group is dormant (commented out in `inventory.yml`).

| Phase | Roles | Main tags |
|-------|-------|-----------|
| 1 — System + packages + dotfiles | sudo, sshd, apk_packages, homebrew, termux_packages, bitwarden, shell_fonts, hive_ops | `system`, `packages`, `dotfiles` |
| 2 — Secrets + auth | ssh_keys, ssh_mesh, github, tailscale, kube, forgejo_registry | `secrets` |
| 1 — System + packages + dotfiles | sudo, sshd, apk_packages, homebrew, termux_packages, bitwarden, hive_ops | `system`, `packages`, `dotfiles` |
| 2 — Secrets + auth | ssh_keys, ssh_mesh, tailscale | `secrets` |
| 3 — Desktop apps | flatpak, bluefin_common, gnome, zen_browser (+ browser_fxa), pipewire_audio | `desktop` |
| 4 — Services | syncthing, systemd, bst_dashboard, kirocrew, proxy, tailscale_cert, server_hardening | `services` |

After the playbook, `just apply*` runs the [bash units](units.md) (`chezmoi`, `omp`, `atuin`, `shell-ai`) in parallel through mise. The `omp` unit also uses Bitwarden for its broker token. `just apply-nosecrets` skips secret-tagged roles and passes `--no-secrets` to units.
After the playbook, `just apply*` runs the [bash units](units.md) (`chezmoi`, `fonts`, `omp`, `atuin`, `shell-ai`, `github`, `kube`, `forgejo-registry`) in parallel through mise. The `omp` unit also uses Bitwarden for its broker token. `just apply-nosecrets` skips secret-tagged roles and passes `--no-secrets` to units.
24 changes: 8 additions & 16 deletions docs/src/roles/forgejo_registry.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,21 @@
# forgejo_registry

**Unit:** `forgejo-registry` (`units/forgejo-registry.sh`; see [Units](../units.md))
**Tags:** `secrets`, `forgejo`, `registry`
**Secrets needed:** Yes (Login item named after the registry host)
**Runs on:** All machines except `machine_profile: vm-test` (unless `skip_forgejo: true`)
**Secrets needed:** Yes (login item named after the registry host)
**Runs on:** All machines except `machine_profile: vm-test` or `skip_forgejo: true` in `host_vars`

Logs podman in to the private Forgejo container registry.

## What It Does
## What it does

When `bw_unlocked` and `podman` is on `PATH`:

1. Checks `podman login --get-login {{ forgejo_registry }}` — skips if already logged in
2. Fetches `bw get username` / `bw get password` for the item named `{{ forgejo_registry }}`
3. Runs `podman login … --password-stdin`
4. Warns if the Bitwarden item is missing
1. `SKIPPED:` unless `podman` is installed; no-op when `podman login --get-login <registry>` already succeeds.
2. With an unlocked vault: `bw get username` / `bw get password` for the item named after the registry, then `podman login <registry> -u <user> --password-stdin`. A missing item prints `PARTIAL:` and is not a failure.

## Configuration

```yaml
# roles/forgejo_registry/defaults/main.yml
forgejo_registry: forgejo.manatee-basking.ts.net
```

The Bitwarden Login item's name must equal this value; its password is a registry/package token.
The registry host is `FORGEJO_REGISTRY` in `units/forgejo-registry.sh` (default `forgejo.manatee-basking.ts.net`, overridable from the environment). The Bitwarden login item's name must equal it; its password is a registry/package token.

## Notes

- Forgejo runs on the home Talos cluster, which is currently powered down — a fresh `podman login` can't succeed until it returns. Hosts already logged in skip the step.
- Forgejo ran on the home cluster, which is powered down, so a fresh `podman login` cannot succeed until it returns. Hosts already logged in skip the step.
43 changes: 22 additions & 21 deletions docs/src/roles/github.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,39 @@
# github

**Tags:** `secrets`, `github`
**Secrets needed:** Yes (only on first auth — once `gh` is authenticated, BW is not required)
**Runs on:** All machines with `gh` installed
**Unit:** `github` (`units/github.sh`; see [Units](../units.md))
**Tags:** `secrets`, `github`
**Secrets needed:** Only on first auth; once `gh` is authenticated Bitwarden is not used
**Runs on:** All machines with `gh` installed (`SKIPPED:` otherwise)

Logs `gh` in via a BW-stored PAT (only if not already authenticated), then registers this host's SSH key with GitHub for both auth and signing.
Logs `gh` in via a Bitwarden-stored PAT (only if not already authenticated), then registers this host's SSH key with GitHub for both authentication and signing. With `--no-secrets`, only the local known-hosts step runs; the unit does not invoke `gh` or Bitwarden.

## What it does
## Steps

1. Ensures `github.com`'s ed25519 host key is in `~/.ssh/known_hosts` (prevents MITM warnings on first push).
2. `gh auth status` — if already authenticated, skip the token fetch entirely (no BW dependency for steady-state).
3. If not authenticated and BW is unlocked → `bw get password github-token` → `gh auth login --with-token`. If the BW item is missing, emits a one-line warning and continues.
4. Sets `gh config set git_protocol ssh`.
5. Lists existing keys on the GitHub account. For each key type (auth + signing), runs `gh ssh-key add` if this host's key isn't already there.
1. `github known_hosts`: ensure github.com's ed25519 host key is in `~/.ssh/known_hosts`.
2. `gh login`: skipped when `gh auth status` succeeds. Otherwise, with an unlocked vault, `bw get password github-token` → `gh auth login --with-token`. Locked vault or missing item prints a `PARTIAL:` line.
3. `register SSH keys`: needs a token with `admin:public_key` and `admin:ssh_signing_key` (otherwise a `PARTIAL:` line with the regenerate-PAT link). For each of authentication and signing, `gh ssh-key add ~/.ssh/id_ed25519.pub --title <machine>-auth|-signing` unless `gh ssh-key list` already shows the key with that type. If the list fails, the unit fails without registering either key.

GitHub CLI configuration, including `git_protocol: ssh`, is managed by chezmoi, not this unit.

## Failure modes

| Symptom | Cause | Fix |
|---|---|---|
| `gh auth status` says `not logged in` after apply, vault locked | First run on this host with BW locked | Unlock BW and re-run `just apply-tags github`, or `gh auth login` manually |
| Warning: `No 'github-token' item found` | BW vault doesn't have the PAT | Create a BW *login* item named `github-token` with your PAT as the password |
| Key registration silently fails | `gh ssh-key add` returned non-zero (failed_when:false) — possibly key was just deleted on github.com side | Inspect with `gh ssh-key list` and re-run the role |
| Stale keys clutter github.com | This host's previous key was rotated; the old gh entry stays forever | Delete the old key manually at <https://github.com/settings/keys> — no automated cleanup yet |
| `PARTIAL: gh not logged in; vault locked` | First run on this host with Bitwarden locked | `bw unlock`, then `just apply-tags github`, or `gh auth login` |
| `PARTIAL: no 'github-token' item` | Vault has no PAT | Create a login item `github-token` with the PAT as the password |
| `PARTIAL: GitHub token lacks admin:public_key / admin:ssh_signing_key` | PAT scopes | Regenerate the PAT with those scopes and update the item |
| `warn: failed to list GitHub SSH keys; registration skipped` | `gh ssh-key list` failed | Check GitHub access and re-run; no keys were added |
| `warn: failed to upload SSH ... key` | `gh ssh-key add` failed | Inspect with `gh ssh-key list` and re-run |

## How to verify
## Verify

```bash
gh auth status # Should say "Logged in" with this account
gh ssh-key list | grep "$(hostname)" # Should show <hostname>-auth and <hostname>-signing
git log --show-signature -1 # Latest commit should show "Good \"git\" signature for ..."
gh auth status
gh ssh-key list | grep "$(cat /etc/dotfiles-machine)" # <machine>-auth and <machine>-signing
```

## Notes

- Depends on the `ssh_keys` role running first (the key must exist on disk).
- The signing key registration enables the "Verified" badge on commits — only if your local `~/.gitconfig` is also set to sign with the SSH key (the `git` role handles this).
- The PAT in BW needs `admin:public_key`, `write:gpg_key`, and `read:user` scopes for the registrations to succeed.
- Needs `~/.ssh/id_ed25519.pub`, written by the `ssh_keys` role; the units run after the playbook, so a first apply gets both in one pass.
- The "Verified" badge also needs the signing config in `~/.gitconfig` (the chezmoi-managed [git](git.md) config).
- Stale keys from rotated machine keys are not cleaned up: delete them at <https://github.com/settings/keys>.
32 changes: 15 additions & 17 deletions docs/src/roles/kube.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,30 @@
# kube

**Tags:** `secrets`, `kube`
**Secrets needed:** Yes
**Runs on:** Desktop group only (unless `skip_kube: true`)
**Unit:** `kube` (`units/kube.sh`; see [Units](../units.md))
**Tags:** `secrets`, `kube`
**Secrets needed:** Yes
**Runs on:** Desktops only (`SKIPPED:` otherwise, or with `skip_kube: true` / `machine_profile: vm-test` in `host_vars`)

Pulls the kube + Talos configs for both Talos clusters from BW so any desktop in the fleet can talk to them: the home cluster (Bihar + Karnataka — powered down, expected back) and the [AWS cluster](../servers/aws-k8s/cluster.md).
Pulls the kube + Talos configs for both clusters from Bitwarden so any desktop in the fleet can talk to them: the home cluster (Bihar + Karnataka, powered down, expected back) and the [AWS cluster](../servers/aws-k8s/cluster.md) (its nodes were terminated on 2026-10-25; the configs are kept).

## What it does
## Steps

When `bw_unlocked` is true:
With an unlocked vault (a locked vault or `--no-secrets` prints `SKIPPED:` and leaves existing files alone):

1. Ensures `~/.kube/` and `~/.talos/` exist (mode 0700).
2. `bw get notes kubeconfig` → writes to `~/.kube/config` (0600). Skipped if BW returns empty.
3. `bw get notes talosconfig` → writes to `~/.talos/config` (0600). Skipped if BW returns empty.
4. Pins `tls-server-name` on every cluster in `~/.kube/config` to `kube_tls_server_name` (default: bihar's LAN address) — the home API-server cert lacks the tailnet address in its SANs.
5. Emits a one-line warning if either home-cluster note is missing in BW.
6. `bw get notes kubeconfig-aws-migration` → `~/.kube/config-aws-migration` and `bw get notes talosconfig-aws-migration` → `~/.talos/config-aws-migration` (0600, each skipped if empty). Kept as separate files so both clusters stay independently usable.

When the vault is locked the role no-ops cleanly — existing local configs are preserved.
1. `kube dirs`: `~/.kube/` and `~/.talos/` (0700).
2. `home kubeconfig`: `bw get notes kubeconfig` → `~/.kube/config` (0600). A missing note prints `warn:` and leaves the file as it is.
3. `home talosconfig`: `bw get notes talosconfig` → `~/.talos/config` (0600).
4. `pin tls-server-name`: after writing the home kubeconfig, every cluster in it gets `--tls-server-name=$KUBE_TLS_SERVER_NAME` (`units/kube.conf`, default bihar's LAN address `192.168.0.5`): the home API-server cert lacks the tailnet address in its SANs.
5. `aws kubeconfig` / `aws talosconfig`: `kubeconfig-aws-migration` → `~/.kube/config-aws-migration`, `talosconfig-aws-migration` → `~/.talos/config-aws-migration`. Separate files keep both clusters independently usable.

## Failure modes

| Symptom | Cause | Fix |
|---|---|---|
| `kubectl` returns `Unable to connect to the server` after onboarding | Vault was locked, configs never deployed | Unlock BW, re-run `just apply-tags kube` |
| Warning: `kubeconfig missing in BW` | Vault was never seeded | Run `just seed-kube` from a host that already has a working config |
| `warn: kubeconfig ... missing in BW` | Vault was never seeded | Run `just seed-kube` from a host that already has a working config |
| Configs deployed but auth fails | Cluster PKI rotated — local configs are stale | Re-run `just seed-kube` from a healthy host, then re-apply on consumers |
| Role skipped silently on a server host that should have it | `skip_kube: true` in `host_vars/<host>.yml`, or host not in `desktop` group | Adjust inventory or host_vars |
| Unit prints `SKIPPED: not a desktop` on a host that should have it | `skip_kube: true` in `host_vars/<host>.yml`, or host not in the `desktop` group | Adjust inventory or host_vars |

## Seeding BW

Expand All @@ -48,4 +46,4 @@ KUBECONFIG=~/.kube/config-aws-migration kubectl get nodes # AWS cluster
## Notes

- Both files contain cluster PKI material; the repo's `.gitignore` excludes the cluster source files, and these caches live in `~/` only — never commit.
- The role is gated by `is_desktop | bool and not skip_kube`. Servers don't get a kubeconfig — the cluster nodes themselves are Talos and not in the inventory.
- Gated by desktop membership and `skip_kube`. Servers don't get a kubeconfig; the cluster nodes are not in the inventory.
Loading