Add BMAD planning artifacts: brief, PRD, architecture, UX, spec, tickets
Includes the BMAD install config, the initiative ticket tree, the portal context-resources scripts, and the .gitignore change that tracks BMAD files (generated _bmad/render/ is ignored). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Sk72AxLwQnYttF6VFSxQLt
This commit is contained in:
Ebbe Baß
co-authored by
Claude Sonnet 5.5
Claude Sonnet 5.5
parent
97b2a95062
commit
24de5878ed
@@ -0,0 +1,40 @@
|
||||
---
|
||||
topic: ping-mee self-service portal
|
||||
updated: 2026-10-15T09:24
|
||||
---
|
||||
|
||||
|
||||
- (event) Create intent; coaching/fast mode not yet chosen. Stakes not yet read.
|
||||
- (decision) Context: ping-mee.de is the user's large homelab (Jellyfin etc.); users authenticate against homelab Active Directory (domain ping-mee.local).
|
||||
- (decision) Scope v1 (user words): users self-edit email, displayname, name, surname, profile picture, phone number.
|
||||
- (decision) Scope v1: announcement feature so admin can announce planned downtimes and changes.
|
||||
- (decision) Design: resembles classic Microsoft web UI. Login via LDAPS.
|
||||
- (event) User supplied context-resources/*.ps1: existing profile-picture pipeline (fileshare source -> AD thumbnailPhoto/jpegPhoto/photo at 96px <=100KB -> Windows logon script builds account picture sizes, 448px HQ copy from share).
|
||||
- (decision) Users: family and friends, ~10 people. Yet wants polished and protected 'for big deployments' (tension with right-sizing; to probe).
|
||||
- (decision) Pictures: portal drops files on the fileshare (existing sync task does the AD write); portal renames to <username>.jpg if not already named so. Portal does NOT write thumbnailPhoto itself.
|
||||
- (decision) AD writes (other attributes): portal uses a dedicated service account with delegated privileges.
|
||||
- (decision) Announcements: delivered by e-mail AND shown on an announcement page in the portal.
|
||||
- (decision) Design: Office 365 (Fluent) look, not OWA 2010/Aero.
|
||||
- (decision) Stakes: homelab use first, keep option to deploy elsewhere someday (=> no hardcoded domain/OU/share paths).
|
||||
- (decision) Everything configurable, nothing baked in (domain, OU, paths, groups, SMTP, theme). Portal reachable from the INTERNET. No multi-domain. Admin UI wanted: upload backgrounds, change themes, settings.
|
||||
- (decision) Pictures: portal converts to JPEG, scales/sizes to need; user message 'updated within ~2 hours' (sync-task latency).
|
||||
- (decision) Writable scope: OU=Clients,OU=Organisation,DC=ping-mee,DC=local (configurable). Attributes: sn, displayName, givenName, mail, name, cn. Mail change requires confirmation e-mail.
|
||||
- (assumption) GAP: phone number was in the original request but is not in the attribute list (telephoneNumber/mobile?). Also name/cn are the RDN: changing needs ModifyDN, not attribute modify.
|
||||
- (decision) Announcements: publishers = members of a configurable AD group; SMTP server configurable (IONOS); opt-out/opt-in for e-mails wanted; one-way text primary, scheduled downtime window / severity / expiry as OPTIONAL features.
|
||||
- (decision) Deployment: Docker container on a Linux box.
|
||||
- (decision) Phone: both telephoneNumber and mobile. name and cn REMOVED from concept (no RDN renames).
|
||||
- (decision) Behind reverse proxy (TLS there). Login throttling wanted. Asked: authentik IdP between AD and portal as option (user has an authentik server).
|
||||
- (decision) Scope: ship everything (user: not a rational project, homelab is oversized by design). No phasing imposed; sequencing left to downstream.
|
||||
- (decision) E-mail announcements: default opt-IN; on opt-out user is told they won't get downtime notifications and can opt back in via portal.
|
||||
- (decision) Secrets via Docker environment variables.
|
||||
- (decision) NEW SCOPE: password change by users at any time (admin currently resets manually) - core success criterion. Success = no manual password resets AND one clean all-in-one package solving these homelab problems.
|
||||
- (decision) Password: users can CHANGE only (current+new); reset stays a manual admin process (out of scope). E-mail change requires current password + confirmation e-mail. Users with expired/must-change passwords can still log in (mechanism unresolved with OIDC).
|
||||
- (decision) Login via OIDC (authentik) for initial authentication only; all writes stay LDAPS with service account. Prefers OIDC over LDAPS login.
|
||||
- (decision) Problems solved: password change, profile info, profile pictures, announcement channel. 'Clean' = no good solution exists for these today; one all-in-one package. PowerShell scripts (sync, logon, registry) stay.
|
||||
- (decision) Mode: FAST PATH chosen. Draft brief with [ASSUMPTION] tags.
|
||||
- (assumption) Success criterion tension: forgotten passwords still need manual reset by admin, so 'no manual password work' only holds for known-password changes.
|
||||
- (assumption) Expired-password login: authentik/AD OIDC login likely fails for expired passwords; mechanism needs design.
|
||||
- (decision) Expired-password behavior with authentik unknown; to be tested. Password change confirmed: user enters current+new in portal, applied over LDAPS.
|
||||
- (decision) Security success criterion: no injections, no session takeover, no cross-user read/write, throttled logins.
|
||||
- (change) Draft v1 written: brief.md + addendum.md; security criterion made concrete, open question on expired passwords reworded.
|
||||
- (event) Polish pass (bmad-review structure+prose) applied; brief status set to final.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Addendum: Technical Context for Downstream Documents
|
||||
|
||||
## Existing picture pipeline (context-resources/)
|
||||
- `AD-ProfilePicture-Sync.ps1` (DC, scheduled task): reads `<sam>.jpg` from the fileshare source folder, falls back to a default image, writes a 96px copy and a 448px copy to a processed folder, and sets `thumbnailPhoto`, `jpegPhoto` and `photo` in AD from the 96px copy (limit 100 KB). It writes MD5 files for change detection but does not yet compare them, so every run reprocesses every user. Target OU in the script: `OU=Organisation,DC=ping-mee,DC=local`.
|
||||
- `Set-LocalAccountPicture.ps1` (user logon script): reads `thumbnailPhoto` and builds Windows account-picture sizes (32, 40, 48, 96, 192, 200, 240, 448). Large sizes use the 448px copy from the share. It uses `$roamingDir` before defining it, which is a bug.
|
||||
- `Set-AccountPictureRegistry-System.ps1` (startup): applies registry entries from manifests left by the logon script.
|
||||
- The portal's job is only to put a correct `<username>.jpg` in the share's source folder. Format, size and naming constraints come from these scripts.
|
||||
|
||||
## AD write scope
|
||||
- Writable OU: `OU=Clients,OU=Organisation,DC=ping-mee,DC=local` (configurable).
|
||||
- Attributes: `givenName`, `sn`, `displayName`, `mail`, `telephoneNumber`, `mobile`. Password via the AD password mechanism over LDAPS.
|
||||
- Rejected: editing `cn` and `name`. They are the object's RDN and would need ModifyDN renames, which change the DN and risk breaking apps.
|
||||
|
||||
## Security notes raised during discovery
|
||||
- Internet exposure plus LDAP binds can lock AD accounts if an attacker hammers logins. Throttling must sit in front of any bind. OIDC via authentik moves the first factor there.
|
||||
- E-mail change feeds announcements and any future reset path. Chain risk: hijacked session, then e-mail change. Mitigated by requiring the current password and a confirmation link.
|
||||
- Secrets (service account, SMTP) come from Docker environment variables, not the admin UI.
|
||||
|
||||
## Integrations
|
||||
- IdP: authentik via OIDC. Keep it generic OIDC so other providers work. Not verified: whether authentik can write passwords back to AD. The portal does not rely on it.
|
||||
- Mail: configurable SMTP, IONOS in the homelab.
|
||||
- Reverse proxy in front terminates TLS.
|
||||
|
||||
## Design
|
||||
- Office 365 (Fluent) look, not OWA 2010 or Windows 7 Aero. Admin can change theme and upload backgrounds.
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: "Product Brief: ping-mee Self-Service Portal"
|
||||
status: final
|
||||
created: 2026-10-15
|
||||
updated: 2026-10-15
|
||||
---
|
||||
|
||||
# Product Brief: ping-mee Self-Service Portal
|
||||
|
||||
## Executive Summary
|
||||
|
||||
ping-mee.de is a large homelab that family and friends use, around ten people, for services such as Jellyfin. All accounts live in one Active Directory. Today, almost anything a user wants changed (a password, a name, a phone number, a profile picture) means asking the admin. There is also no good place to tell everyone about planned downtime.
|
||||
|
||||
The ping-mee Self-Service Portal is a single web application that closes those gaps. Signed-in users change their own password and profile details and upload a profile picture. The admin publishes announcements that reach users by e-mail and on a page in the portal. It is built for the homelab first, reachable from the internet behind the existing reverse proxy, and configurable enough to run elsewhere later. The homelab is deliberately oversized for ten users, and so is this project. That is part of its purpose, not an accident.
|
||||
|
||||
## The Problem
|
||||
|
||||
- **Password changes are manual.** A user who wants a new password has to ask the admin. This is the main pain.
|
||||
- **Profile data is admin-maintained.** Name, display name, e-mail and phone are edited by hand in AD.
|
||||
- **Profile pictures are awkward.** The pipeline works (a file on a share, a scheduled sync to AD, a logon script on Windows clients), but a user has no way to supply the file themselves.
|
||||
- **No announcement channel.** There is no single place to announce downtime or changes.
|
||||
- **No existing tool fits.** Nothing handles these four things together, cleanly, in an AD-based homelab.
|
||||
|
||||
## The Solution
|
||||
|
||||
One portal, one login. After signing in through the existing authentik server (OIDC), a user can:
|
||||
|
||||
- **Change their password** by entering the current one and a new one.
|
||||
- **Edit profile data**: first name, last name, display name, e-mail, telephone number and mobile number.
|
||||
- **Upload a picture.** The portal converts it to a JPEG sized for the pipeline and writes `<username>.jpg` to the fileshare. The existing PowerShell sync then updates AD within roughly two hours, and the portal tells the user so.
|
||||
- **Read announcements** on a page in the portal, and receive them by e-mail.
|
||||
|
||||
Changing an e-mail address needs the current password and a confirmation link sent to the new address. Members of a configurable AD group can publish announcements. The admin has a UI to manage themes, background images and settings. The look follows Office 365.
|
||||
|
||||
All writes to AD go through LDAPS with a dedicated service account that is limited to a configurable OU and a short list of attributes.
|
||||
|
||||
## What Makes This Different
|
||||
|
||||
There is no moat. The value is fit and cleanliness: a portal built around this exact setup (AD, authentik, the existing picture pipeline) that does four things well in one container, instead of four partial solutions. It is also configurable throughout, so it is not tied to one domain.
|
||||
|
||||
## Who This Serves
|
||||
|
||||
- **Users** are about ten family members and friends of the homelab, with mixed technical skill. They want to change their own details without asking anyone.
|
||||
- **The admin** (the homelab owner) wants to stop doing manual password and profile changes and wants an announcement channel. This person is also the main builder and operator.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Users change their own passwords without admin involvement. [ASSUMPTION: "manual" means known-password changes only; forgotten passwords stay manual, see Open Questions.]
|
||||
- Users update their own profile fields and pictures without admin involvement.
|
||||
- Every planned downtime or change can be announced through the portal, and opted-in users receive it by e-mail.
|
||||
- Nothing is hard-coded to ping-mee: domain, OU, group, share path, SMTP and theme all come from configuration.
|
||||
- The portal runs safely on the internet. Concretely: injection attacks (LDAP, SQL, script) do not work, a stolen or hijacked session does not give lasting access, and a signed-in user can never read or write another user's data. Logins are throttled.
|
||||
|
||||
## Scope
|
||||
|
||||
**In for the first version (everything below is wanted, sequencing is for later):**
|
||||
- Login via OIDC (authentik).
|
||||
- Password change with the current password.
|
||||
- Profile edit for `givenName`, `sn`, `displayName`, `mail`, `telephoneNumber` and `mobile`.
|
||||
- E-mail change with password and confirmation link.
|
||||
- Picture upload, conversion and rename to `<username>.jpg` on the share.
|
||||
- Announcements: text, e-mail and portal page, with user opt-in (default) and opt-out. Opting out shows a notice that downtime notifications will stop and that the user can opt back in. Severity, downtime windows and expiry are optional features.
|
||||
- Admin UI for themes, backgrounds and non-secret settings.
|
||||
- Configuration and secrets via Docker environment variables.
|
||||
- Delivery as a Docker container on a Linux host.
|
||||
- Login throttling.
|
||||
|
||||
**Out:**
|
||||
- Password reset for forgotten passwords. The admin does this manually.
|
||||
- Editing `cn` or `name`, which means no object renames.
|
||||
- Multi-domain support.
|
||||
- Replacing the PowerShell scripts, which stay as they are.
|
||||
|
||||
## Open Questions and Risks
|
||||
|
||||
- **Expired passwords.** The admin wants users with expired or "must change" passwords to still be able to log in and change them. Login goes through authentik, and it may refuse those users. How authentik behaves here is unknown and has to be tested before the design is fixed.
|
||||
- **Forgotten passwords.** They still need the admin, so "no manual password work" is only partly true. Confirm that this is acceptable.
|
||||
- **Internet exposure.** The portal holds an AD service account and is reachable from outside. This is the largest risk and gets its own design attention.
|
||||
- **Scope.** Shipping everything in one go delays the first benefit to users.
|
||||
|
||||
## Vision
|
||||
|
||||
A single, polished home for everything a user needs from the homelab's identity system, and the first place the admin looks when something changes. If it works well in this homelab, it could be released for other AD-based homelabs, because nothing in it assumes ping-mee.
|
||||
Reference in New Issue
Block a user