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 -->
* **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

`abra app config <app-name>` 

Configure the following envs:
```
COMPOSE_FILE="$COMPOSE_FILE:compose.apps.yml"
ONLYOFFICE_URL=https://onlyoffice.example.com
SECRET_ONLYOFFICE_JWT_VERSION=v1
```

* `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.

Many of us  have found that jumping major versions when upgrading is also 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 extra cautious just upgrade one release at a time. Read the release notes and check your logs.

## 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 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'
```