The playbook can install and configure Nextcloud for you.
Nextcloud is the most popular self-hosted collaboration solution for tens of millions of users at thousands of organizations across the globe.
See the project's documentation to learn what Nextcloud does and why it might be useful to you.
For details about configuring the Ansible role for Nextcloud, you can check them via:
- 🌐 the role's documentation online
- 📁
roles/galaxy/nextcloud/docs/configuring-nextcloud.mdlocally, if you have fetched the Ansible roles
This service requires the following other services:
- Postgres / MySQL / MariaDB / SQLite database — Nextcloud will default to SQLite if Postgres is not enabled
- Traefik reverse-proxy server
- (optional) a Valkey data-store; see below for details about installation
- (optional) exim-relay mailer
To enable this service, add the following configuration to your vars.yml file:
########################################################################
# #
# nextcloud #
# #
########################################################################
nextcloud_enabled: true
nextcloud_hostname: mash.example.com
nextcloud_path_prefix: /nextcloud
# Valkey configuration, as described below
########################################################################
# #
# /nextcloud #
# #
########################################################################By default Nextcloud is configured to use Postgres (if enabled), but you can choose other databases such as MySQL (MariaDB) and SQLite. If Postgres is not enabled, SQLite will be used. See this section on the role's documentation for details.
On Nextcloud you can set up a mailer for functions such as password recovery. If you enable the exim-relay service in your inventory configuration, the playbook will automatically configure it as a mailer for the service.
To actually have the service use (and get messages sent through the exim-relay service), you will need to adjust settings on the service's UI after the service is installed.
Warning
Without setting an authentication method such as DKIM, SPF, and DMARC for your hostname, emails are most likely to be quarantined as spam at recipient's mail servers. The worst scenario is that your server's IP address or hostname will be included in the spam list such as the one managed by Spamhaus, depending on the reputation. As the exim-relay service supports DKIM signing, refer to the role's documentation for details about how to set it up.
Some configuration parameters for Nextcloud can be specified with variables starting with nextcloud_config_parameter_default_*. See this section on the role's documentation for details. Refer to this page of the Nextcloud documentation as well.
Valkey can optionally be enabled to improve Nextcloud performance and to prevent file locking problems. This playbook supports it, and you can set up a Valkey instance by enabling it on vars.yml.
If Nextcloud is the sole service which requires Valkey on your server, it is fine to set up just a single Valkey instance. However, it is not recommended if there are other services which require it, because sharing the Valkey instance has security concerns and possibly causes data conflicts, as described on the documentation for configuring Valkey. In this case, you should install a dedicated Valkey instance for each of them.
If you are unsure whether you will install other services along with Nextcloud or you have already set up services which need Valkey (such as PeerTube, Funkwhale, and Docmost), it is recommended to install a Valkey instance dedicated to Nextcloud.
See below for an instruction to install a shared instance.
💡 Though running Valkey is recommended, you can start without it for a simpler deployment. To learn more, read this section of the Nextcloud documentation about memory caching.
To create a dedicated instance for Nextcloud, you can follow the steps below:
- Adjust the
hostsfile - Create a new
vars.ymlfile for the dedicated instance - Edit the existing
vars.ymlfile for the main host
See this page for details about configuring multiple instances of Valkey on the same server.
At first, you need to adjust inventory/hosts file to add a supplementary host for Nextcloud.
The content should be something like below. Make sure to replace mash.example.com with your hostname and YOUR_SERVER_IP_ADDRESS_HERE with the IP address of the host, respectively. The same IP address should be set to both, unless the Valkey instance will be served from a different machine.
[mash_servers]
[mash_servers:children]
mash_example_com
[mash_example_com]
mash.example.com ansible_host=YOUR_SERVER_IP_ADDRESS_HERE
mash.example.com-nextcloud-deps ansible_host=YOUR_SERVER_IP_ADDRESS_HERE
…mash_example_com can be any string and does not have to match with the hostname.
You can just add an entry for the supplementary host to [mash_example_com] if there are other entries there already.
Then, create a new directory where vars.yml for the supplementary host is stored. If mash.example.com is your main host, name the directory as mash.example.com-nextcloud-deps. Its path therefore will be inventory/host_vars/mash.example.com-nextcloud-deps.
After creating the directory, add a new vars.yml file inside it with a content below. It will have running the playbook create a mash-nextcloud-valkey instance on the new host, setting /mash/nextcloud-valkey to the base directory of the dedicated Valkey instance.
# This is vars.yml for the supplementary host of Nextcloud.
---
########################################################################
# #
# Playbook #
# #
########################################################################
# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
mash_playbook_generic_secret_key: ''
# Override service names and directory path prefixes
mash_playbook_service_identifier_prefix: 'mash-nextcloud-'
mash_playbook_service_base_directory_name_prefix: 'nextcloud-'
########################################################################
# #
# /Playbook #
# #
########################################################################
########################################################################
# #
# valkey #
# #
########################################################################
valkey_enabled: true
########################################################################
# #
# /valkey #
# #
########################################################################Having configured vars.yml for the dedicated instance, add the following configuration to vars.yml for the main host, whose path should be inventory/host_vars/mash.example.com/vars.yml (replace mash.example.com with yours).
########################################################################
# #
# nextcloud #
# #
########################################################################
# Add the base configuration as specified above
# Make sure the connection via Unix domain socket is enabled
# Set to `false` to enable TCP connection instead
nextcloud_redis_socket_enabled: true
# Connect Nextcloud to its dedicated Valkey instance via the Unix domain socket
#
# Alternatively, if you set `nextcloud_redis_socket_enabled` to `false`,
# - Add the dedicated Valkey instance (mash-nextcloud-valkey) to `nextcloud_redis_hostname`
# - Add its network (mash-nextcloud-valkey) to `nextcloud_container_additional_networks_custom`
nextcloud_redis_socket_path_host: /mash/nextcloud-valkey/run
# Make sure the Nextcloud service (mash-nextcloud.service) starts after its dedicated Valkey service (mash-nextcloud-valkey.service)
nextcloud_systemd_required_services_list_custom:
- "mash-nextcloud-valkey.service"
########################################################################
# #
# /nextcloud #
# #
########################################################################Running the installation command will create the dedicated Valkey instance named mash-nextcloud-valkey.
If you host only Nextcloud on this server, it is fine to set up a single shared Valkey instance.
To install the single instance and hook Nextcloud to it, add the following configuration to inventory/host_vars/mash.example.com/vars.yml:
########################################################################
# #
# valkey #
# #
########################################################################
valkey_enabled: true
########################################################################
# #
# /valkey #
# #
########################################################################
########################################################################
# #
# nextcloud #
# #
########################################################################
# Add the base configuration as specified above
# Make sure the connection via Unix domain socket is enabled
# Set to `false` to enable TCP connection instead
nextcloud_redis_socket_enabled: true
# Connect Nextcloud to the shared Valkey instance via the Unix domain socket
#
# Alternatively, if you set `nextcloud_redis_socket_enabled` to `false`,
# - Add the shared Valkey instance (mash-valkey) to `nextcloud_redis_hostname`
# - Add its network (mash-valkey) to `nextcloud_container_additional_networks_custom`
nextcloud_redis_socket_path_host: "{{ valkey_run_path }}"
# Make sure the Nextcloud service (mash-nextcloud.service) starts after the shared Valkey service (mash-valkey.service)
nextcloud_systemd_required_services_list_custom:
- "{{ valkey_identifier }}.service"
########################################################################
# #
# /nextcloud #
# #
########################################################################Running the installation command will create the shared Valkey instance named mash-valkey.
You can enable Samba external Windows fileshares using smbclient. See this section on the role's documentation for details.
If you have decided to install the dedicated Valkey instance for Nextcloud, make sure to run the installing command for the supplementary host (mash.example.com-nextcloud-deps) first, before running it for the main host (mash.example.com).
Note that running the just commands for installation (just install-all or just setup-all) automatically takes care of the order. See here for more details about it.
After running the command for installation, the Nextcloud instance becomes available at the URL specified with nextcloud_hostname and nextcloud_path_prefix. With the configuration above, the service is hosted at https://mash.example.com/nextcloud.
Before logging in to the instance, update the configuration (URL paths, trusted reverse-proxies, etc.) by running the command below:
just run-tags adjust-nextcloud-configNote
You should re-run the command every time the Nextcloud version is updated.
The playbook automatically configures a SMTP server (Exim-relay), to which the Nextcloud instance connects to send emails. After logging in as the admin user, you can check the configuration at https://mash.example.com/nextcloud/settings/admin for basic administration settings.
Before sending a test mail, make sure to set the email address of the admin user at https://mash.example.com/nextcloud/settings/user. Otherwise hitting the "Send email" button on the page returns the 400 error, as the instance does not know where to send the mail. See the browser's console for details.
It is possible to set up preview generation. See this section on the role's documentation for details about necessary steps to enable it.
Nextcloud supports Single-Sign-On (SSO) via LDAP, SAML, and OIDC. To make use of it, an Identity Provider (IdP) like authentik or Keycloak needs to be set up.
For example, you can enable SSO with authentik via OIDC by following the steps below:
- Create a new provider in authentik and trim the client secret to less than 64 characters
- Create an application in authentik using this provider
- Install the app
user_oidcin Nextcloud - Fill in the details from authentik in the app settings
Refer to this blogpost by a third party for details.
💡 Notes:
- The official documentation of authentik to connect nextcloud via SAML does not seem to work (as of August 2023).
- If you cannot log in due to an error (the error message contains
SHA1 mismatch), make sure that Nextcloud users and authentik users do not have the same name. If they do, checkUse unique user IDin the OIDC App settings.
Nextcloud ships with an LDAP application to allow LDAP (including Active Directory) users to log in to the Nextcloud instance with their LDAP credentials. See this section on the role's documentation for details about how to configure Nextcloud.
This playbook supports LLDAP, and it is possible to set up the LLDAP instance as a source for users.
First, the LLDAP instance needs to be installed. See this page for the instruction.
Then, proceed to configure the LDAP application on the Nextcloud to have it connect to the LLDAP instance. By default the playbook is configured to use the user specified with lldap_environment_variables_lldap_ldap_user_dn for binding. To use another user (with search privileges), add the following configuration to your vars.yml file:
nextcloud_ldap_agent_name_uid: USERNAME_FOR_BINDING_HERERun the command below to configure the LDAP application on the Nextcloud instance, so that the instance connects to the LLDAP server:
just run-tags set-ldap-config-nextcloud -e agent_password=PASSWORD_OF_BIND_USER_HEREAfter running the command successfully, the application's server tab should look like below (note: uid is set to admin):
If "Configuration OK 🟢" is displayed at the bottom of the tab, the application is configured successfully, and now users on the LLDAP instance can log in to the instance with their LDAP credentials.
Refer to this page on the Nextcloud admin manual for details about other configurations.
To disable the integration altogether (in case of using another LDAP server for Nextcloud while using LLDAP for other services, etc.), add the following configuration to your vars.yml file:
nextcloud_lldap_enabled: falseTo use the Nextcloud Office application, it is necessary to set up an Euro-Office instance. This playbook supports it, and you can set it up by enabling it on vars.yml. You can follow the documentation to install it.
By default, this playbook is configured to automatically integrate the Euro-Office instance with the Nextcloud instance which this playbook manages, if both of them are enabled.
After installing both Euro-Office and Nextcloud, run this command to install and configure the Nextcloud Office application:
just run-tags install-nextcloud-app-euroofficeYou should then be able to open any document (.doc, .odt, .pdf, etc.) and create new ones in Nextcloud Files with the Nextcloud Office application.
Open the URL https://mash.example.com/nextcloud/settings/admin/eurooffice to configure the application. Refer to this page for details about available settings.
To use the Nextcloud Office (Collabora) application, it is necessary to set up a WOPI (Web Application Open Platform Interface) client such as Collabora Online Development Edition (CODE). This playbook supports CODE, and you can set up a CODE instance by enabling it on vars.yml. You can follow the documentation to install it.
By default, this playbook is configured to automatically integrate the CODE instance with the Nextcloud instance which this playbook manages, if both of them are enabled.
After installing both CODE and Nextcloud, run this command to install and configure the Nextcloud Office (Collabora) application:
just run-tags install-nextcloud-app-richdocumentsOpen the URL https://mash.example.com/nextcloud/settings/admin/richdocuments to have the instance set up the connection with the CODE instance.
You should then be able to open any document (.doc, .odt, .pdf, etc.) and create new ones in Nextcloud Files with the Nextcloud Office (Collabora) application.
Note
By default, several private IPv4 networks are whitelisted to connect to the WOPI API (document serving API). If your CODE instance does not live on the same server as Nextcloud, you may need to adjust the list of networks. If necessary, redefine the nextcloud_app_richdocuments_wopi_client_allowlist environment variable on vars.yml.
See this section on the role's documentation for details.