waldur-site-agent-nextcloud

Nextcloud plugin for Waldur Site Agent.

Users purchase storage plans in Waldur and automatically receive access to a shared Nextcloud Group Folder. Login is via Keycloak OIDC.

At a glance

Modes: order_process, membership_sync, report, event_process (recommended).

How it works

• Each Waldur resource → a Nextcloud Group + Group Folder (with quota from the plan)
• Users added to the resource → added to the Nextcloud group → can access the folder
• Usage is reported as Group Folder bytes used

Prerequisites

Install and enable in Nextcloud admin:

• User OIDC app (user_oidc) — configure to point at your Keycloak realm
• Group Folders app (groupfolders)

In the OIDC provider settings, set the user ID attribute to preferred_username (matches the Keycloak username that the site-agent uses when calling the OCS API).

Configuration example

offerings:
  - name: "Nextcloud Storage"
    waldur_api_url: "https://waldur.example.com/api/"
    waldur_api_token: "<site agent api token>"
    waldur_offering_uuid: "<offering uuid>"
    backend_type: "nextcloud"
    order_processing_backend: "nextcloud"
    membership_sync_backend: "nextcloud"
    reporting_backend: "nextcloud"
    # STOMP is strongly recommended for Nextcloud.  On event-based deployments
    # the agent retries the team-member fetch to avoid a race where the
    # create-order event arrives before Waldur commits the initial membership.
    stomp_enabled: true
    # stomp_membership_sync_enabled: false  # uncomment to keep HTTP polling for
    #                                       # membership sync even with STOMP on
    backend_settings:
      nextcloud_url: "https://nextcloud.example.com"
      admin_username: "admin"
      admin_password: "<nextcloud admin or app password>"
      group_prefix: "waldur-"          # prefix for auto-created groups
      default_storage_quota_gb: 25     # fallback if plan has no storage limit (GiB)
      allow_resharing: false           # allow users to reshare folder contents
    backend_components:
      storage:
        # Quota values are in GiB (1 GiB = 1024³ bytes), consistent with how
        # Nextcloud labels storage in its UI.
        measured_unit: "GiB"
        accounting_type: "limit"
        label: "Storage"
        unit_factor: 1

Backend settings reference

The agent does not expand ${VAR} references in its configuration file; write the values in, or generate the file from a template at deploy time. The settings are validated by waldur_site_agent_nextcloud.schemas.NextcloudBackendSettingsSchema; a misspelt or missing required key is logged as a warning when the agent loads its configuration, and the backend refuses to start without the required ones. The backend also requires a storage component with accounting_type: limit.

STOMP settings reference

team_fetch_attempts (backend-level, non-configurable)

The Nextcloud backend sets team_fetch_attempts = 4 internally. On order-processing paths (including STOMP create-order events) the event can arrive before Waldur has committed the initial team membership row. The agent retries the team-member fetch up to 4 times (with a 3 s delay between attempts) if the list comes back empty. Other backends default to 1 (no retry); this higher value is specific to Nextcloud's create-order path.

Note: the retry only helps when the team is entirely absent. A non-empty but stale team (new member not yet committed) breaks on the first attempt.

Tests

cd plugins/nextcloud && uv run pytest tests/