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`

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

### Disable Dashboard

Disable dashboard app since it is so corporate:

`abra app config <app-name>` 
Configure the following envs:
```
OCC_CMDS="app:disable dashboard"
```
`abra app cmd <app-name> app post_install_occ`

## Running `occ`

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

## 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 apps

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