First administrator
The first-run setup creates an instance administrator. Instance administrators can see all organizations, manage instance settings, manage user accounts, and install or remove plugins.
Additional users join through an invitation or through a configured identity provider.
Roles
Roles are scoped and inherited downward. A stronger role at an ancestor scope applies to every descendant resource.
Instance
| Role | Can do |
|---|---|
| Admin | Manage the instance, users, and installed plugins; read and manage every organization and space. |
Organization
| Role | Can do |
|---|---|
| Owner | Everything an organization admin can do, including managing other owners and deleting the organization. |
| Admin | Manage organization settings, spaces, sites, members, and plugins. |
| Member | Read the organization and the spaces they can access; write access comes from a space role. |
An organization member with an explicit space editor or admin grant can
write in that space.
Space
| Role | Can do |
|---|---|
| Admin | Manage the space, its members, plugin overrides, and site; write content. |
| Editor | Read and write pages, including change requests. |
| Viewer | Read pages and change requests. |
A user may have a direct role on one space without being a member of the organization. A space grant also permits reading the owning organization.
Invitations
Organization owners and admins can invite people from Organization settings > Members.
- Enter an email address if you want Docleus to send the invitation.
- Choose the organization role.
- Create the invitation.
- Copy the invitation link if email delivery is not configured, or share it through another trusted channel.
Invitations can be revoked before they are accepted. The invited role is granted when the person signs in or creates an account through the invitation. If the person already has a stronger role, Docleus keeps the stronger role.
To send invitation email, configure DOCLEUS_SMTP_URL and
DOCLEUS_SMTP_FROM. Without SMTP, invitations still work through the copyable
link.
Sign-in
Docleus supports password accounts by default. Passwords must be between 8 and 256 characters.
The browser uses an HttpOnly session cookie. API clients can use the session
token as a Bearer token instead. Cookie-authenticated writes include a
cross-site request check, which is why the proxy must preserve the original
host and protocol and why DOCLEUS_TRUST_PROXY=true is required behind a TLS
terminating proxy.
Failed sign-ins are rate-limited in the database, so the limit is shared by every web process using the same database.
OpenID Connect
The OIDC plugin is included in the default bundle but remains disabled until an identity provider is configured. A single provider can be configured through the environment:
DOCLEUS_OIDC_ISSUER=https://id.example.com
DOCLEUS_OIDC_CLIENT_ID=docleus
DOCLEUS_OIDC_CLIENT_SECRET=...
DOCLEUS_OIDC_LABEL="Company sign-in"Restart the container after changing the environment. Several providers can
be declared in the plugin configuration in /data/docleus.yaml.
Use the editor URL as the OIDC redirect origin and register the callback URL expected by the plugin in the identity provider. Keep the client secret in the environment or another secret store; do not commit it.
Access recommendations
- Keep the number of instance administrators small.
- Grant organization ownership only when another person must manage owners or delete the organization.
- Prefer direct space roles over broad organization write access.
- Remove departed users promptly and review pending invitations.
- Use a dedicated service account only when an automated integration requires one, and limit its grants to the resources it needs.