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).
46 lines
2.3 KiB
Markdown
46 lines
2.3 KiB
Markdown
## 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>`.
|