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).
147 lines
6.0 KiB
Markdown
147 lines
6.0 KiB
Markdown
# Co-op Cloud Recipe Toolkit
|
|
|
|
Claude skills and tooling for working with [Co-op Cloud](https://coopcloud.tech) recipes — creating new recipes, updating existing ones, and testing deployments.
|
|
|
|
## Quickstart
|
|
|
|
```
|
|
git clone ssh://git@git.autonomic.zone:2222/notplants/recipe-maintainer.git
|
|
cd recipe-maintainer
|
|
claude
|
|
```
|
|
|
|
Then inside Claude, run:
|
|
|
|
```
|
|
/intro
|
|
```
|
|
|
|
This will walk you through the project and how to get started.
|
|
|
|
## Skills
|
|
|
|
These Claude Code slash commands automate common recipe maintenance tasks.
|
|
|
|
### Recipe lifecycle
|
|
|
|
| Skill | Description |
|
|
|-------|-------------|
|
|
| `/recipe-overview` | Check all recipes in `maintained-recipes.md` for available upgrades and recommend what to focus on |
|
|
| `/recipe-init <name>` | Bootstrap a new recipe — fetch, create test instance, set up `recipe-info/`, deploy |
|
|
| `/recipe-check <name>` | Quick status report — check if a recipe has upstream image upgrades available |
|
|
| `/recipe-upgrade-plan <name>` | Research release notes and write a detailed upgrade plan to `plans/` |
|
|
| `/recipe-upgrade-apply <name>` | Execute a planned upgrade — apply changes, deploy, test, commit and tag |
|
|
| `/recipe-new-tag <name>` | Bump the recipe version and create an annotated git tag |
|
|
| `/recipe-review <name>` | Audit a recipe against Co-op Cloud best practices |
|
|
| `/new-recipe-guide` | Step-by-step guide for developing a new recipe from scratch |
|
|
|
|
### Deployment and testing
|
|
|
|
| Skill | Description |
|
|
|-------|-------------|
|
|
| `/recipe-deploy <name>` | Deploy the local recipe checkout to the test instance with chaos mode |
|
|
| `/recipe-test <name>` | Run all Python test scripts from `recipe-info/<recipe>/tests/` |
|
|
| `/recipe-test-new <name>` | Test first-time initialization of a recipe from scratch |
|
|
| `/recipe-test-update <name>` | Test upgrading a recipe's test instance |
|
|
| `/recipe-test-backup <name>` | Test backing up and restoring a recipe's test instance |
|
|
| `/recipe-test-all` | Run tests for all maintained recipes, deploying each one at a time |
|
|
|
|
### Infrastructure and environment
|
|
|
|
| Skill | Description |
|
|
|-------|-------------|
|
|
| `/init-instance` | Deploy all maintained recipes to the active test instance from scratch |
|
|
| `/switch-default-instance` | Switch the default test instance (b1cc or t1cc) for all operations |
|
|
| `/test-setup` | Verify the test environment is configured correctly |
|
|
| `/test-context-reset` | Undeploy all apps from the test server except traefik |
|
|
| `/sync-secrets` | Sync Docker secrets from the test server into `recipe-info/testsecrets/` |
|
|
| `/t1cc-start` | Provision the t1cc DigitalOcean droplet (2 vCPU, 8 GB) and deploy Traefik |
|
|
| `/t1cc-stop` | Destroy the t1cc droplet (reserved IP is preserved, DNS unchanged) |
|
|
|
|
## Recommended workflow
|
|
|
|
### Daily check-in
|
|
|
|
```
|
|
/recipe-overview
|
|
```
|
|
|
|
Start here. This checks all your maintained recipes at once, shows what's up to date and what has upgrades available, and tells you which recipe to focus on.
|
|
|
|
### Setting up a new recipe
|
|
|
|
```
|
|
/recipe-init <recipe-name>
|
|
```
|
|
|
|
This creates the test instance, all the `recipe-info/` files, and deploys. After it finishes, verify with `/recipe-test` and add any recipe-specific test scripts to `recipe-info/<recipe>/tests/`.
|
|
|
|
### Checking for and applying upgrades
|
|
|
|
1. **Check** what's available:
|
|
```
|
|
/recipe-check <recipe-name>
|
|
```
|
|
Quick status report — see what upgrades exist and any breaking changes.
|
|
|
|
2. **Plan** the upgrade:
|
|
```
|
|
/recipe-upgrade-plan <recipe-name>
|
|
```
|
|
Creates a detailed plan file in `plans/`. Review it before proceeding.
|
|
|
|
3. **Apply** the plan:
|
|
```
|
|
/recipe-upgrade-apply <recipe-name>
|
|
```
|
|
Executes the plan — applies changes, deploys, tests, and commits + tags locally if everything passes.
|
|
|
|
4. **Push** when satisfied:
|
|
```
|
|
cd ~/.abra/recipes/<recipe-name> && git push && git push --tags
|
|
```
|
|
|
|
### Day-to-day development
|
|
|
|
When making local changes to a recipe (editing compose.yml, tweaking configs):
|
|
|
|
1. **Deploy** your changes:
|
|
```
|
|
/recipe-deploy <recipe-name>
|
|
```
|
|
|
|
2. **Test** the deployment:
|
|
```
|
|
/recipe-test <recipe-name>
|
|
```
|
|
|
|
## Test Environment Setup
|
|
|
|
This project is designed to run inside a container that bind-mounts `~/.abra`, creating an isolated environment where `abra` operates normally without access to the host's SSH keys or abra configuration.
|
|
|
|
### SSH keys and config
|
|
|
|
The `test-ssh/` folder must contain SSH keys and an SSH config that point to a server (or VM) running Co-op Cloud that is ready to be deployed to. The skills use this SSH config when connecting to the test server to deploy and manage recipe instances.
|
|
|
|
### Container isolation
|
|
|
|
Run this project in a container with `~/.abra` bind-mounted from the host or a dedicated volume. This ensures:
|
|
|
|
- `abra` finds its recipes, servers, and app state in the expected location (`~/.abra/`)
|
|
- The host's own SSH keys and abra configs are never exposed to the container
|
|
- The test SSH keys in `test-ssh/` are the only credentials available, limiting the blast radius of any deployment operations to the designated test server
|
|
|
|
## Structure
|
|
|
|
- **`recipe-info/`** — Per-recipe metadata, setup docs, and Python test scripts (organized by recipe name)
|
|
- **`lib/`** — Python library for interacting with `abra`, managing config, secrets, SSH, and recipe operations
|
|
- **`scripts/`** — Standalone Python scripts (test runner, context reset, secret sync, tag creation)
|
|
- **`utils/`** — SSO integration helpers and test utilities
|
|
- **`planned-updates/`** — Upgrade reports and summaries generated by `/recipe-upgrade-plan` and `/recipe-upgrade-apply`
|
|
- **`plans/`** — Detailed upgrade and project planning documents
|
|
- **`terraform/`** — Terraform config for provisioning a DigitalOcean test droplet
|
|
- **`test-ssh/`** — SSH config and keys for the test server
|
|
- **`docs.coopcloud.tech/`** — Local copy of the [Co-op Cloud documentation](https://docs.coopcloud.tech); reference for recipes, deployment patterns, and platform conventions
|
|
- **`.claude/commands/`** — Skill definitions for the slash commands above
|
|
- **`.opencode/`** — Thin wrapper mapping Claude skills to [OpenCode](https://opencode.ai) commands
|