dotfiles/README.md

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:

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:

./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, and zarf (DevSecOps for Offline and Airgapped Kubernetes). 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:

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.