autonomic-bot
f283a371bb
Sanitized single-commit public mirror of recipe-maintainer. - Removed test-ssh/.testenv (live creds); added test-ssh/.testenv.example placeholders. - Removed plans/ and planned-updates/ (deployment-planning docs) so no client/ deployment domains appear in the public repo. - All other secret stores were already gitignored. - docs.coopcloud.tech retained as a submodule (public upstream).
88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
## Getting Started
|
|
|
|
At the start of each session, before doing any work:
|
|
|
|
1. Read `README.md` to understand this project's purpose, structure, skills, and test environment setup.
|
|
2. Read the `docs.coopcloud.tech/` folder to understand how Co-op Cloud and `abra` work, including recipe structure, deployment patterns, configuration conventions, and best practices.
|
|
|
|
This background context is essential for all recipe-related tasks.
|
|
|
|
3. **Read `learnings.md`** for abra CLI best practices — it contains critical information about TTY requirements, `--chaos` flag usage, and other operational patterns that will save you from common pitfalls. In particular:
|
|
- Many `abra` commands (e.g. `abra app cmd`, `abra app backup create`, `abra app logs`) require a TTY wrapper: `script -qefc "abra ..." /dev/null`
|
|
- Always use `--chaos` during local recipe development to prevent abra from changing your working tree
|
|
- Prefer `docker service logs` via SSH over `abra app logs` in non-interactive environments
|
|
|
|
4. **Read these key skill files** so you understand operational patterns used across all tasks:
|
|
- `.claude/commands/test-context-reset.md` — how context reset works, including the **in-use lock file** mechanism (`in-use/<recipe>.lock`): these files protect recipes from being undeployed during active work. Always create one when starting work on a recipe, remove it when done.
|
|
- `.claude/commands/recipe-deploy.md` — the standard deploy flow (chaos mode, force, no-input)
|
|
- `.claude/commands/recipe-test.md` — how recipe tests are run
|
|
- `.claude/commands/init-instance.md` — how the test instance is initialised from scratch
|
|
|
|
## Always pull the latest recipe before answering questions about it
|
|
|
|
Before answering any question about a specific recipe (config, env vars, compose overlays, secrets, etc.), `git fetch` and check `origin/main` in the recipe's checkout. The local copy can be days or weeks behind, and recipes change — new `compose.*.yml` overlays, new secrets, env-var renames, and entrypoint changes land regularly. Answering from a stale tree produces confidently-wrong advice.
|
|
|
|
```bash
|
|
cd /workspace/.container-abra/recipes/<recipe>
|
|
git fetch
|
|
git log --oneline HEAD..origin/main # show what you're missing
|
|
```
|
|
|
|
If `origin/main` is ahead, either pull or `git show`/`git diff` the new commits before answering.
|
|
|
|
## Recipe semver vs. image versions
|
|
|
|
Co-op Cloud recipe versions are independent of the upstream app/image version, and follow semver
|
|
*for the recipe* — not the app. The recipe version label (the `coop-cloud.${STACK_NAME}.version`
|
|
tag in `compose.yml`, e.g. `0.3.4+v5.2.0`) has two parts: `<recipe-semver>+<app-version>`.
|
|
|
|
When you bump an image tag (the `+<app-version>` part), you **must** also bump the recipe semver
|
|
(the part before `+`). The size of that bump is determined by what the operator has to do, **not**
|
|
by how big the app's own version jump is:
|
|
|
|
- **Patch** (`0.3.4 → 0.3.5`) — the usual case. The image version increased but **no operator
|
|
action is required**: deploying the new version "just works" (no new/renamed env vars, no new
|
|
secrets, no manual migration, no breaking config changes).
|
|
- **Minor** (`0.3.4 → 0.4.0`) — new optional functionality or new env vars/secrets that have safe
|
|
defaults; the operator *may* want to act but isn't forced to.
|
|
- **Major** (`0.3.4 → 1.0.0`) — operator action is **required**: breaking changes, mandatory new
|
|
secrets/env vars, manual data migrations, or anything that breaks an existing deployment if applied
|
|
blindly.
|
|
|
|
Default to a **patch** bump for routine image-version upgrades. Only go minor/major when the upgrade
|
|
genuinely demands operator awareness or action.
|
|
|
|
## Git commits
|
|
|
|
- Author every commit as `notplants <@notplants>` (use `--author="notplants <@notplants>"`).
|
|
- Do **not** add `Co-Authored-By` trailers to commit messages — no Claude/AI co-author lines.
|
|
|
|
## Tailscale + SSH (userspace mode)
|
|
|
|
Some test servers require Tailscale for SSH access. To connect from this containerized environment:
|
|
|
|
1. **Start tailscaled in userspace mode** (no root, no TUN device needed):
|
|
```bash
|
|
tailscaled --state=/tmp/tailscale-state --tun=userspace-networking \
|
|
--socks5-server=localhost:1055 --socket=/tmp/tailscale-run/tailscaled.sock &>/tmp/tailscaled.log &
|
|
```
|
|
|
|
2. **Authenticate** using an auth key from `test-ssh/.testenv`:
|
|
```bash
|
|
source test-ssh/.testenv
|
|
tailscale --socket=/tmp/tailscale-run/tailscaled.sock up \
|
|
--authkey=$TS_AUTH_KEY --hostname=claude-recipe-maintainer
|
|
```
|
|
|
|
3. **SSH via the SOCKS5 proxy** — set `ALL_PROXY` before any SSH command:
|
|
```bash
|
|
export ALL_PROXY=socks5://localhost:1055
|
|
ssh -o StrictHostKeyChecking=no server.example.com "echo connected"
|
|
```
|
|
|
|
4. The SSH config in `test-ssh/ssh-config` should use `HostName` with the Tailscale IP (100.x.x.x) for servers that require Tailscale. Auth keys are stored in `test-ssh/.testenv` (not committed).
|
|
|
|
## OpenCode
|
|
|
|
If you are running in OpenCode, read `OPENCODE.md` for details on how skills and commands are configured.
|