Repository navigation
Add a user reporting page for the opencloud report command - #1390
Open
schweigisito wants to merge 3 commits into
Open
schweigisito wants to merge 3 commits into
schweigisito wants to merge 3 commits into
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The documentation omits a Helm deployment limitation, contains inconsistent report examples, and mischaracterizes timestamp availability and zero recorded sign-ins, potentially misleading administrators.
4 open issues
What changed in this PR
Adds a User Reporting page under Admin > Maintenance in the rolling documentation for the opencloud report command introduced by opencloud-eu/opencloud#4034.
Changes:
- Documents invocation, options, and user counts grouped by role.
- Provides table and machine-readable output examples, including
--skip-sign-in. - Explains LDAP sign-in recording and the distinction between unavailable counts and zero.
| File | Description |
|---|---|
docs/admin/maintenance/user-reporting.md |
Adds command usage, output examples, and LDAP reporting guidance. |
Review effort: Balanced
Comment on lines
+25
to
+27
| The command talks to the services of the instance through the shared service registry, so it has to | ||
| run next to them, not from a remote machine. With Docker Compose, run it inside the OpenCloud | ||
| container as described in [Maintenance Commands](./maintenance-commands.md): |
| "usersWithSignInData": 3, | ||
| "roles": [ | ||
| { "role": "User", "users": 3, "signedIn": 1 }, | ||
| { "role": "Admin", "users": 2, "signedIn": 1 } |
Comment on lines
+143
to
+145
| Whether the sign-in columns hold numbers or `N/A` depends entirely on whether OpenCloud may write to | ||
| the LDAP directory. OpenCloud keeps no database of its own for this: the timestamp of the last | ||
| successful sign-in is stored as an attribute on the user entry in the directory. |
Comment on lines
+241
to
+243
| A role showing `0` on an instance whose other roles show numbers is a genuine finding: those accounts | ||
| exist and were not used inside the window. A report showing `N/A` everywhere is a statement about the | ||
| deployment, not about the users. |
Document opencloud report under Admin > Maintenance: how to run it, what it counts, its options, and the machine readable output. The main part explains why the sign-in counts depend on the LDAP integration. OpenCloud stores the last successful sign-in as an attribute on the user entry, so a directory that OpenCloud may not write to records nothing and the report has to report N/A rather than 0. Both modes are described side by side, with OC_LDAP_SERVER_WRITE_ENABLED as the switch. Two sections cover the operational flags: raising the time budget with -t/--timeout on an instance with many users, and --insecure where OC_HTTP_TLS_ENABLED is on with a generated self-signed certificate. The (no role assigned) bucket gets an explanation of its own: where roles are assigned on first sign-in it mostly holds accounts that were provisioned but never used, and a failed role lookup puts a user in the same bucket without the report being able to tell. Assisted-by: Claude Code:claude-opus-5
schweigisito
force-pushed
the
document-report-command
branch
from
November 17, 2026 16:18
0d9b5f4 to
a377462
Compare
The default behaviour of opencloud report has flipped: it no longer reports sign-ins unless asked. The page led with the sign-in window and described --skip-sign-in as the way out of it, which is now backwards. The page now leads with the plain user count per role, and a section of its own covers --with-sign-in: what it adds, that it needs an LDAP identity backend OpenCloud may write to, and the two refusals it can produce, read-only LDAP and cs3. N/A against 0 now only arises within --with-sign-in, on a writable backend where nobody has a recorded sign-in yet, so that part moved under the new section and the warning it describes was reworded to match. The options table gained --with-sign-in and notes that --days only applies together with it. Assisted-by: Claude Code:claude-opus-5
The page explained that the command finds the services through the shared service registry. It no longer does: it falls back to the configured gateway and graph addresses when the registry holds no entry, which is what a Helm deployment with an external NATS endpoint looks like. Say that it talks to the two services directly instead, keep the point that it has to run next to them, since that is still true and is why the fallback can use loopback, and add the invocation for Kubernetes. Assisted-by: Claude Code:claude-opus-5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Adds a User Reporting page under Admin > Maintenance in the rolling version, documenting the
opencloud reportcommand.Depends on
opencloud-eu/opencloud#4034 adds the command this page describes.
Do not merge this before that PR. Until it lands, this page documents a command that exists in no release, and the availability note below has nothing to point at.
Contents
How to run the report on Docker Compose, a single binary and Kubernetes, what it counts, all five options, and the machine readable output.
The page leads with the default, a plain user count per role, because that is what the command does without any flags. A section of its own covers
--with-sign-in: what it adds, that it needs an LDAP identity backend OpenCloud may write to, and both refusals it can produce, read-only LDAP andcs3. Where the backend does accept the write but nobody has signed in yet, the counts areN/Arather than0, and that distinction is given per output format.Two further sections cover raising the time budget with
-t/--timeouton an instance with many users, and--insecurewhereOC_HTTP_TLS_ENABLEDis on with a generated self-signed certificate.Following the review on opencloud-eu/opencloud#4034, the page also explains the
(no role assigned)bucket: where roles are assigned on first sign-in it mostly holds provisioned but never used accounts, and a failed role lookup puts a user in the same bucket without the report being able to tell.Commits
The second commit rewrites the page for the flipped default, since the first version led with the sign-in window and described
--skip-sign-inas the way out of it.The third corrects how the command finds the services. The page said it uses the shared service registry, which stopped being true once the command gained a fallback to the configured gateway and graph addresses. That fallback is what makes it work in a Helm deployment, so the page now gives the Kubernetes invocation as well:
Open point
The availability note is a placeholder. It needs the release that first ships
opencloud reportbefore this page goes out.Checks
markdownlint-cli2andprettier --checkpass, and a fulldocusaurus buildsucceeds for both locales, so the internal links and the in-page anchor are verified.AI assistance: Claude Code (claude-opus-5) wrote the page and this description.