[Nextcloud](https://nextcloud.com/) is the most popular self-hosted collaboration solution for tens of millions of users at thousands of organizations across the globe.
## Dependencies
This service requires the following other services:
To enable this service, add the following configuration to your `vars.yml` file. This is a minimal example. See also the [Optional Configuration](#optional-configuration) sections below.
Then proceed with the [Installation](#installation) as described below, noting that it includes pre-install and post-install steps.
In the example configuration above, we configure the service to be hosted at `https://mash.example.com/nextcloud`.
You can remove the `nextcloud_path_prefix` variable definition, to make it default to `/`, so that the service is served at `https://mash.example.com/`.
You can choose any username/password for the initial account. This account will have [super administrator](https://docs.nextcloud.com/server/30/admin_manual/configuration_user/user_configuration.html#granting-administrator-privileges-to-a-user) privileges, by being a member of the `admin` group, but is not otherwise special or unique.
## Installation
Installation of Nextcloud requires two or three steps.
### Pre-Install
If you've decided to install a dedicated KeyDB instance for Nextcloud, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `nextcloud.example.com-deps`), before running installation for the main one (e.g. `nextcloud.example.com`).
### Main Install and Start Services
Run the [installation](../installing.md) for the main nextcloud host, e.g. `just run-tags install-all,start`.
Ensure Nextcloud and all services it depends on are installed and started.
### Post-Install
After the main installation, and services are running, you need to run a post-install step before Nextcloud will be available to use.
Run the post-install step: `just post-install-nextcloud` (or `just post-install-all`).
This post-install step:
- runs the Nextcloud [initial installation](https://docs.nextcloud.com/server/latest/admin_manual/installation/command_line_installation.html) `occ maintenance:install`, if it hasn't yet run.
- adjusts the configuration of URL paths, trusted reverse-proxies, etc.
- configures Nextcloud settings including those you define in `nextcloud_config_additional_parameters`.
To learn more, read the [Memory caching](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/caching_configuration.html) section of the Nextcloud documentation.
As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to Nextcloud](#creating-a-keydb-instance-dedicated-to-nextcloud).
If you're only running Nextcloud on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-nextcloud).
**Regardless** of the method of installing KeyDB, you may need to adjust your Nextcloud configuration file (e.g. `/mash/nextcloud/data/config/config.php`) to **add** this:
This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to Nextcloud](#creating-a-keydb-instance-dedicated-to-nextcloud).
The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.
Adjust your `inventory/hosts` file as described in [Re-do your inventory to add supplementary hosts](../running-multiple-instances.md#re-do-your-inventory-to-add-supplementary-hosts), adding a new supplementary host (e.g. if `nextcloud.example.com` is your main one, create `nectcloud.example.com-deps`).
Nextcloud supports Single-Sign-On (SSO) via LDAP, SAML, and OIDC. To make use of this you'll need a Identity Provider like [authentik](./authentik.md) or [Keycloak](./keycloak.md). The following assumes you use authentik.
**The official documentation of authentik to connect nextcloud via SAML seems broken**
MASH can connect Nextcloud with authentik via OIDC. The setup is quite straightforward, refer to [this blogpost by Jack](https://blog.cubieserver.de/2022/complete-guide-to-nextcloud-oidc-authentication-with-authentik/) for a full explanation.
To enable [Samba](https://www.samba.org/) external Windows fileshares using [smbclient](https://www.samba.org/samba/docs/current/man-html/smbclient.1.html), add the following additional configuration to your `vars.yml` file:
# By default, various private IPv4 networks are whitelited to connect to the WOPI API (document serving API).
# If your Collabora Online installation does not live on the same server as Nextcloud,
# you may need to adjust the list of networks.
# If necessary, redefined the `nextcloud_collabora_app_wopi_allowlist` environment variable here.
```
There's **no need** to [re-run the playbook](../installing.md) after adjusting your `vars.yml` file.
You should, however run: `just run-tags install-nextcloud-app-collabora`
This will install and configure the [Office](https://apps.nextcloud.com/apps/richdocuments) app for Nextcloud.
You should then be able to click any document (`.doc`, `.odt`, `.pdf`, etc.) in Nextcloud Files and it should automatically open a Collabora Online editor.
You can also create new documents via the "plus" button.
It is possible to setup preview generation, using this playbook.
First modify your `vars.yml` file by adding at least the following line (other options are also present, check the corresponding `defaults/main.yml` file):
```yaml
nextcloud_preview_enabled: true
```
then install Nextcloud (or rerun the playbook if already installed).
Next, from the Settings/Application menu in your Nextcloud instance install the preview generator app (https://apps.nextcloud.com/apps/previewgenerator).
After the application is installed run `just run-tags adjust-nextcloud-config` that will start the original preview-generation and when finished, enables the periodic generation of new images.
The original generation may take a long time, but a continuous prompt is presented by ansible as some visual feedback (it is being run as an async task), however it will timeout after approximately 27 hours.
On 60GBs, most of the data being images, it took about 10 minutes to finish.
If it takes more time to run than a day, you may want to start it from the host by calling
`nextcloud_preview_preview_max_x` and `nextcloud_preview_preview_max_y` sets the maximum size of the preview in pixels..
Their default value according to the [documentation](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/previews_configuration.html) is `null` which is set by the playbook.
Using a numeric value will set the corresponding nextcloud variable and sets the size of the preview images.
`nextcloud_preview_app_jpeg_quality` JPEG quality setting for preview images.
