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