nextcloud/README.md

# Nextcloud

[![Build Status](https://drone.autonomic.zone/api/badges/coop-cloud/nextcloud/status.svg)](https://drone.autonomic.zone/coop-cloud/nextcloud)

Fully automated luxury Nextcloud via docker-swarm.

<!-- metadata -->
* **Maintainer**: [@dannygroenewegen](https://git.coopcloud.tech/dannygroenewegen), [@ineiti](https://git.coopcloud.tech/ineiti), [@javielico](https://git.coopcloud.tech/javielico)
* **Category**: Apps
* **Status**: 5
* **Image**: [`nextcloud`](https://hub.docker.com/_/nextcloud), 4, upstream
* **Healthcheck**: Yes
* **Backups**: Yes
* **Email**: 3
* **Tests**: 2
* **SSO**: 1 (OAuth)
<!-- endmetadata -->

## Quick start

* `abra app new nextcloud`
* `abra app config <app-name>`
* `abra app secret insert <app-name> smtp_password v1 <SMTP_PASSWORD>`
* `abra app secret generate -a <app-name>`
* `abra app deploy <app-name>`

### Onlyoffice Integration

First, install onlyoffice following the instructions in the 
[OnlyOffice Recipe](https://recipes.coopcloud.tech/onlyoffice), and enable
the JWT secret. Then configure your nextcloud instance with:

`abra app config <app-name>` 

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`

### BBB Integration

`abra app config <app-name>` 

Configure the following envs:
```
COMPOSE_FILE="$COMPOSE_FILE:compose.apps.yml"
BBB_URL=https://talk.example.org/bigbluebutton/ # trailing slash!
SECRET_BBB_SECRET_VERSION=v1
```

* `abra app secret insert <app-name> bbb_secret v1 <bbb_secret>`
* `abra app cmd <app-name> app install_bbb`

### Nextcloud Talk High performance Backend

Note: at the moment you are limited to run one Nextcloud high performance backend per docker host with this setup.

`abra app config <app-name>` 

Configure the following envs:
```
#COMPOSE_FILE="$COMPOSE_FILE:compose.talk.yml"
#TALK_DOMAIN=talk.example.com
#SECRET_TALK_INTERNAL_SECRET_VERSION=v1 # length=64 charset=default
#SECRET_TALK_TURN_SECRET_VERSION=v1 # length=64 charset=default
#SECRET_TALK_SIGNALING_SECRET_VERSION=v1 # length=64 charset=default
```

* `abra app secret insert <app-name> talk_internal_secret v1 <talk_internal_secret>`
* `abra app secret insert <app-name> talk_turn_secret v1 <talk_turn_secret>`
* `abra app secret insert <app-name> talk_signaling_secret v1 <talk_signaling_secret>`
* `abra app cmd <app-name> app install_talk`

Don't forget to enable the additional env's in your hosts traefik instance:
```
COMPOSE_FILE="$COMPOSE_FILE:compose.nextcloud-talk-hpb.yml"
NEXTCLOUD_TALK_HPB_ENABLED=1
```

Due to a bug in compose that deletes duplacted ports without checking for the protocol, traefik need to get the additional udp binding added after the deployment via ssh (this might take longer than expected!):
```
docker service update  --publish-add published=3478,target=3478,protocol=udp traefik_XXX_XXX_app
```

To check if tcp and udp was binded, you can use:
```
docker service inspect traefik_XXX_XXX_app | grep 3478 -a2
```

### Authentik Integration


`abra app config <app-name>` 
Configure the following envs:
```
COMPOSE_FILE="$COMPOSE_FILE:compose.authentik.yml"
AUTHENTIK_USER_PREFIX=authentik
AUTHENTIK_DOMAIN=authentik.example.com
AUTHENTIK_SECRET_NAME=authentik_example_com_nextcloud_secret_v1  # the same as in authentik
AUTHENTIK_ID_NAME=authentik_example_com_nextcloud_id_v1  # the same as in authentik
```

`abra app cmd <app-name> app set_authentik`

## Running `occ`

`abra app cmd <app-name> app run_occ '"user:list --help"'`

Read more about [occ command here](https://docs.nextcloud.com/server/stable/admin_manual/occ_command.html).

### Disable Dashboard

To disable dashboard app (since it is so corporate):

`abra app cmd <app-name> app run_occ '"app:disable dashboard"'`

## Default user files

- Follow [these docs](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/default_files_configuration.html) to set the default files list for each user in the Files app

## Default App

- Configure a `defaultapp` in your `config.php` or use [apporder](https://apps.nextcloud.com/apps/apporder)

## Upgrading Nextcloud

Upgrading Nextcloud can be a hair raising experiance. They
[don't support downgrading](https://docs.nextcloud.com/server/latest/admin_manual/maintenance/upgrade.html)
even for minor versions.

### Upgrade path

Many of us have found that jumping major versions when upgrading is a bad idea.
We have however found that it's ok to skip minor version upgrades and go to the
last minor version before a major version (e.g. 24.0.0 to 24.9.9 before going to
25.0.0). To be extra cautious just upgrade one release at a time. Read the
release notes and check your logs.

### Checking upgrade readiness

Before upgrading to a new major, check whether the instance (and its enabled
apps) look ready:

`abra app cmd <app-name> app check_major_upgrade`

This checks that you're not skipping a major version, that there's no pending DB
upgrade left over from a previous update, and that every enabled non-shipped app
declares support for the target major (falling back to an apps.nextcloud.com
lookup to see if an app update would fix it). Shipped apps (`files`, `settings`,
etc.) are skipped since they come bundled and are upgraded within the Docker
image. Pass an explicit target major as the first argument (e.g.
`check_major_upgrade 33`) to check readiness for a specific major, or it
defaults to current major + 1. This is a sanity check, not a guarantee. Still
read Nextcloud's release notes for any
[critical changes between major versions](https://docs.nextcloud.com/server/stable/admin_manual/release_notes/index.html#critical-changes).

### Staying on an old major version

If you're not able to move to a new major version yet (e.g. because of app
incompatibility), note that (starting from v32) before we release a recipe
container a new major Nextcloud version, we also publish one more release of the
previous major that points its image at the floating `nextcloud:XX-fpm` tag
(e.g. `nextcloud:32-fpm`) instead of a pinned patch version. Deploying that
release is less predictable: every redeploy pulls whatever the latest `32-fpm`
build happens to be at that moment, rather than a fixed, reproducible version.
But it means you keep getting security patches for the old major if you can't
move to the next major. See [MAINTENANCE.md](./MAINTENANCE.md#release-cadence)
for how this fits into our release process.

## Upgrading Nextcloud apps (plug-ins)

`abra app cmd <app-name> app run_occ '"app:update --all"'`


## How do I fix a Nextcloud version snafu?

`Exception: Updates between multiple major versions and downgrades are unsupported.`

Solution:

- Look at log files to determine the old Nextcloud version
- Change your local `~/.abra/recipes/nextcloud/compose.yml` to the highest minor
    version in the old version -- e.g. choose `22.2.5` for `22`, if you're
    upgrading to `23`.
- Then, do one of (both bad):
  1. `abra app deploy --chaos ...`, then `app run` to go in and manually lower the version number in PHP (shell in, `apt install vim-core && vi version.php`), then try `php ./occ upgrade`
  2. `abra app undeploy ...`, `abra volume rm`, CAREFULLY only choose the volume
     ENDING `_nextcloud`, then `abra app deploy --chaos ...`, then edit the
     `compose.yml` to add `entrypoint: ['tail', '-f', '/dev/null']` to `app`,
     then `app deploy --chaos` again, then `app run --user=www-data ... app bash` to get in and run `./occ maintenance:repair`, and `./occ upgrade`. 
- Change `compose.yml` to the new version number; `git checkout compose.yml`
- `abra app deploy --force`
- This wasn't even multiplle major versions was it 😾

## How do I integrate with Keycloak SSO?

Use [this plugin](https://github.com/pulsejet/nextcloud-oidc-login). Unlike the plugin it's forked from, there is no configuration UI, so you'll need to edit `/var/www/html/config/config.php`:

```
  'oidc_login_client_id' => 'nextcloud',
  'oidc_login_client_secret' => 'mysecret',
  'oidc_login_provider_url' => 'https://example.com/realms/myrealm',
  'oidc_login_disable_registration' => false,
  'oidc_login_hide_password_form' => true,
  'oidc_login_button_text' => 'Log in with your myssodomain',
  'oidc_login_default_group' => 'mygroup',
  'oidc_login_attributes' =>
  array (
    'id' => 'sub',
    'name' => 'name',
    'mail' => 'email',
  ),
  'oidc_create_groups' => true,
```

You can use [this trick](https://janikvonrotz.ch/2020/10/20/openid-connect-with-nextcloud-and-keycloak/) (see "Cryptic Usernames" work-around) to get proper usernames.

If you ever need to change the realm, you'll need to reset the cache with:

```
docker exec -u www-data <container-id> php occ config:app:delete oidc_login last_updated_well_known
docker exec -u www-data <container-id> php occ config:app:delete oidc_login last_updated_jwks
```

## How do I enable multiple SSO login buttons?

We've been able to get this setup by using the [social login](https://apps.nextcloud.com/apps/sociallogin) plugin.

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.

To go a little deeper, you can use [this handy app](https://apps.nextcloud.com/apps/theming_customcss).

Here is an example CSS config which hides the local login and makes space for a central image:

```css
#body-login .wrapper main form[name="login"],
#body-login .wrapper main form[name="login"] ~ a {
  display: none;
}

#body-login .logo {
  visibility: hidden;
}

#body-login #alternative-logins a.button[href*="oidc"] {
  background: #233b4a;
  color: #fff;
  transition: all 0.2s ease-in-out;
}
#body-login #alternative-logins a.button[href*="oidc"]:hover {
  background: linear-gradient(-35deg, #233b4a 40%, #486c83 100%);
}

#body-login #alternative-logins a.button[href*="/sociallogin/oauth/google"] {
  border: 0;
  color: #db4437 !important;
  background-color: #fff;
}

#body-login
  #alternative-logins
  a.button[href*="/sociallogin/oauth/google"]::before {
  width: 25px;
  background-color: #db4437;
  border-radius: 100%;
  background-size: 60%;
  background-position: center;
  height: 25px;
  vertical-align: middle;
  margin-right: 4px;
}

#body-login main {
  padding: 50vh 0 0 0;
}

