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.

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`.
[ ]	`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`.
[ ]	`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`.
[ ]	`files/playwright/playwright.spec.js`	When Playwright coverage is included	Defines the Playwright login and logout test flow. See Contributing `playwright.spec.js`.

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.

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 were considered and applied during implementation.

Additional Notes¶

Add any reviewer context that is useful for deployment, rollback, or follow-up work.