Ebbe BaßandClaude Sonnet 5.5
24de5878ed
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
84 lines
6.0 KiB
Markdown
84 lines
6.0 KiB
Markdown
---
|
|
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.
|