recipe-maintainers/recipe-maintainer
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
460eba090ba6765b05a929d32d16ca984cf66e5a
recipe-maintainer/.claude/commands/includes/guidelines.md
autonomic-bot f283a371bb recipe-maintainer: public snapshot (secrets + deployment plans removed, single commit) 
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).
2026-06-16 20:18:24 +00:00

2.3 KiB
Raw Blame History

Guidelines

Read and follow these guidelines for all recipe operations.

Preserving local recipe changes

Before running abra recipe fetch <recipe> --force, always check for uncommitted changes first:

git -C ~/.abra/recipes/<recipe> status --short
  • If the working tree is clean: proceed with abra recipe fetch <recipe> --force to pull the latest upstream.
  • If there are uncommitted changes: do NOT fetch. Log that the recipe has local modifications and that you are using the local checkout as-is. Use --chaos on any subsequent abra app commands so they pick up the local state instead of requiring a committed version.

This matters because --force overwrites the entire local checkout, destroying any in-progress work.

Recipe version format

Recipe versions use the format <recipe-semver>+v<upstream-version>, for example 0.2.6+v4.5.0. The v prefix before the upstream version is always present, even if the upstream image tag uses a different prefix (e.g. CryptPad's Docker tag version-2025.9.0 becomes +v2025.9.0 in the recipe version).

This version string appears in three places that must stay in sync:

  1. The coop-cloud.${STACK_NAME}.version deploy label in compose.yml
  2. The annotated git tag on the release commit
  3. The TYPE=<recipe>:<version> line in the app's .env file on the server

Co-op Cloud requires annotated tags (not lightweight tags). Always use git tag -a with a -m message:

git tag -a "0.5.0+v2026.2.0" -m "chore: publish 0.5.0+v2026.2.0 release"

Saving secrets locally

When generating secrets for an app, always use --machine to get machine-readable output and save it to recipe-info/<recipe>/secrets.json:

abra app secret generate <domain> --all --machine > recipe-info/<recipe>/secrets.json

This keeps a local record of the generated secrets (e.g. admin passwords needed for initial login). The --machine flag outputs JSON instead of a human-readable table.

Active test instance

The current active test instance is set by default_instance in settings.toml at the workspace root. Read this value directly to determine which instance to operate on. The instance's server and domain_suffix are in the [instances.<name>] section. Domain for any recipe is <recipe>.<domain_suffix>.