jhummel
9f7cc45e86
Mark linux_apt-upgrade.yaml as work-in-progress in README, add dedicated section for it. Add CLAUDE.md with repo architecture guidance. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this repo is
|
|
|
|
A collection of Kestra workflow flows (YAML) and helper scripts (Python) for homelab automation. The flows run inside Kestra and use this Git repository as the source for versioned logic.
|
|
|
|
**Core separation of concerns:**
|
|
- `*.yaml` — Kestra flows (orchestration, task sequencing, SSH commands)
|
|
- `*.py` — Python scripts called at runtime by Kestra (data processing, transformation)
|
|
- `.env` — Secrets and credentials, never committed (see `.env.example`)
|
|
|
|
## Testing the Python script locally
|
|
|
|
```bash
|
|
export OPTIONS_B64_JSON='["WyJkb2NrZXIxOzE5Mi4xNjguMTAwLjEwO21laW51c2VyOy9ob21lL21laW51c2VyL2RvY2tlci9uZXh0Y2xvdWQiXQ=="]'
|
|
python3 build_select_options.py
|
|
cat select_options.json
|
|
```
|
|
|
|
The script reads `OPTIONS_B64_JSON` (a JSON array of base64-encoded per-host results) and writes `select_options.json`.
|
|
|
|
## Architecture: how flows use Python scripts
|
|
|
|
The `docker_stack_inventory_scan` flow does **not** bundle the Python script inline. Instead, it clones this Git repo at runtime via `io.kestra.plugin.git.Clone` inside a `WorkingDirectory` task, then finds and runs `build_select_options.py` dynamically using `find`. This means:
|
|
- Changes to `.py` files take effect on the next flow run without redeploying the flow
|
|
- The flow variable `git_repo_url` and `git_branch` control which repo/branch is used
|
|
|
|
## Kestra secrets
|
|
|
|
Secrets are referenced in flows as `{{ secret('SECRET_NAME') }}`. For Kestra OSS, secrets must be stored base64-encoded in `.env` with the `SECRET_` prefix:
|
|
|
|
```bash
|
|
# Encode a value
|
|
echo -n "my-secret-value" | base64 -w 0
|
|
|
|
# Encode an SSH private key
|
|
base64 -w 0 ~/.ssh/id_ed25519
|
|
```
|
|
|
|
Then in `.env`:
|
|
```env
|
|
SECRET_SSH_PRIVATE_KEY=base64_encoded_value
|
|
```
|
|
|
|
## KV-Store data format
|
|
|
|
The `docker_stack_inventory_scan` flow writes to the KV key `docker_stack_select_options`. Each entry is a semicolon-delimited string:
|
|
|
|
```
|
|
hostname;ip-address;ssh-user;/path/to/compose-dir
|
|
```
|
|
|
|
The `docker_hosts` variable in the flow uses the same `hostname;ip-address` format.
|
|
|
|
## Flow namespaces
|
|
|
|
All flows use the `homelab.docker` namespace.
|
|
|
|
## Compose file discovery
|
|
|
|
The SSH scan uses `find -maxdepth 2` under `base_dir`. Compose files must be named exactly `compose.yml`, `compose.yaml`, `docker-compose.yml`, or `docker-compose.yaml` and located at most 2 levels deep to be detected.
|