# Nextcloud

Ansible role to deploy [Nextcloud](https://nextcloud.com/) (fpm) with
Postgres and Redis via Docker Compose, optional Collabora WOPI
integration, optional draw.io integration, optional notify_push
companion, optional S3 primary storage, plus OIDC and LDAP user
backends.

## What this role does

- Renders the Compose stack with traefik labels and TLS
- Installs and enables a configurable list of Nextcloud apps idempotently
- Configures Collabora (richdocuments), draw.io, OIDC providers and
  LDAP via `occ` — every setting is read first and only written when
  the stored value differs, so re-runs don't churn
- Sets up notify_push (when enabled)
- Applies an in-container PHP source workaround for the upstream
  `UserConfig::getValueBool` TypeError (nextcloud/server#59629, fixed in
  master via PR #59646 with no stable33 backport before 33.0.4).
  Idempotent via grep guard; remove the patch task once
  `nextcloud_image` is >= 33.0.4.

## Requirements

- Docker and Docker Compose installed on the target host
- Ansible collection: `community.docker`
- Traefik with a shared `nextcloud_traefik_network` (default `proxy`)

## Role variables

Full spec with types and defaults: `meta/argument_specs.yml`. The most
common overrides:

### Service

- `nextcloud_domains`: FQDNs the router accepts. First entry is the
  canonical hostname (used for `OVERWRITEHOST` and notify_push setup).
  Further entries cover internal `*.int.*` names so Collabora's WOPI
  callback hits the instance on a name with a valid cert.
- `nextcloud_admin_password`, `nextcloud_postgres_password` (required).
- `nextcloud_memory_limit_mb`, `nextcloud_upload_limit_mb`.

### Collabora

- `nextcloud_enable_collabora`: toggle integration with a separately
  deployed Collabora server (see the `collabora` role).
- `nextcloud_collabora_domain`: server-to-server hostname.
- `nextcloud_collabora_public_domain` (optional): browser-facing
  hostname when split-horizon uses different names.

### Draw.io

- `nextcloud_enable_drawio`: enable the `integration_drawio` app.
- `nextcloud_drawio_url`: public draw.io URL.
- `nextcloud_drawio_theme`, `nextcloud_drawio_offline`.

### Notify push

- `nextcloud_enable_notify_push`: deploy the notify_push companion.
- `nextcloud_notify_push_domain` (optional): override the hostname
  used by `occ notify_push:setup` to avoid hairpinning through the DMZ.

### S3 primary storage

Set `nextcloud_use_s3_storage: true` plus the `nextcloud_s3_*` block to
point Nextcloud at an external S3-compatible store (e.g. Garage, MinIO).

### OIDC

`nextcloud_oidc_providers` is a list of OIDC providers registered with
`user_oidc`. Required fields per entry: `identifier`, `display_name`,
`client_id`, `client_secret`, `discovery_url`.

### LDAP

Set `nextcloud_ldap_enabled: true` and provide `nextcloud_ldap_config`
as a dict of `occ ldap:set-config s01 KEY VALUE` pairs. The role reads
the current LDAP config via `occ ldap:show-config s01 --output=json`
and only calls `ldap:set-config` for keys whose stored value differs.

## Dependencies

- Traefik network (`nextcloud_traefik_network`, default `proxy`)
- Optional: `collabora`, `drawio`, `garage` roles for the corresponding
  integrations
- Optional: an OIDC provider (Keycloak, authentik) reachable from
  Nextcloud and a 389ds LDAP server when using `user_ldap`

## Example playbook

```yaml
- hosts: app_servers
  roles:
    - role: digitalboard.core.nextcloud
      vars:
        nextcloud_domains:
          - "cloud.example.com"
          - "cloud.int.example.com"
        nextcloud_admin_password: "{{ vault_nextcloud_admin_password }}"
        nextcloud_postgres_password: "{{ vault_nextcloud_pg_password }}"

        nextcloud_enable_collabora: true
        nextcloud_collabora_domain: "office.int.example.com"
        nextcloud_collabora_public_domain: "office.example.com"

        nextcloud_enable_notify_push: true
        nextcloud_notify_push_domain: "cloud.int.example.com"

        nextcloud_oidc_providers:
          - identifier: authentik
            display_name: "Login with Authentik"
            client_id: nextcloud
            client_secret: "{{ vault_nextcloud_oidc_secret }}"
            discovery_url: "https://auth.example.com/application/o/nextcloud/.well-known/openid-configuration"
            mapping:
              uid: preferred_username
              display_name: name
              email: email
              groups: groups
```

## License

MIT-0