# dotfiles

Configures fresh VMs (RHEL-family or Debian-family) with a consistent
environment. Run `./bootstrap.sh` (or curl-pipe it) to apply everything;
each module also runs standalone and is safe to re-run.

## Quick start

On a fresh box, apply everything with one command:

```sh
curl -fsSL https://git.nic-oconnor.com/public/dotfiles/raw/branch/main/bootstrap.sh | sh
```

When piped like this (no local checkout), `bootstrap.sh` clones the repo to
`~/.dotfiles` and runs from there, so `git` must be installed first. Re-running
the command updates the checkout (`git pull`) and re-applies every module.
Override the destination or source with `DOTFILES_DIR` / `DOTFILES_REPO`.

Already have a clone? Just run it directly:

```sh
./bootstrap.sh
```

## Modules

- `zsh/` — installs zsh + oh-my-zsh, drops a managed `~/.zshrc`
  (robbyrussell theme, git plugin), and sets zsh as the login shell. The
  managed rc sources `~/.zshrc.local` last for per-machine customizations
  (see below).
- `git/` — sets git `user.name`/`user.email` and configures
  `credential.helper store` (plaintext `~/.git-credentials`, 0600) for
  HTTPS auth.
- `docker/` — installs full (rootful) Docker Engine via get.docker.com,
  enables the service (systemd hosts), and adds the invoking user to the
  `docker` group (takes effect at next login). No-ops where a rootless
  Docker daemon is already running (e.g. Kasm) so it never fights that
  setup. Uses sudo.
- `bin/` — installs userland devops CLIs as self-contained, statically
  linked release binaries into `~/.local/bin`: jq, kubectl, helm, k9s,
  kubectx/kubens, stern, yq, OpenTofu, terragrunt, task (go-task, the
  Taskfile runner), the 1Password CLI `op` for secrets storage, the
  opencode coding agent, zarf (DevSecOps for Offline and Airgapped
  Kubernetes), and packer (HashiCorp's infrastructure build tool).
  kind is installed only when full (non-rootless) Docker is available —
  it doesn't work against rootless Docker, so it is skipped on Kasm.
  No sudo, nothing outside `$HOME`, so tools persist across Kasm
  redeploys with no reinstall. Idempotent: each tool records its version
  under `~/.local/bin/.versions` and is skipped when the pinned version
  is already present. `zsh/zshrc` puts `~/.local/bin` on `PATH`.

  opencode is configured by `mcp-config/`: it points at the covert-gpt
  LiteLLM gateway (`https://llm.covert-gpt.com/v1` for models,
  `https://llm.covert-gpt.com/mcp` for MCP tools). Run
  `mcp-config/install.sh` once to store your LiteLLM key and enable
  config sync — without it, opencode installs but can't reach the
  gateway.
- `ansible/` — installs Ansible into a virtualenv at `~/.local/opt/ansible`
  (it's Python, not a single binary) and symlinks its CLIs into
  `~/.local/bin`. Persists across redeploys; only rebuilt when the venv is
  missing or broken. Building it may install `python3`/`python3-venv` via
  the system package manager (the one place this module uses sudo).
- `docker-rootless-cgroup/` — on systemd-less hosts (e.g. Kasm), hand-delegates
  cgroup v2 controllers to the rootless Docker daemon so per-container cgroups
  work (rootless Docker otherwise comes up with
  `CgroupDriver=none`). Uses sudo for host cgroup writes and restarts the
  daemon; no-ops on systemd or non-rootless hosts. Re-run at each bootstrap
  (the cgroup layout resets on redeploy); its PATH shim lives in `$HOME`.
- `mcp-config/` — shared MCP gateway config sync for laptops (LiteLLM /
  opencode). Independent of `bootstrap.sh`; see its own README.

## Per-machine customizations and secrets

`~/.zshrc` is managed — bootstrap overwrites it, so never hand-edit it.
Per-machine settings and secrets go in `~/.zshrc.local`, which the managed
rc sources last (so it can override anything) and bootstrap never touches:

```sh
cp zsh/zshrc.local.example ~/.zshrc.local && chmod 600 ~/.zshrc.local
```

Variables modules look for:

- `GITEA_KEY` — personal access token for `git.nic-oconnor.com` (API/CLI
  use; HTTPS git auth itself goes through `git/`'s credential helper).
- `LITELLM_KEY` — covert-gpt gateway key used by opencode. Normally you
  don't set this by hand: run `mcp-config/install.sh` once and its shell
  hook exports it from `~/.config/mcp-sync/key`. Set it in `~/.zshrc.local`
  only on a box without mcp-sync.
- `OP_SERVICE_ACCOUNT_TOKEN` — 1Password service-account token for
  non-interactive `op read` / `op run`.
- `GITEA_KEY`, `PROXMOX_MCP_TOKEN_ID`, `PROXMOX_MCP_TOKEN_SECRET` — **your own**
  credentials for the client-side MCP servers in `mcp-config/`. opencode reads
  them from your environment (`{env:VAR}`) and passes them to the MCP server it
  spawns, so the tools act as *you*. Keep them in `~/.zshrc.local`; they are
  never written into any config file.

  These are NOT used by `ai-k8s-iac` / `task up`: the LiteLLM gateway hosts no
  MCP servers and stores no MCP credentials. See `mcp-config/README.md`.

Secrets never go in this repo or in `zsh/zshrc` — that file is shared
config applied to every box.

`lib/os-detect.sh` provides shared package-manager detection (`dnf`/`yum`
vs `apt`); `lib/fetch.sh` provides arch detection and binary-download
helpers. Both are used by module install scripts.