update README and add CLAUDE.md

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>
2026-06-26 17:44:24 +02:00
parent 7ff029e59a
commit 9f7cc45e86
2 changed files with 72 additions and 0 deletions
@@ -0,0 +1,63 @@
+# 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.