Files
Homelab-manager/ROLES.md
T
bobbanandClaude Sonnet 5.5 c17e9aa140 Add runbooks, backup coverage, inventory, roles from groups, Prometheus metrics and event webhooks
- Runbooks: notes per server/integration, shown next to matching alerts
- Backup coverage page across Proxmox and PBS, with a digest section
- Hardware inventory with warranty, power and running cost
- Authentik group to role mapping with preview and safeguards
- /metrics (bearer token) and signed outgoing event webhooks
- Docs: README, DATABASE, NOTIFICATIONS, ROLES and new API.md

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-17 20:41:00 +02:00

5.3 KiB

Roles & menu access

Homelab Manager has three roles, ranked lowest to highest: viewer, operator, admin. The first person to sign in becomes admin; everyone after that starts as viewer until an admin changes their role under Administration → Users.

A role can do everything the roles below it can, plus what's listed for it — operator includes everything viewer has, admin includes everything operator has.

Sidebar menu, by role

✅ = the menu item appears for that role · ❌ = it's hidden entirely (not just disabled) — a group that would end up with zero visible items disappears too, and a group left with exactly one just shows as that page's own top-level link.

Menu item Path Viewer Operator Admin
Dashboard / ✅ ✅ ✅
Infrastructure
Servers /servers ✅ ✅ ✅
Proxmox /proxmox ✅ ✅ ✅
Synology /synology ✅ ✅ ✅
Proxmox Backup /pbs ✅ ✅ ✅
Backup coverage /backups ✅ ✅ ✅
Inventory /inventory ✅ ✅ ✅
Docker /docker ✅ ✅ ✅
Tailscale /tailscale ✅ ✅ ✅
Network
DNS /dns ✅ ✅ ✅
Domains /domains ✅ ✅ ✅
IP Addresses /ipam ✅ ✅ ✅
Ports /ports ✅ ✅ ✅
Consistency /consistency ✅ ✅ ✅
Automation
Semaphore /semaphore ✅ ✅ ✅
Gitea /gitea ✅ ✅ ✅
Secrets /secrets ✅ ✅ ✅
Operations
Alerts /alerts ✅ ✅ ✅
Maintenance /maintenance ✅ ✅ ✅
Updates /updates ✅ ✅ ✅
Uptime Kuma /uptime-kuma ✅ ✅ ✅
osTicket /osticket ✅ ✅ ✅
Admin Links /admin-links ✅ ✅ ✅
Generator /generator ✅ ✅ ✅
Administration
Integrations /integrations ✅ ✅ ✅
Users /users ❌ ❌ ✅
Sessions /sessions ❌ ❌ ✅
Audit Log /audit-log ❌ ✅ ✅
Diagnostic Log /diag-log ❌ ❌ ✅
Settings /settings ❌ ❌ ✅
Privacy (footer link, not in a group) /privacy ✅ ✅ ✅

So in practice: every page is visible to every role except the five under Administration — Users, Sessions, and Diagnostic Log need admin; Audit Log needs operator or admin; Settings needs admin.

Being able to see a page isn't the same as being able to change things

Almost every page above is visible to viewers, but most of the buttons on them aren't — a viewer can look at everything but can't act on anything. Operators can use the page's normal working actions (starting a container, syncing DNS, adding a secret, opening a maintenance window…). Some actions on otherwise-viewer-visible pages are held back even further, to admin only:

  • Integrations & DNS providers: any operator can use an integration once it's configured (start/stop a guest, run a template, sync DNS records, etc.), but adding, editing, testing, or deleting an integration or DNS provider is admin-only.
  • Servers: registering a new server, rotating its agent token, and editing/deleting a server are admin-only; tagging a server and linking/unlinking it to a Proxmox guest just need operator.
  • Tags: creating, renaming, recoloring, or deleting a tag is admin-only (applying an existing tag to a server needs operator).
  • Ports: everyone can see both the agent-reported and manual tables; adding, editing, or deleting a manual port opening needs operator.
  • Admin Links: everyone can see and open every server's admin bookmarks, from that server's own page or the summary page; adding, editing, or removing one needs operator, from either place.
  • Generator: everyone can use it; the name lists it picks server names from are edited under Settings → Names, which is admin-only (and so is importing names from Skatteverket).
  • Alert tickets: everyone sees which alerts have an osTicket ticket (a badge on the Alerts page, linking to the ticket in osTicket); switching the feature on, choosing what opens a ticket, and sending a test ticket are under Settings → Alert tickets, which is admin-only.
  • Runbooks: everyone reads them (on a server's page, an integration's card, next to an alert); writing, editing and removing one needs operator.
  • Inventory: everyone can see the hardware; adding, editing and removing needs operator; the price of power used for the running cost is admin-only.
  • Backup coverage and Updates are read-only pages for everyone.
  • Sign-in groups, metrics tokens, event webhooks and share links are all under Settings, so admin-only; /metrics itself needs a metrics token, not a login.
  • Everything under Settings (notification channels, badge colors, display prefs, log retention, backup/restore) is admin-only, matching the page itself being admin-only.

If you need the exact role for one specific button rather than this summary, check the corresponding route in server/src/routes/ — each one that needs more than "signed in" calls requireRole("operator") or requireRole("admin") right where that action is defined.