Skip to content

Add a user reporting page for the opencloud report command - #1390

Open
schweigisito wants to merge 3 commits into
mainfrom
document-report-command
Open

schweigisito wants to merge 3 commits into
mainfrom
document-report-command

Conversation

@schweigisito

@schweigisito schweigisito commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Adds a User Reporting page under Admin > Maintenance in the rolling version, documenting the opencloud report command.

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 and cs3. Where the backend does accept the write but nobody has signed in yet, the counts are N/A rather than 0, and that distinction is given per output format.

Two further sections cover 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.

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-in as 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:

kubectl exec -n <namespace> deploy/<release>-api -- opencloud report

Open point

The availability note is a placeholder. It needs the release that first ships opencloud report before this page goes out.

Checks

markdownlint-cli2 and prettier --check pass, and a full docusaurus build succeeds 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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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
schweigisito force-pushed the document-report-command branch from 0d9b5f4 to a377462 Compare November 17, 2026 16:18

@Svanvith Svanvith left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants