OpenCloud File Sharing

Overview

Self-hosted file sharing and collaboration platform. Keycloak handles authentication via OIDC (realm internal). Collabora Online enables in-browser editing of office documents.

URLs:

Both records are DNS only, bypassing the Cloudflare proxy — reference Cloudflare DNS.

Module: modules/features/opencloud.nix

Architecture

Browser
  └── cloud.yhkze.net (Traefik → OpenCloud :9200)
        ├── Auth: Keycloak OIDC (id.yhkze.net, realm internal)
        ├── Files: /mnt/aether/network/opencloud  (network drive)
        └── Office: office.yhkze.net (Collabora, WOPI protocol)

OpenCloud’s built-in IDP is disabled (OC_EXCLUDE_RUN_SERVICES=idp). Users are auto-provisioned on first login from OIDC claims — no manual user creation needed. Returning users are matched by email (PROXY_USER_OIDC_CLAIM=email), so renaming a user in Keycloak keeps their account; changing their email does not.

Groups and Roles

Role assignment is driven by Keycloak group membership (realm internal):

Keycloak Group OpenCloud Role
opencloud_admin Admin
opencloud_readwrite User
opencloud_service_group User
opencloud_readonly User Light

A User gets a personal Space and can upload and manage their own files. A User Light gets no personal Space, so it can only reach files through Spaces it was added to as a member. Note that demoting an account to User Light does not take away a personal Space it already had.

Add users to the appropriate group in the Keycloak admin console after account creation, reference Keycloak.

Initial Setup

OpenCloud generates internal keys and service state on first run. After deploy:

Before deploying, add two secrets to SOPS (hosts/server/secrets/secrets.yaml):

After deploy:

  1. Navigate to https://cloud.yhkze.net
  2. Log in with any Keycloak account in the opencloud_service_group or opencloud_admin group
  3. Verify Collabora opens correctly by creating a .odt file

File Storage

Files live at /mnt/aether/network/opencloud on the network drive. This path is mounted read-write by the OpenCloud service. Subdirectories are per-user, managed by OpenCloud’s internal IDM.

Operations

Check service:

systemctl status opencloud
journalctl -u opencloud -n 50

Check audit log:

tail -f /var/lib/opencloud/audit.log | jq .

References