#body-login a[href*="#body-login"] {
  visibility: hidden;
}

#body-login footer a,
#body-login footer p {
  color: #233b4a;
}

#body-login footer a:hover {
  color: #fff;
}

#body-login footer p.info {
  text-shadow: none;
}
```

[nextcloud-docker]: https://hub.docker.com/_/nextcloud/
[`abra`]: https://git.autonomic.zone/autonomic-cooperative/abra
[`coop-cloud/traefik`]: https://git.autonomic.zone/coop-cloud/traefik

## Using [`previewgenerator`](https://github.com/nextcloud/previewgenerator) app

> Beware, this appp has been known to not work...

After you install, enable etc. then you need to run the generation (**warning**: it can take a long time!):

```
abra app run <domain> app bash -u www-data
./occ preview:generate-all
```

To set up the cron to run again, there is [no clear solution in the context of
containers](https://github.com/nextcloud/previewgenerator/issues/1). So, a
pretty dodgy hack is to run it from the system directly:

```
root@foo.com /etc/cron.hourly $ cat foo-com-preview-generate 
#!/bin/bash

docker exec -u www-data $(docker ps -f name=foo_com_app -q) ./occ preview:pre-generate
```

This app will improve performance of image browsing at the cost of storage space.

## Fulltextsearch using elasticsearch

1. Uncomment the following lines in your env file:
```
#COMPOSE_FILE="$COMPOSE_FILE:compose.fulltextsearch.yml"
#SECRET_ELASTICSEARCH_PASSWORD_VERSION=v1
```

2. Generate the secret for elasticsearch:
```bash
abra app secret generate <domain> elasticsearch_password v1
```

3. Deploy your app:
```bash
abra app deploy <domain>
```

4. Install the apps and configure them:
```
abra app cmd <domain> app install_fulltextsearch
```

5. You might need to configure the files_fulltextsearch app. run this command to check its settings:
```
abra app cmd <domain> app run_occ '"config:list files_fulltextsearch"
```

6. You can check if the nextcloud can connect to elasticsearch:
```
abra app cmd <domain> app run_occ '"fulltextsearch:test"'
```

And you can populate the index manually and check if any errors occur:
```
abra app cmd <domain> app run_occ '"fulltextsearch:index"'
```

### Troubleshooting fulltextsearch

The fulltextsearch plugin might be stuck with this error: "Index is already running". In that case the following command can get things runing again:

```
abra app run <domain> db /bin/sh -- -c 'echo "delete from oc_fulltextsearch_ticks;" | mariadb -u root -p$(cat /run/secrets/db_root_password) nextcloud'
```