README update for imaginary

Reviewed-on: coop-cloud/nextcloud#70

.env.sample

@@ -93,6 +93,17 @@ DEFAULT_QUOTA="10 GB"
 #SECRET_TALK_TURN_SECRET_VERSION=v1 # length=64 charset=default
 #SECRET_TALK_SIGNALING_SECRET_VERSION=v1 # length=64 charset=default
 
+# COMPOSE_FILE="$COMPOSE_FILE:compose.user_oidc.yml"
+# APPS="$APPS user_oidc"
+# USER_OIDC_PROVIDER=
+# USER_OIDC_ID=
+# USER_OIDC_DISCOVERY_URI=
+# USER_OIDC_END_SESSION_URI=
+# USER_OIDC_LOGIN_ONLY=false
+# SECRET_USER_OIDC_SECRET_VERSION=v1
+
+# Image / PDF previews with Imaginary (see README)
+#COMPOSE_FILE="$COMPOSE_FILE:compose.imaginary-preview.yml"
 
 # HSTS Options
 # Uncomment this line to enable HSTS: https://docs.nextcloud.com/server/30/admin_manual/installation/harden_server.html

MAINTENANCE.md

@@ -1,96 +0,0 @@
-# Nextcloud Recipe Maintenance
-
-> Status: **DRAFT** — open for discussion with co-maintainers and the wider
-> federation. Sections marked _(TBD)_ need collective input before this
-> document is considered ratified.
-
-This document describes how the Nextcloud recipe is maintained. It builds on
-the floor set by [Federation Resolution
-025](https://docs.coopcloud.tech/federation/resolutions/passed/025/) and
-follows the [`MAINTENANCE.md`
-template](https://docs.coopcloud.tech/maintainers/maintain/#maintenancemd-template)
-described in the Co-op Cloud maintainers' docs.
-
-All contributions should be made via a pull request so that quality and
-consistency stay something others can rely on.
-
-## Maintainers
-
-Everyone can apply to be a recipe maintainer. 
-Simply add your self to the list in the README.md and open a new pull request 
-with the change.
-
-## Maintainer Responsibilities
-
-This recipe commits to the following, which is tighter than the floor set by
-Resolution 025 (stable-recipe category). However, these timelines are
-best-effort, so we aim for them as good as possible:
-
-- Respond to PRs / issues within 3 working days
-- Apply security patches within 1 week of disclosure
-- Ship patch / minor image updates within 2 weeks of upstream release
-- Adopt major Nextcloud version updates within 1 release cycle of upstream
-  EOL of the previous major (see below)
-- Keep documentation current
-
-In order to meet these responsibilities each maintainer:
-
-- Watches the repository so notifications arrive
-- Keeps an eye on [Renovate](./renovate.json) updates and helps shepherd them through
-- Has a working contact (Matrix handle or email) reachable by the others
-
-## Release cadence
-
-The intent is to **track Nextcloud's own release schedule** rather than invent
-our own. In practice this means:
-
-- **Patch releases (e.g. `32.0.x`)**: published to this recipe shortly after
-  upstream, ideally within 1 week. `chore(deps)` opens the PRs; a maintainer
-  reviews the release notes and Nextcloud's issue tracker, and merges the PR
-  if it is OK.
-- **Minor releases**: same flow as patch releases, but one of the maintainer
-  tests it on their own instance before merging.
-- **Major releases (e.g. `32 → 33`)**: not adopted on day one. We wait for the
-  first one or two upstream patch releases of the new major to land
-  (typically 1–2 months) before promoting it here, to avoid passing the
-  early-adopter cost to operators. Major bumps get their own PR with release
-  notes and an upgrade-path check.
-  Before adding a major release, the following needs to be done:
-  - at least two maintainers update one of their production instances to the
-    new version
-  - the previous release gets a last update pointing to the docker image
-    versions nextcloud:xx-fpm, so that users can auto-update if they wish so
-  - the new release is added to this repo
-- If people have the time it would be nice to create specially tagged versions
-  for major releases, which reflect that this is 'bleeding edge' and has not
-  been thoroughly tested.
-- **Co-installed components** (Talk HPB, OnlyOffice, Whiteboard, etc.) are
-  bumped alongside or shortly after the matching Nextcloud release.
-
-## Pull Requests
-
-A pull request can be merged once it is approved by at least one maintainer.
-PRs opened by a maintainer need approval from another maintainer. With three
-maintainers this is workable; if the group shrinks, the rule should be
-revisited.
-
-Approvals should ideally include a smoke test on a real instance for anything
-beyond a patch bump — Nextcloud upgrades have a long history of surprising us
-(see the [upgrade notes in `README.md`](./README.md#upgrading-nextcloud)),
-and silent CI is not enough.
-
-## Becoming a maintainer
-
-Everyone is welcome to apply:
-
-1. Watch the repository so you get notifications.
-2. Open a pull request adding yourself to the `Maintainer` line in
-   [`README.md`](./README.md) and to the list above.
-3. Once an existing maintainer merges the PR, you'll be added to the
-   [nextcloud maintainers
-   team](https://git.coopcloud.tech/org/coop-cloud/teams/nextcloud-maintainers)
-   _(team to be created if it does not yet exist — TBD)_.
-
-Stepping down is symmetrical: open a PR removing yourself, and flag it in
-the federation channels so the group can plan replacement before falling
-below the Res. 025 floor of one named maintainer.

README.md

@@ -5,7 +5,6 @@
 Fully automated luxury Nextcloud via docker-swarm.
 
 <!-- metadata -->
-* **Maintainer**: [@dannygroenewegen](https://git.coopcloud.tech/dannygroenewegen), [@ineiti](https://git.coopcloud.tech/ineiti)
 * **Category**: Apps
 * **Status**: 5
 * **Image**: [`nextcloud`](https://hub.docker.com/_/nextcloud), 4, upstream
@@ -26,15 +25,21 @@ Fully automated luxury Nextcloud via docker-swarm.
 
 ### Onlyoffice Integration
 
+First install onlyoffice following the instructions in the 
+[OnlyOffice Recipe](https://recipes.coopcloud.tech/onlyoffice), and enable
+the JWT secret.
+
 `abra app config <app-name>` 
 
-Configure the following envs:
+Configure the following envs with the URL of the onlyoffice service:
 ```
 COMPOSE_FILE="$COMPOSE_FILE:compose.apps.yml"
 ONLYOFFICE_URL=https://onlyoffice.example.com
 SECRET_ONLYOFFICE_JWT_VERSION=v1
 ```
 
+Then set the onlyoffice JWT secret from the onlyoffice installation:
+
 * `abra app secret insert <app-name> onlyoffice_jwt v1 <jwt_secret>`
 * `abra app cmd <app-name> app install_onlyoffice`
 
@@ -189,6 +194,31 @@ We've been able to get this setup by using the [social login](https://apps.nextc
 
 If using Keycloak, you'll want to do [this trick](https://janikvonrotz.ch/2020/10/20/openid-connect-with-nextcloud-and-keycloak/) also.
 
+## How do I enable OpenID Connect (OIDC) providers?
+[user_oidc](https://github.com/nextcloud/user_oidc) is the recommended way to integrate Nextcloud with OIDC providers.
+
+Run `abra app config <app-name>`
+
+Set the following envs:
+```env
+COMPOSE_FILE="$COMPOSE_FILE:compose.user_oidc.yml"
+APPS="$APPS user_oidc"
+USER_OIDC_PROVIDER=example-provider # this has been tested with keycloak
+USER_OIDC_ID=example-client-id # get this from your oidc provider
+USER_OIDC_DISCOVERY_URI=example-oidc-provider.com/.well-known/openid-configuration # get this from your oidc provider
+USER_OIDC_END_SESSION_URI=example-oidc-provider.com/protocol/openid-connect/logout # get this from your oidc provider
+USER_OIDC_LOGIN_ONLY=false # set this to true to automatically redirect all logins to your oidc provider
+SECRET_USER_OIDC_SECRET_VERSION=v1
+```
+
+Then insert the client secret from your OIDC provider:
+```sh
+abra app secret insert <app-name> user_oidc_secret v1 <client-secret from oidc provider>
+```
+
+After you deploy (or redeploy), run the following to set up the user_oidc Nextcloud app:
+`abra app cmd <app-name> app set_user_oidc`
+
 ## How can I customise the CSS?
 
 There is some basic stuff in the admin settings.
@@ -285,6 +315,20 @@ docker exec -u www-data $(docker ps -f name=foo_com_app -q) ./occ preview:pre-ge
 
 This app will improve performance of image browsing at the cost of storage space.
 
+## Better image previews with `imaginary`
+
+1. Run `abra app config <domain>` and uncomment the line `#COMPOSE_FILE="$COMPOSE_FILE:compose.imaginary-preview.yml"`.
+2. Re-deploy the app (`abra app deploy <domain> --force`)
+3. Edit `/var/www/config/config.php` and add:
+
+  ```
+  'enabledPreviewProviders' => 
+  array (
+    0 => 'OC\\Preview\\Imaginary',
+  ),
+  'preview_imaginary_url' => 'http://imaginary:9000',
+  ```
+
 ## Fulltextsearch using elasticsearch
 
 1. Uncomment the following lines in your env file:

abra.sh

@@ -159,6 +159,23 @@ set_authentik() {
     run_occ 'config:system:set lost_password_link --value=disabled'
 }
 
+set_user_oidc() {
+    install_apps user_oidc
+    USER_OIDC_SECRET=$(cat /run/secrets/user_oidc_secret)
+    run_occ "user_oidc:provider \
+            --clientid=${USER_OIDC_ID} \
+            --clientsecret=${USER_OIDC_SECRET} \
+            --discoveryuri=${USER_OIDC_DISCOVERY_URI} \
+            --endsessionendpointuri=${USER_OIDC_END_SESSION_URI} \
+            --postlogouturi=https://${DOMAIN} \
+            --scope='openid email profile' \
+            ${USER_OIDC_PROVIDER}"
+    # disable non user_oidc login
+    if [[ ${USER_OIDC_LOGIN_ONLY:-false} = "true" ]]; then
+        run_occ "config:app:set --value=0 user_oidc allow_multiple_user_backends"
+    fi
+}
+
 disable_skeletondirectory() {
     run_occ "config:system:set skeletondirectory --value ''"
 }

compose.imaginary-preview.yml

@@ -0,0 +1,10 @@
+---
+version: '3.8'
+services:
+  imaginary:
+    image: nextcloud/aio-imaginary:20250822_112758
+    environment:
+      - PORT=9000
+    command: -concurrency 50 -enable-url-source -log-level debug
+    networks:
+      - internal

compose.talk.yml

@@ -14,7 +14,7 @@ services:
     deploy:
       labels:
         - traefik.enable=true
-        - traefik.docker.network=proxy
+        - traefik.swarm.network=proxy
         - traefik.http.services.${STACK_NAME}_talk.loadbalancer.server.port=8081
         - traefik.http.routers.${STACK_NAME}_talk.rule=Host(`${TALK_DOMAIN}`)
         - traefik.http.routers.${STACK_NAME}_talk.entrypoints=web-secure
@@ -67,4 +67,4 @@ configs:
   entrypoint_talk:
     name: ${STACK_NAME}_entrypoint_talk_${ENTRYPOINT_TALK_VERSION}
     file: entrypoint.talk.sh.tmpl
-    template_driver: golang
+    template_driver: golang

compose.user_oidc.yml

@@ -0,0 +1,10 @@
+version: "3.8"
+services:
+  app:
+    secrets:
+      - user_oidc_secret
+
+secrets:
+  user_oidc_secret:
+    external: true
+    name: ${STACK_NAME}_user_oidc_secret_${SECRET_USER_OIDC_SECRET_VERSION}

compose.whiteboard.yml

@@ -10,7 +10,7 @@ services:
     deploy:
       labels:
         - traefik.enable=true
-        - traefik.docker.network=proxy
+        - traefik.swarm.network=proxy
         - traefik.http.services.${STACK_NAME}_whiteboard.loadbalancer.server.port=3002
         - traefik.http.routers.${STACK_NAME}_whiteboard.rule=Host(`${DOMAIN}`${EXTRA_DOMAINS}) && PathPrefix(`/whiteboard`)
         - traefik.http.routers.${STACK_NAME}_whiteboard.entrypoints=web-secure
@@ -41,4 +41,4 @@ configs:
   entrypoint_whiteboard:
     name: ${STACK_NAME}_entrypoint_whiteboard_${ENTRYPOINT_WHITEBOARD_VERSION}
     file: entrypoint.whiteboard.sh.tmpl
-    template_driver: golang
+    template_driver: golang

compose.yml

@@ -29,7 +29,7 @@ services:
         order: start-first
       labels:
         - "traefik.enable=true"
-        - "traefik.docker.network=proxy"
+        - "traefik.swarm.network=proxy"
         - "traefik.http.services.${STACK_NAME}.loadbalancer.server.port=80"
         - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`${EXTRA_DOMAINS})"
         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"