mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 02:54:26 +00:00
kevinveenbirkenbachandClaude Opus 5
ef5ea7cb55
meta/schema.yml held credential definitions and their runtime values, but the name said 'schema' and read like structural metadata next to services.yml and volumes.yml. Nothing in the file is a schema in the sense the other meta files use the word, and a contributor had to open it to learn it holds secrets. 62 role files renamed. ROLE_FILE_META_SCHEMA becomes ROLE_FILE_META_SECRETS and keeps its role as the SPOT the path is built from. Two readers bypassed that constant and spelled the name themselves: utils/cache/applications.py built meta_dir / 'schema.yml' twice, and plugins/lookup/application_gid.py carries the filename in the marker list it detects application roles by. Left behind, the rename would not have raised — credentials would have resolved empty and the role would have stopped counting as an application. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
158 lines
6.8 KiB
Markdown
158 lines
6.8 KiB
Markdown
## Summary
|
|
|
|
Briefly describe the `web-*` change and the expected user-facing outcome.
|
|
|
|
Examples:
|
|
|
|
* Add a new `web-app-*` role
|
|
* Fix a broken login, bootstrap, or integration flow in an existing `web-*` role
|
|
* Introduce SSO or mail integration for an existing `web-*` role
|
|
* Extend bootstrap or deployment behavior for a server-facing application
|
|
|
|
---
|
|
|
|
## Template Type
|
|
|
|
Select the primary intent of this PR:
|
|
|
|
* [ ] **Feature** - Adds or extends server functionality
|
|
* [ ] **Fix** - Repairs broken or incorrect server behavior
|
|
|
|
---
|
|
|
|
## Affected Roles and Services
|
|
|
|
List the impacted roles and related services.
|
|
|
|
* Primary `web-*` role(s):
|
|
* Related `web-svc-*`, `sys-front-*`, `svc-db-*`, auth, mail, proxy, or storage role(s):
|
|
|
|
## Preferred Integrations
|
|
|
|
Integrate the change into the following services when possible:
|
|
|
|
* [ ] Dashboard
|
|
* [ ] Matomo
|
|
* [ ] OIDC
|
|
* [ ] LDAP
|
|
* [ ] Logout
|
|
|
|
---
|
|
|
|
## Roles (optional `🧩 Subset` CI scope)
|
|
|
|
Optional. Ignored unless a maintainer applies the **🧩 Subset** label; without the label CI uses the diff-derived role set as usual. When the label is set, CI deploys **only** the roles listed here — each must be an existing `roles/<id>` directory, or the run fails. See [pipeline.md](../../docs/contributing/artefact/git/pipeline.md#subset-label-).
|
|
|
|
```yaml
|
|
roles:
|
|
# - web-app-nextcloud
|
|
# - web-app-matomo
|
|
# - sys-version
|
|
```
|
|
|
|
---
|
|
|
|
## Change Type
|
|
|
|
Select the semantic version impact of this change:
|
|
|
|
* [ ] **Major** - Breaking change
|
|
* [ ] **Minor** - New backwards-compatible feature
|
|
* [ ] **Patch** - Small improvement or compatible adjustment
|
|
|
|
---
|
|
|
|
## Change Details
|
|
|
|
Explain what changed and why.
|
|
|
|
Key points:
|
|
|
|
* What problem does this solve?
|
|
* Which upstream image or service version was used or changed?
|
|
* How do login, logout, proxying, storage, or mail integration behave after this change?
|
|
* Which alternatives were considered?
|
|
|
|
---
|
|
|
|
## File Checklist
|
|
|
|
Check the relevant rows and explain intentional omissions in `Additional Notes`.
|
|
|
|
| Check | Item | When to include | Purpose |
|
|
|---|---|---|---|
|
|
| [ ] | `README.md` | Usually | Documents role-specific usage, setup notes, and contributor context. |
|
|
| [ ] | `meta/main.yml` | Usually | Declares Ansible Galaxy info and `dependencies:`. No project-internal `run_after:` / `lifecycle:` (those live on the primary entity in `meta/services.yml`). |
|
|
| [ ] | `vars/main.yml` | Usually | Defines the shared fixed role variables as the main source of truth. |
|
|
| [ ] | `meta/services.yml` | Usually | Per-entity service config (file root IS the services map keyed by `<entity_name>`). Holds image/version, `ports.{internal,local,public}`, `run_after`/`lifecycle` on the primary entity, plus inlined per-service settings. |
|
|
| [ ] | `meta/server.yml` | Usually | Server-level config (file root IS `applications.<app>.server`). CSP, `domains`, `status_codes`, plus the per-role `networks.local.{subnet,dns_resolver}`. |
|
|
| [ ] | `meta/rbac.yml` | When the role declares RBAC | RBAC declarations (file root IS `applications.<app>.rbac`). |
|
|
| [ ] | `meta/volumes.yml` | When the role declares Compose volumes | Volumes map (file root IS the volumes map; no `compose:`/`volumes:` wrapper). |
|
|
| [ ] | `meta/secrets.yml` | When the role declares credentials | Credential schema with optional `default:` field. |
|
|
| [ ] | `tasks/main.yml` | Usually | Acts as the role entry point and includes the main task flow. |
|
|
| [ ] | `templates/compose.yml.j2` | For containerized app roles | Defines the service, volume, environment, port, and network wiring. |
|
|
| [ ] | `templates/env.j2` | When the app uses environment files | Renders the app environment configuration. |
|
|
| [ ] | `templates/style.css.j2` or `files/style.css` | When the role injects custom branding or theming | Defines the role-local CSS overrides that adapt the UI to the repository design system. See [Contributing `style.css`](../../docs/contributing/artefact/files/role/style.css.md). |
|
|
| [ ] | `templates/javascript.js.j2` or `files/javascript.js` | When the role injects custom frontend behavior | Defines the role-local JavaScript that adapts UI behavior or integration glue in the browser. See [Contributing `javascript.js`](../../docs/contributing/artefact/files/role/javascript.js.md). |
|
|
| [ ] | `meta/users.yml` | When the role bootstraps users or identities | Role-local user definitions (file root IS the users map; no `users:` wrapper). |
|
|
| [ ] | `files/Dockerfile` | When a custom image is required | Provides a custom image build path. Prefer this over `Dockerfile.j2`. |
|
|
| [ ] | `templates/playwright.env.j2` | When Playwright coverage is included | Configures the Playwright test environment. See [Contributing `playwright.env.j2`](../../docs/agents/files/role/playwright.env.j2.md). |
|
|
| [ ] | `files/playwright/playwright.spec.js` | When Playwright coverage is included | Defines the Playwright login and logout test flow. See [Contributing `playwright.spec.js`](../../docs/contributing/artefact/files/role/playwright.specs.js.md). |
|
|
|
|
### Registered
|
|
|
|
| Check | Item | When to include | Purpose |
|
|
|---|---|---|---|
|
|
| [ ] | Per-entity ports in `meta/services.yml.<entity>.ports.{internal,local,public}` | When the app exposes a service | Confirms that the app's host-bound ports are declared on the entity that exposes them. Use `cli meta ports suggest` to pick free slots inside the appropriate `PORT_BANDS.<scope>.<category>` from `group_vars/all/08_networks.yml`. |
|
|
| [ ] | Per-role subnet in `meta/server.yml.networks.local.subnet` | When the app communicates over container networks | Confirms that the role's docker network CIDR is declared. Use `cli meta networks suggest --clients N` to pick a free subnet. |
|
|
|
|
---
|
|
|
|
## Local Validation
|
|
|
|
Describe how the change was validated locally.
|
|
|
|
* [ ] Deployment target and distro documented
|
|
* [ ] Playwright test run documented
|
|
* [ ] Login flow tested
|
|
* [ ] Logout flow tested
|
|
* [ ] Screenshot attached when the change is user-visible
|
|
|
|
---
|
|
|
|
## Security Impact
|
|
|
|
Indicate whether this change has security implications.
|
|
|
|
* [ ] No relevant security impact
|
|
* [ ] Security impact present
|
|
|
|
If security impact is present, explain:
|
|
|
|
* Affected auth, TLS, permissions, secrets, headers, or exposed surfaces:
|
|
* Risk reduction, new exposure, or compatibility considerations:
|
|
* Security-specific validation performed:
|
|
|
|
---
|
|
|
|
## Review Focus
|
|
|
|
Help reviewers focus on the riskiest parts of this PR.
|
|
For repository-wide contribution and review expectations, see [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
|
|
|
* Highest-risk files, roles, or flows:
|
|
* Migration, rollback, or security-sensitive concerns:
|
|
* Specific feedback requested from reviewers:
|
|
|
|
---
|
|
|
|
## Definition of Done (DoD)
|
|
|
|
* [ ] The implementation follows the Definition of Done, and the contribution guidelines in [CONTRIBUTING.md](../../CONTRIBUTING.md) were considered and applied during implementation.
|
|
|
|
---
|
|
|
|
## Additional Notes
|
|
|
|
Add any reviewer context that is useful for deployment, rollback, or follow-up work.
|