Add Jeannie man page
This commit is contained in:
juvdiaz
parent
8582c3ea61
commit
1d73c33703
|
|
@ -0,0 +1,289 @@
|
||||||
|
# JEANNIE(1)
|
||||||
|
|
||||||
|
## NAME
|
||||||
|
|
||||||
|
jeannie - operate the personal homelab control pipeline
|
||||||
|
|
||||||
|
## SYNOPSIS
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./jeannie COMMAND [ARG...]
|
||||||
|
```
|
||||||
|
|
||||||
|
## DESCRIPTION
|
||||||
|
|
||||||
|
`jeannie` is the main homelab operator script. It deploys and checks the Debian
|
||||||
|
control host, Gitea, Raspberry Pi services, Pimox workers, Kubernetes platform
|
||||||
|
components, applications, public edge routing, secrets tooling, and local AI
|
||||||
|
helpers.
|
||||||
|
|
||||||
|
Run mutating infrastructure commands from the Debian homelab host. Commands that
|
||||||
|
can destroy or rewrite state have explicit confirmation environment variables.
|
||||||
|
The canonical script name is `metadata.main_script` in `homelab.yml`.
|
||||||
|
|
||||||
|
## COMMANDS
|
||||||
|
|
||||||
|
### Core Lifecycle
|
||||||
|
|
||||||
|
`up`
|
||||||
|
: Deploy the full homelab pipeline. Runs early preflight, deploys Gitea and RPi
|
||||||
|
services, runs full preflight and pre-apply doctor checks, then applies Pimox,
|
||||||
|
OpenWrt, cluster, platform, apps, and edge stacks.
|
||||||
|
|
||||||
|
`plan [all|provisioning|cluster|platform|apps|edge]`
|
||||||
|
: Run OpenTofu plans without applying changes. The default target is `all`.
|
||||||
|
|
||||||
|
`rebuild-cluster`
|
||||||
|
: Back up current local OpenTofu state, destroy cluster state through the guarded
|
||||||
|
nuke path, rebuild Pimox workers, recreate the cluster, and redeploy platform,
|
||||||
|
apps, and edge.
|
||||||
|
|
||||||
|
`stop-cluster`
|
||||||
|
: Stop the Kubernetes control-plane runtime and worker VMs without destroying
|
||||||
|
cluster state.
|
||||||
|
|
||||||
|
`start-cluster`
|
||||||
|
: Start the Kubernetes control-plane runtime and desired worker VMs.
|
||||||
|
|
||||||
|
`status`
|
||||||
|
: Print a compact health report for the configured homelab.
|
||||||
|
|
||||||
|
`nuke`
|
||||||
|
: Destroy Kubernetes state and Pimox worker VMs. Requires
|
||||||
|
`LAB_CONFIRM_NUKE=homelab`.
|
||||||
|
|
||||||
|
### Deploy Targets
|
||||||
|
|
||||||
|
`apps`
|
||||||
|
: Deploy platform applications and build or publish application images when
|
||||||
|
needed.
|
||||||
|
|
||||||
|
`deploy-gitea`
|
||||||
|
: Deploy the external Gitea Docker Compose service on the Debian host.
|
||||||
|
|
||||||
|
`rpi-services`
|
||||||
|
: Deploy Pi-hole, Unbound, and Uptime Kuma on the Raspberry Pi.
|
||||||
|
|
||||||
|
`bootstrap-gitea-repo`
|
||||||
|
: Ensure the configured Gitea repository, branch, remotes, and host SSH key are
|
||||||
|
ready.
|
||||||
|
|
||||||
|
`openwrt`
|
||||||
|
: Apply the OpenWrt VM stack.
|
||||||
|
|
||||||
|
### Gitea Operations
|
||||||
|
|
||||||
|
`backup-gitea`
|
||||||
|
: Run a Gitea backup on the Debian host.
|
||||||
|
|
||||||
|
`drill-gitea-restore`
|
||||||
|
: Run the Gitea restore drill workflow.
|
||||||
|
|
||||||
|
`install-gitea-runner [TOKEN]`
|
||||||
|
: Install or repair the Gitea Actions runner. If `TOKEN` is omitted, the command
|
||||||
|
uses the configured token source.
|
||||||
|
|
||||||
|
### Checks And Doctors
|
||||||
|
|
||||||
|
`preflight`
|
||||||
|
: Run homelab preflight checks. This verifies inventory-derived host settings,
|
||||||
|
Docker roots, Tailscale IPs, Gitea reachability, Pimox storage, and OCI edge SSH.
|
||||||
|
|
||||||
|
`doctor-preapply`
|
||||||
|
: Run blocking readiness checks used by `up` before high-blast-radius applies.
|
||||||
|
It checks Debian free disk, Docker and containerd, Raspberry Pi Docker
|
||||||
|
writability, Pimox storage, OCI edge disk, and Pi-hole DNS.
|
||||||
|
|
||||||
|
`doctor-versions`
|
||||||
|
: Check Kubernetes component version alignment.
|
||||||
|
|
||||||
|
`doctor-edge`
|
||||||
|
: Diagnose public edge routing, Traefik reachability, and Gitea edge exposure.
|
||||||
|
|
||||||
|
`doctor-gitea`
|
||||||
|
: Diagnose Debian Gitea container, local access, edge access, and repository
|
||||||
|
health.
|
||||||
|
|
||||||
|
`doctor-rpi`
|
||||||
|
: Diagnose Raspberry Pi services, Pi-hole DNS, Unbound DNS, fallback DNS,
|
||||||
|
Uptime Kuma, and Docker root state.
|
||||||
|
|
||||||
|
`doctor-cluster`
|
||||||
|
: Diagnose Kubernetes API, nodes, core pods, MetalLB, Traefik, and app health.
|
||||||
|
|
||||||
|
`inventory-check`
|
||||||
|
: Validate `homelab.yml` with a real YAML parser when available.
|
||||||
|
|
||||||
|
`secrets-check`
|
||||||
|
: Validate SOPS and age configuration plus committed encrypted secret file
|
||||||
|
structure.
|
||||||
|
|
||||||
|
`tailnet-policy-check`
|
||||||
|
: Validate the repo-managed Tailscale ACL policy.
|
||||||
|
|
||||||
|
`ai-check`
|
||||||
|
: Check local AI helper prerequisites, knowledge index, and Ollama availability
|
||||||
|
when the backstage helper is enabled.
|
||||||
|
|
||||||
|
### Maintenance
|
||||||
|
|
||||||
|
`state-backup`
|
||||||
|
: Create a local tarball backup of OpenTofu state and generated homelab state
|
||||||
|
files.
|
||||||
|
|
||||||
|
`fix-debian-docker-root`
|
||||||
|
: Repair or migrate the Debian Docker root according to inventory settings.
|
||||||
|
|
||||||
|
`move-prometheus-stack-workers`
|
||||||
|
: Move Prometheus stack workloads off the control plane. Requires
|
||||||
|
`LAB_CONFIRM_DELETE_PROMETHEUS_DATA=true` because Prometheus PVC data is deleted.
|
||||||
|
|
||||||
|
`secrets-init`
|
||||||
|
: Initialize local age and SOPS configuration on the Debian host.
|
||||||
|
|
||||||
|
`ai-index`
|
||||||
|
: Build the local homelab knowledge index for the backstage AI helper.
|
||||||
|
|
||||||
|
`ollama-setup`
|
||||||
|
: Install or configure Ollama on the Debian host and pull the configured local
|
||||||
|
model.
|
||||||
|
|
||||||
|
`website-translation-model`
|
||||||
|
: Prepare the website translation model assets.
|
||||||
|
|
||||||
|
`website-ollama-listen`
|
||||||
|
: Configure the Ollama service listen address for website use.
|
||||||
|
|
||||||
|
## COMMON ENVIRONMENT
|
||||||
|
|
||||||
|
`HOMELAB_INVENTORY_FILE`
|
||||||
|
: Path to the canonical non-secret inventory. Defaults to `./homelab.yml`.
|
||||||
|
|
||||||
|
`HOMELAB_STATE_DIR`
|
||||||
|
: Local runtime state directory. Defaults to
|
||||||
|
`${XDG_DATA_HOME:-$HOME/.local/share}/homelab`.
|
||||||
|
|
||||||
|
`JEANNIE_LOG_DIR`
|
||||||
|
: Directory for command logs. Defaults to `$HOMELAB_STATE_DIR/logs`.
|
||||||
|
|
||||||
|
`JEANNIE_VERBOSE=true`
|
||||||
|
: Print full step output as it runs. Without this, noisy commands are compact and
|
||||||
|
full output is written to the log file.
|
||||||
|
|
||||||
|
`LAB_AUTO_APPROVE=false`
|
||||||
|
: Disable automatic OpenTofu approval for apply paths that support confirmation.
|
||||||
|
|
||||||
|
`LAB_PIMOX_WORKER_COUNT`
|
||||||
|
: Desired Pimox worker count when not supplied by generated cluster topology
|
||||||
|
state.
|
||||||
|
|
||||||
|
`LAB_SKIP_PREFLIGHT=true`
|
||||||
|
: Skip preflight checks. Use only for targeted troubleshooting.
|
||||||
|
|
||||||
|
`LAB_PREFLIGHT_ROOT_MIN_FREE_GIB`
|
||||||
|
: Minimum Debian `/` free space for `doctor-preapply`. Default is `10`.
|
||||||
|
|
||||||
|
`LAB_PREFLIGHT_DATA_MIN_FREE_GIB`
|
||||||
|
: Minimum Debian `/data` free space for `doctor-preapply`. Default is `20`.
|
||||||
|
|
||||||
|
`LAB_PREFLIGHT_EDGE_MIN_FREE_GIB`
|
||||||
|
: Minimum OCI edge `/` free space for `doctor-preapply`. Default is `2`.
|
||||||
|
|
||||||
|
`LAB_GITEA_INSTALL_DOCKER=true`
|
||||||
|
: Allow `deploy-gitea` to install Docker through `get.docker.com` when Docker is
|
||||||
|
missing. Default is to fail and ask for host bootstrap.
|
||||||
|
|
||||||
|
`LAB_RPI_INSTALL_DOCKER=true`
|
||||||
|
: Allow `rpi-services` to install Docker through `get.docker.com` on the
|
||||||
|
Raspberry Pi when Docker is missing. Default is to fail.
|
||||||
|
|
||||||
|
`TF_VAR_edge_install_docker=true`
|
||||||
|
: Allow the edge OpenTofu stack to install Docker on the OCI host when Docker is
|
||||||
|
missing. Default is to fail.
|
||||||
|
|
||||||
|
`TF_VAR_haproxy_stats_password`
|
||||||
|
: Required HAProxy stats password for the edge stack. It must be set explicitly
|
||||||
|
and must not use the old default.
|
||||||
|
|
||||||
|
`LAB_CONFIRM_NUKE=homelab`
|
||||||
|
: Required confirmation for direct `./jeannie nuke`.
|
||||||
|
|
||||||
|
`LAB_NUKE_DESTROY_PIMOX_WORKERS=true`
|
||||||
|
: Also destroy Pimox worker VMs during `nuke`.
|
||||||
|
|
||||||
|
`LAB_CONFIRM_DELETE_PROMETHEUS_DATA=true`
|
||||||
|
: Required confirmation for `move-prometheus-stack-workers`.
|
||||||
|
|
||||||
|
## FILES
|
||||||
|
|
||||||
|
`homelab.yml`
|
||||||
|
: Canonical non-secret inventory for hosts, IPs, domains, ports, and the main
|
||||||
|
script name.
|
||||||
|
|
||||||
|
`.lab/cluster-workers.auto.tfvars.json`
|
||||||
|
: Generated worker topology passed to the cluster stack.
|
||||||
|
|
||||||
|
`.lab/pimox-workers.tsv`
|
||||||
|
: Generated Pimox worker inventory.
|
||||||
|
|
||||||
|
`.lab/manual-workers.tsv`
|
||||||
|
: User-managed manual worker inventory.
|
||||||
|
|
||||||
|
`$HOMELAB_STATE_DIR/logs`
|
||||||
|
: Jeannie command logs.
|
||||||
|
|
||||||
|
`$HOMELAB_STATE_DIR/tofu-state-backups`
|
||||||
|
: Local OpenTofu and generated state backups.
|
||||||
|
|
||||||
|
## EXAMPLES
|
||||||
|
|
||||||
|
Start a three-worker homelab:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
LAB_PIMOX_WORKER_COUNT=3 ./jeannie up
|
||||||
|
```
|
||||||
|
|
||||||
|
Preview all OpenTofu changes:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./jeannie plan
|
||||||
|
```
|
||||||
|
|
||||||
|
Run focused edge diagnostics:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./jeannie doctor-edge
|
||||||
|
```
|
||||||
|
|
||||||
|
Run the blocking pre-apply doctor directly:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./jeannie doctor-preapply
|
||||||
|
```
|
||||||
|
|
||||||
|
Create a local state backup:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./jeannie state-backup
|
||||||
|
```
|
||||||
|
|
||||||
|
Destroy the cluster path intentionally:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
LAB_CONFIRM_NUKE=homelab ./jeannie nuke
|
||||||
|
```
|
||||||
|
|
||||||
|
## EXIT STATUS
|
||||||
|
|
||||||
|
`0`
|
||||||
|
: Command completed successfully.
|
||||||
|
|
||||||
|
Non-zero
|
||||||
|
: A check, deployment step, or external tool failed. Check the printed error and
|
||||||
|
the referenced Jeannie log file for full command output.
|
||||||
|
|
||||||
|
## SEE ALSO
|
||||||
|
|
||||||
|
`README.md`, `docs/service-catalog.md`, `docs/runbooks/edge-failures.md`,
|
||||||
|
`docs/runbooks/gitea-failures.md`,
|
||||||
|
`docs/runbooks/cluster-stop-start-failures.md`, `docs/secrets.md`.
|
||||||
Loading…
Reference in New Issue