grnet.nextcloud.nextcloud

Overview

Installs and configures Nextcloud. Use like this:

tasks:
- role: grnet.nextcloud.nextcloud
  nextcloud_fqdn: nextcloud.example.com
  nextcloud_default_phone_region: GR
  nextcloud_mail_from_address: noreply
  nextcloud_mail_domain: example.com

You may need to perform additional configuration using Nextcloud’s web interface. See section Limitations for that.

Parameters

nextcloud_fqdn

The domain name for Nextcloud.

nextcloud_mysql_fqdn

The FQDN of the MySQL server. The default is localhost.

nextcloud_admin_user

The username for the Nextcloud administrator. The default is admin.

nextcloud_admin_user_password

The Nextcloud administrator password. This will usually be in the vault.

nextcloud_download_url

By default, the latest version of Nextcloud Community will be installed. To install another version, specify a different URL, such as https://download.nextcloud.com/server/releases/nextcloud-24.0.11.zip. It must point to a zip file.

Unless when an upgrade is specifically requested, this role downloads and installs Nextcloud only if it is not already installed; if already installed, the role does not upgrade it and nextcloud_download_url is irrelevant. To upgrade Nextcloud, see Upgrading Nextcloud.

nextcloud_assistant_background_worker

If you install the Nextcloud Assistant, you will also want to install a background worker (otherwise any requests to the Assistant will be executed when cron runs, by default every 5 minutes). Set this variable to true to enable the background worker. It runs four instances of the worker (this is currently not configurable). The default is false.

nextcloud_appapi_harp_shared_key

If you define this variable, the role enables Nextcloud AppAPI support, installs a local HaRP container, and adds the required /exapps/ reverse proxy configuration to the main nginx or Apache virtual host. The value is the shared secret used by HaRP and the AppAPI deploy daemon, so it should be vaulted.

nextcloud_letsencrypt

This role automatically includes an apache_vhost role or an nginx_site role as needed and nextcloud_letsencrypt is passed as the letsencrypt parameter. The default is nextcloud_fqdn.

nextcloud_php_memory_limit

Default 512M.

nextcloud_php_upload_max_filesize
nextcloud_php_post_max_size
nextcloud_php_max_execution_time

The defaults for these are 2M, 8M and 30, which are essentially the php or the Debian fpm defaults. However, they are too low for Nextcloud Talk recordings. If you install Nextcloud Talk recording, use 2048M, 2048M and 3600.

nextcloud_opcache_interned_strings_buffer

The default for this PHP setting is 8. However in some installations it might need to be set to 16, and sometimes to 32. It seems to depend on the installed apps. See the related support forum discussion for more information.

nextcloud_fpm_mode
nextcloud_fpm_max_children
nextcloud_fpm_start_servers
nextcloud_fpm_min_spare_servers
nextcloud_fpm_max_spare_servers
nextcloud_fpm_process_idle_timeout

These configure the Nextcloud PHP-FPM pool’s pm process manager settings. The defaults are suitable for about 50 reasonably active users. On smaller systems, modify these settings to use less RAM. Setting nextcloud_fpm_mode=ondemand and nextcloud_fpm_process_idle_timeout=10m is an alternative that will use way less RAM on small systems and will likely scale well.

nextcloud_default_phone_region

A country code like “GR”. There is no default. This is used for Nextcloud’s default_phone_region configuration parameter.

nextcloud_mail_from_address
nextcloud_mail_domain

The email address from which email notifications from Nextcloud appear to be sent. For example, to use noreply@example.com, specify nextcloud_mail_from_address=noreply and nextcloud_mail_domain=example.com.

These settings are those that can be set in the web interface, under Basic settings, Email server. This role will overwrite these settings whenever Ansible is run.

It will always use localhost port 25 as the smarthost, without authentication and without encryption. For this to work, use Ansible role mail_satellite.

nextcloud_mysql_client_key
nextcloud_mysql_client_cert
nextcloud_mysql_ca_cert

By default, these parameters are empty. In this case, Nextcloud connects to MySQL without TLS. If they have values, they must be pathnames (in the Ansible controller) from which the keys and certificates are taken and installed in the Nextcloud server. In this case, Nextcloud is configured to connect to MySQL with TLS.

Either all three must be empty, or all three must have a value.

nextcloud_cron_schedule

How often to run Nextcloud’s cron.php (which, e.g., sends notifications to users). It must be in the format accepted by cron. The default is */5 * * * *.

nextcloud_maintenance_window_start

The start time, as an integer hour, in UTC, when cron is allowed to perform non-time-critical tasks. (The end time is four hours later.) The default is 1, i.e. 01:00 UTC.

nextcloud_mail_smtpmode

The mode to use for sending email. The default is “smtp”. See the relevant Nextcloud documentation for more.

Upgrading Nextcloud

The role has the option of upgrading Nextcloud to a newer version. This will cause some downtime and it is important to understand how it works before trying it. Apart from some checks, this is what it does:

  • It moves /etc/cron.d/nextcloud to /tmp/nextcloud.cron.

  • It downloads and unzips the new Nextcloud version to /tmp/nextcloud.

  • It copies the existing Nextcloud installation’s config.php to /tmp/nextcloud/config.

  • It stops the php-fpm service.

  • It moves the existing Nextcloud installation directory to /tmp/nextcloud.old, then moves the data directory to /tmp/nextcloud/data, then moves /tmp/nextcloud to the correct directory (/var/www/.../nextcloud). These should happen instantly, because these moves are in the same filesystem. In fact, the playbook verifies that this is the case before running.

  • It starts the php-fpm service. So far the downtime is minimal.

  • It executes the php occ upgrade command. This takes several minutes during which Nextcloud is out of service (it shows a related message to users).

  • It moves /tmp/nextcloud.cron back to its correct location.

You can upgrade Nextcloud by specifying the upgrade_nextcloud tag. In that case, you also need to specify nextcloud_download_url to point to the version you want to upgrade to. This should not be more than one major release ahead of what is already installed (this is not checked), otherwise the upgrade will fail.

Here is an example of how to upgrade:

ansible-playbook site.yml --tags upgrade_nextcloud \
    -e nextcloud_download_url=https://download.nextcloud.com/server/releases/nextcloud-23.0.0.zip

If all goes well, at the end of the upgrade the directory /tmp/nextcloud.old still contains the old installation (but without the data directory). You need to remove it or move it elsewhere in order to attempt another upgrade.

If anything goes wrong, you have to cleanup yourself (restore /etc/cron.d/nextcloud and /var/www/.../nextcloud). This is why it is important to understand the process clearly.

Sometimes after major upgrades the theme might break; for example, icons or logos may be missing from the main toolbar or from other toolbars (such as the toolbar of the markdown editor). In this case, this typically fixes the problems:

cd /var/www/.../nextcloud
sudo -u www-data php occ maintenance:repair

Limitations

Server setup

Many things are hardwired. The current assumption is that Nextcloud, Redis and Apache are all going to be in the same machine.

Setting up theming

It seems to be nontrivial to setup theming through the command line, particularly to setup logo, background and favicon. Therefore, the role does not touch theming; use the web interface to setup theming after Ansible is run.

Setting up the Mail app

It doesn’t seem to be possible to setup the Mail app through the command line or Ansible. You need to go to the web interface, logon as admin, and go to Settings, Administration, Groupware.