Nextcloud
Nextcloud is a fork of ownCloud. For differences between the two, see Wikipedia:Nextcloud#Differences from ownCloud.
From Wikipedia:Nextcloud:
- Nextcloud is a suite of client-server software for creating and using file hosting services. It is functionally similar to Dropbox, although Nextcloud is free and open-source, allowing anyone to install and operate it on a private server. In contrast to proprietary services like Dropbox, the open architecture allows adding additional functionality to the server in form of applications.
Setup overview
A complete installation of Nextcloud comprises (at least) the following components:
A web server paired with an application server on which runs Nextcloud (i.e. the PHP code) using a database.
This article will cover MariaDB/MySQL and PostgreSQL as databases and the following combinations of web server and application server:
- nginx → uWSGI (plus uwsgi-plugin-php)
- nginx → php-fpm,
- Apache (using mod_proxy_uwsgi) → uWSGI (plus uwsgi-plugin-php)
- Apache (using mod_proxy_fcgi) → php-fpm
The Nextcloud package complies with the web application package guidelines. Among other things this mandates that the web application be run with a dedicated user - in this case nextcloud. This is one of the reasons why the application server comes into play here. For the very same reason it is not possible anymore to execute Nextcloud's PHP code directly in the Apache process by means of php-apache.
Installation
Install the nextcloud package. This will pull in quite a few dependent packages. All required PHP extensions will be taken care of this way. Additionally install the recommended packages php-imagick for preview generation and for increased translation performance and fixed sorting (preferrably as dependent package with pacman option ). Other optional dependencies will be covered later depending on your concrete setup (e.g. which database you choose).
Configuration
PHP
This guide does not tamper with PHP's central configuration file but instead puts Nextcloud specific PHP configuration in places where it does not potentially interfere with settings for other PHP based applications. These places are:
- A dedicated copy of in
/etc/webapps/nextcloud/php.ini(for theocccommand line tool and the background job). - Corresponding settings in the configuration of the application server. These will be covered in the section about application servers.
Make a copy of in . Although not strictly necessary change ownership of the copy:
Most of the prerequisites listed in Nextcloud's installation instructions are already enabled in a bare PHP installation. Additionally enable the following extensions:
Set to your preferred timezone, e.g.:
Raise PHP's memory limit to at least 512MiB:
Optional: For additional security configure . This limits the locations where Nextcloud's PHP code can read and write files. Proven settings are
Depending on which additional extensions you configure you may need to extend this list, e.g. /run/redis in case you opt for Redis.
It is not necessary to configure opcache here as this is only used by the occ command line tool and the background job, i.e. by short running PHP processes.
Nextcloud
Add the following entries to Nextcloud's configuration file:
/etc/webapps/nextcloud/config/config.php
'trusted_domains' =>
array (
0 => 'localhost',
1 => '''cloud.mysite.com''',
),
'overwrite.cli.url' => 'https://''cloud.mysite.com''/',
'htaccess.RewriteBase' => '/',
Adapt the given example hostname . In case your Nextcloud installation will be reachable via a subfolder (e.g. ) and have to be modified accordingly.
System and environment
To make sure the Nextcloud specific is used by the occ tool set the environment variable :
Also add this line to your (or ) to make this setting permanent.
As a privacy and security precaution create the dedicated directory for session data:
# install --owner=nextcloud --group=nextcloud --mode=700 -d /var/lib/nextcloud/sessions
Database
MariaDB/MySQL is the canonical choice for Nextcloud.
Most information concerning databases with Nextcloud deals with MariaDB/MySQL. The Nextcloud developers admit to have less detailed expertise with other databases.
PostgreSQL is said to deliver better performance and overall has fewer quirks compared to MariaDB/MySQL. SQLite is mainly supported for test / development installations and not recommended for production. The list of supported databases also contains Oracle database. This product will not be covered here.
MariaDB / MySQL
Since MariaDB has been the default MySQL implementation in Arch Linux since 2013 this text only mentions MariaDB.
In case you want to run your database on the same host as Nextcloud install mariadb (if you have not done so already). See the corresponding article for details. Do not forget to initialize MariaDB with . It is recommended for additional security to configure MariaDB to only listen on a local Unix socket:
Nextcloud's own documentation recommends to set the transaction isolation level to READ-COMMITTED. This is especially important when you expect high load with many concurrent transactions.
The other recommendation to set is obsolete. The default in recent MariaDB versions is at least as good as the recommended . In any case the setting is only relevant when replication is applied.
Start the CLI tool with database user root. (Default password is empty, but hopefully you change it as soon as possible.)
Create the user and database for Nextcloud with
(db-password is a placeholder for the actual password of DB user nextcloud you must choose.) Quit the tool with .
So that you have decided to use MariaDB as the database of your Nextcloud installation you have to enable the corresponding PHP extension:
Further configuration (related to MariaDB) is not required (contrary to the information given in Nextcloud's admin manual).
Now setup Nextcloud's database schema with:
Mind the placeholders (e.g. db-password) and replace them with appropriate values. This command assumes that you run your database on the same host as Nextcloud. Enter and see Nextcloud's documentation for other options.
PostgreSQL
Consult the corresponding article for detailed information about PostgreSQL. In case you want to run your database on the same host as Nextcloud install (if you have not done so already). For additional security in this scenario it is recommended to configure PostgreSQL to only listen on a local UNIX socket:
Especially do not forget to initialize your database with . After having done so start PostgreSQL's CLI tool :
$ sudo -u postgres -- psql
and create the database user nextcloud and the database of the same name
(db-password is a placeholder for the password of database user nextcloud that you have to choose.)
Install the additional package as dependency (pacman option ) and enable the corresponding PHP extension in /etc/webapps/nextcloud/php.ini:
Now setup Nextcloud's database schema with:
$ occ maintenance:install \
--database=pgsql \
--database-name=nextcloud \
--database-host=/run/postgresql \
--database-user=nextcloud \
--database-pass=''db-password'' \
--admin-pass=''admin-password'' \
--admin-email=''admin-email'' \
--data-dir=/var/lib/nextcloud/data
Mind the placeholders (e.g. db-password) and replace them with appropriate values. This command assumes that you run your database on the same host as Nextcloud. Enter and see Nextcloud's documentation for other options.
Application server
There are two prevalent application servers that can be used to process PHP code: uWSGI or php-fpm. php-fpm as the name suggests is specialized on PHP. The protocol used between the web server and php-fpm is fastcgi. The tool's documentation leaves room for improvement. uWSGI on the other hand can serve code written in a handful of languages by means of language specific plugins. The protocol used is uwsgi (lowercase). The tool is extensively documented - albeit the sheer amount of documentation can become confusing and unwieldy.
uWSGI
uWSGI has its own article. A lot of useful information can be found there. Install and the plugin - preferrably as dependencies, i.e. with . To run Nextcloud's code with (or in) uWSGI you have to configure one uWSGI specific configuration file () and define one systemd service.
nextcloud.ini
The nextcloud package includes a sample configuration file already in the right place . In almost any case you will have to adapt this file to your requirements and setup. Find a version with lots of commented changes (compared to the package's version). It assumes a no-frills Nextcloud installation for private use (i.e. with moderate load).
See section Background jobs for arguments why not to configure recurring jobs in this file. In general keep the enabled extensions, extension specific settings and in sync with /etc/webapps/nextcloud/php.ini (with the exception of opcache).
/etc/uwsgi/nextcloud.ini can become extensive. A file named nextcloud.ini.pacnew will be created during package update in case there are changes in the original file provided by the package nextcloud. In order to better track changes in this latter file and apply them to /etc/uwsgi/nextcloud.ini the following approach can be applied:
- Make a copy of the file as provided by the package (e.g. by extracting from the package) and store it as
nextcloud.ini.package. - In case an update of package nextcloud produces a
nextcloud.ini.pacnewyou can identify the changes withdiff nextcloud.ini.package nextcloud.ini.pacnew. - Selectively apply the changes to your
nextcloud.inidepending on whether they make sense with your version or not. - Move
nextcloud.ini.pacnewovernextcloud.ini.package.
Enable and start
The package provides a template unit file (). The instance ID (here nextcloud) is used to pick up the right configuration file. Enable/start .
In case you have more than a few (e.g. 2) services started like this and get the impression this is a waste of resource you might consider using emperor mode.
php-fpm
In case you opt to use php-fpm as your application server install - preferrably as a dependent package ().
Configuration consists of a copy of relevant for all applications served by php-fpm and a so-called pool file specific for the application (here Nextcloud). Finally you have to tweak the systemd service file.
php-fpm.ini
As stated earlier this article avoids modifications of PHP's central configuration in . Instead create a php-fpm specific copy.
# cp /etc/php/php.ini /etc/php/php-fpm.ini
Make sure it is owned and only writeable by root (). Enable the op-cache, i.e. uncomment the line
/etc/php/php-fpm.ini
;zend_extension=opcache
and put the following parameters below the existing line :
nextcloud.conf pool file
Next you have to create a so called pool file for php-fpm. It is responsible for spawning dedicated php-fpm processes for the Nextcloud application. Create a file - you may use this functional version as a starting point.
Again make sure this pool file is owned and only writeable by root (i.e. -rw-r--r-- 1 root root ... nextcloud.conf). Adapt or add settings (especially , and ) to your liking. The settings and must be consistent with the corresponding settings in /etc/webapps/nextcloud/php.ini (but not ).
The settings done by means of and could instead be specified in php-fpm.ini. But mind that settings in php-fpm.ini apply for all applications served by php-fpm.
php-fpm service
php-fpm is (of course) run as a systemd service. You have to modify the service configuration to be able to run Nextcloud. This is best achieved by means of a drop-in file and add:
- It replaces the line by a start command that uses the
php-fpm.inicovered in the previous section. - The directories and
/etc/webapps/nextcloud/config(and everything below) are made writable. The in the original service definition causes , and to be mounted read-only for the php-fpm processes.
Keep /etc tidy
The Nextcloud package unconditionally creates the uWSGI configuration file . Of course it is of no use when you run php-fpm instead of uWSGI (and it does no harm whatsoever). In case you nevertheless want to get rid of it just add the following lines to
Web server
There is an abundance of web servers you can choose from. Whatever option you finally pick you have to keep in mind that the Nextcloud application needs to be run with its own system user nextcloud. So you will need to forward your requests to one of the above mentioned application servers.
nginx
Configuration of nginx is way beyond the scope of this article. See the relevant article for further information. Also consult Nextcloud's documentation for an elaborated configuration. Most likely you will have to copy it into a file with an appropriate name (here as an example ) below /etc/nginx/sites-available and create the corresponding symbolic link in .
If using the example nginx config from the Nextcloud documentation linked above, the root directory should be changed to:
''cloud.mysite.com.conf''
root /usr/share/webapps/nextcloud;
The usage of the block is not necessary. Just specify in the block that deals with forwarding request with PHP URIs to the application server. When using uWSGI instead of php-fpm replace this block with:
Things you might have to adapt (not exhaustive):
- Your server name ( clauses 2x), i.e. the server part of the URL your Nextcloud installation will be reachable with.
- The name of the certificate and key you use for SSL / TLS.
- If and where you want an access log written to.
- The location where Certbot (or any other ACME client) will put the domain verification challenges. Usage of instead of is probably more adequate here.
- The path used to reach your Nextcloud installation. (The part right to the server name & port section in the URL.)
- What application server (uWSGI or php-fpm) you are using, i.e. how and where nginx will pass requests that need to trigger some PHP code. (See above.)
- Configure OCSP stapling.
There is no need to install any additional modules since nginx natively supports both protocols FastCGI and uwsgi.
Apache httpd
Find lots of useful information in the article about the Apache HTTP Server. Nextcloud's documentation has some sample configuration that can also be found in /usr/share/doc/nextcloud/apache.example.conf. Both implicitely rely on mod_php that cannot be used anymore. mod_proxy_fcgi or mod_proxy_uwsgi need to be applied.
Information about how to integrate Apache with php-fpm can be found here in this wiki. uWSGI's documentation has some information about how to integrate Apache with PHP by means of uWSGI and mod_proxy_uwsgi. Mind that the Apache package comes with both modules mod_proxy_fcgi and mod_proxy_uwsgi. They need to be loaded as required.
The following Apache modules are required to run Nextcloud:
Also uncomment the following directive to pull in TLS configuration parameters:
Consult Mozilla's SSL configurator for details about how to optimize your TLS configuration.
Refer to the following two sample configuration files depending on how you want to access your Nextcloud installation:
- In case your Nextcloud installation is accessed via a dedicated host name (e.g.
https://cloud.mysite.com/) put this fragment into .
- In case your Nextcloud installation is located in a subfolder of your web site (e.g. ) put this fragment in your .
Of course you must adapt these sample configuration files to your concrete setup. Replace the directive by when you use uWSGI.
The Nextcloud package comes with a that already takes care of a lot of rewriting and header stuff. Run occ maintenance:update:htaccess to adapt this file. Parameter in is vital for this.
Background jobs
Nextcloud requires certain tasks to be run on a scheduled basis. See Nextcloud's documentation for some details. The easiest (and most reliable) way to set up these background jobs is to use the systemd service and timer units that are already installed by nextcloud. The service unit needs some tweaking so that the job uses the correct PHP ini-file (and not the global ). Create a drop-in file and add:
After that enable/start nextcloud-cron.timer (not the service).
In-memory caching
Nextcloud's documentation recommends to apply some kind of in-memory object cache to significantly improve performance. This section demonstrates setup of APCu - mainly to pinpoint the details that differ from the instructions given in Nextcloud's documentation. The other options (Redis and memcached) are also sufficiently covered there.
Install (as dependency ). Enable the extension in the relevant configuration files. These are
/etc/webapps/nextcloud/php.iniused by theocccommand and the background jobs and- depending on the application server you use either
- in case you use uWSGI or
- in case you use php-fpm.
In /etc/webapps/nextcloud/php.ini add the lines
(preferably somewhere below ).
For the other two files the setting to activate APCu is already in place and only needs to be uncommented. Two other configuration parameters related to APCu are also already there. No need to touch /etc/php/php.ini or .
Restart your application server (not the web server as Nextcloud's documentation claims). Add the following line to your Nextcloud configuration file:
That's it. Enjoy your performance boost!
Security Hardening
See the Nextcloud documentation and Security. Nextcloud additionally provides a Security scanner.
Synchronization
Desktop
The official client can be installed with the package. Alternative versions are available in the AUR: nextcloud-client-gitAUR. Please keep in mind that using with Nextcloud is not supported.
The desktop client basically syncs one or more directories of your desktop computer with corresponding folders in your Nextcloud's file service. It integrates nicely with your desktop's file manager (Dolphin in KDE Plasma, Nautilus in Gnome) displaying overlays representing synchronization and share status. The context menu of each file gets an additional entry Nextcloud to manage sharing of this file and getting the public or internal share link. Nextcloud's documentation has a volume exclusively about the desktop client.
In case the integration does not work as described consult the optional dependencies of package (). E.g. Nautilus (Gnome) requires . Install as dependent package with ).
Thunderbird
Since version 91 Thunderbird fully supports CalDAV and CardDAV - even with auto detection (i.e. you do not have to provide long URLs to access your calendars and address books). Nextcloud's documentation is not up to date in this respect.
Calendar
There are a few ways how to start the new calendar wizard. One is via the main menu (☰ at the very right) > + New > Calendar… Choose Network and click Next. On the next page enter your username (that on your Nextcloud server) and the top URL of your Nextcloud server (e.g. https://cloud.mysite.org/). Click Search calendar. Now provide your password (or even better an app token (see above)). Finally select the calendar(s) you want to see in Thunderbird and click Subscribe. Be sure to mark read-only calendars (e.g. Nextcloud's birtday calendar) as read-only. Otherwise you will repeatably see reminders that you cannot effectively close.
Contacts
Open Thunderbird's address book — e.g. with . Choose File > New > CardDAV address book. On the next page enter your username (that on your Nextcloud server) and the top URL of your Nextcloud server (e.g. https://cloud.mysite.org/). Click Next. Now provide your password (or even better an app token (see above)). Finally select the address book(s) you want to see in Thunderbird's address book window and click Next.
Mounting files with davfs2
If you want to mount your Nextcloud using WebDAV, install (as described in davfs2).
To mount your Nextcloud, use:
You can also create an entry for this in
Mounting files in GNOME Files (Nautilus)
You can access the files directly in Nautilus ('+ Other Locations') via the WebDAV protocol. Use the link as shown in your Nextcloud installation Web GUI (e.g. ) but replace the protocol name https by . Nautilus will ask for user name and password when trying to connect.
Android
Download the official Nextcloud app from Google Play or F-Droid.
To enable contacts and calendar sync (Android 4+):
- Download DAVx5 (Play Store, F-Droid).
- Create a new DAVdroid account in the Account settings and specify your server URL (e.g. ) and login / password pair.
/remote.php/{carddav,webdav} part if you configured your web server with the proper redirections, as illustrated in the above section #Web server. DAVdroid will find itself the right URLs.iOS
Download the official Nextcloud app from the App Store.
Tips and tricks
Using the "occ" command line tool
A useful tool for server administration is occ. Refer to Nextcloud's documentation for details. You can perform many common server operations with occ, such as managing users and configuring apps.
A convenience wrapper around the original is provided with which automatically runs as the default user (nextcloud), using the default PHP executable and PHP configuration file. The environment variables , and can be used to specify a non-default user, PHP executable and PHP configuration file (respectively). Especially the latter (using ) is necessary when Nextcloud was setup in a way as described in the sections #Configuration and #Application server, i.e. using a PHP configuration specific to Nextcloud. In this case put in your .
Pacman hook
The nextcloud package comes with a pacman hook that takes care of automatically upgrading the Nextcloud database after the package has been updated. Take a look .
Unfortunately, this hook unconditionally uses the global when running occ upgrade, i.e. it doesn't take into account the value of environment variable as mentioned above in #Using the "occ" command line tool.
As a possible workaround make a copy of the delivered hook file in the appropriate location:
and change the line starting with to:
/etc/pacman.d/hooks/10-nextcloud.hook
Exec = /usr/bin/runuser -u nextcloud -- /usr/bin/php --php-ini /etc/webapps/nextcloud/php.ini /usr/share/webapps/nextcloud/occ upgrade
Running Nextcloud in a subdirectory
The instructions in section Web server will result in a setup where your Nextcloud installation is reachable via a dedicated server name, e.g. . If you would like to have Nextcloud located in a subdirectory. e.g. , then:
- For nginx refer to the section in Nextcloud's documentation that explicitely covers this topic.
- For apache edit the you included and comment out the part of the include file.
Office integration
There are currently three different solutions for office integration:
All three have in common that a dedicated server is required and your web server needs to be adapted to forward certain requests to the office service. The actual integration with Nextcloud is then accomplished by means of a Nextcloud app specific for one of the above products.
Mind that all three products are aimed at businesses, i.e. you will have to pay for the office service. Only Collabora offers a developers plan (CODE) for free. ONLYOFFICE offers a Home Server plan for a reasonable price.
For installation, setup instructions and integration with Nextcloud consult:
Disabling app recommendations
By default, nextcloud recommends apps to new clients, which can result in a lot of notifications. To disable this, disable the recommendation app using occ.
Troubleshooting
Reading the log
By default, the logs of the web application are available in . The entries (lines) are in JSON format and can be very long. Readability can be greatly improved by using :
Weird behavior of one or more apps
There are two locations where folders with files of Nextcloud's apps can be found:
- (aka read-only apps directory). This is where the nextcloud package and the app packages (e.g. ) put the folders with files comprising Nextcloud apps.
/var/lib/nextcloud/apps(aka writeable apps directory). This is where you find folders with files of apps installed via GUI or via the command.
When files of an app can be found in both directories (especially in different versions) all kind of strange things can happen. In a concrete case the contacts app could be found in both the read-only apps directory and the writeable apps directory. As a result the page with contacts in the GUI did not display. It remained blank white. The browser's Javascript console showed an error message:
Check for apps to be found in both locations. To find out whether to delete the app folder in the read-only directory or in the writeable directory determine whether the app is part of a package. Run
All folders reported with
(and that can also be found in the writeable apps directory) can be safely deleted from . Other double installed apps (i.e. those belonging to a package) should be removed from /var/lib/nextcloud/apps.
Warnings about failing code integrity checks (v23)
For version 23 Nextcloud's PHP code had to be extensively patched for the Arch Linux package to achieve PHP 8.1 compatibility. The downside of this was that Nextcloud's built-in code integrity check failed for all patched files. The corresponding warnings in the admin's view can be ignored. Version 24 is natively compatible with PHP 8.1. So no patches necessary and thus no integrity warnings anymore.
InnoDB refuses to write tables with ROW_FORMAT=COMPRESSED
MariaDB versions >= 10.6 and < 10.6.6 were not compatible with Nextcloud as the database enforced read-only for compressed InnoDB tables and Nextcloud has been (and still is) using these kind of tables:
- From MariaDB 10.6.0 until MariaDB 10.6.5, tables that are of the COMPRESSED row format are read-only by default. This was intended to be the first step towards removing write support and deprecating the feature.
- This plan has been scrapped, and from MariaDB 10.6.6, COMPRESSED tables are no longer read-only by default.
Additionally the issue has already been addressed by Nextcloud. Starting with Nextcloud v24 new installations of Nextcloud do not use row format COMPRESSED anymore. It has to be noted that existing (pre v24) installations are not migrated away from row format COMPRESSED automatically.
Bottom line: Probably you are not affected since Arch Linux has been shipping MariaDB v10.6.6 or later since 2022-02-10.
In the unlikely case that you are affected by this issue there are several possible remedies:
- Adapt your MariaDB configuration:
/etc/my.cnf.d/server.cnf
[mariadb-10.6] innodb_read_only_compressed=OFF
- Migrate your MariaDB tables from row format COMPRESSED to DYNAMIC as suggested by some comments for the corresponding Nextcloud issue. Mind that as long as you stay with Nextcloud < v24 new tables will again use row format COMPRESSED - so will need to be migrated in the same way.
- Replace MariaDB by PostgreSQL and migrate the data of your Nextcloud instance with . See Nextcloud's documentation for details.
Issues with permissions and setup after upgrade to >= 21.0.0
Since version 21.0.0 nextcloud more closely follows the web application package guidelines. This introduces the separate user nextcloud, as which the web application is run.
After an upgrade from nextcloud < 21.0.0 make sure that
- the data directory is located at
- the writable apps directory is located at
/var/lib/nextcloud/apps - both the data directory and the writable apps directory, alongside all files beneath them are writable and owned by the
nextclouduser - the web application configuration file resides in
/etc/webapps/nextcloud/config/and that that directory and its contents are writable and owned by thenextclouduser - an application server, such as or UWSGI is configured to run the web application as the
nextclouduser and not the user - update the cron job/systemd timer to run with the new user
- Finally allow read access to the nextcloud installation to your web-server user by doing:
Login loop without any clue in access.log, error.log, nor nextcloud.log
As mentioned in a post in the forum, this issue can be fixed by setting correct permissions on the sessions directory. (See Nextcloud's documentation for details.) It is also possible that the sessions directory is missing altogether. The creation of this directory is documented in System and environment.
should look like this:
Environment variables not available
Depending on what application server you use custom environment variables can be provided to Nextcloud's PHP code.
php-fpm
Add one or more lines in as per Nextcloud's documentation, e.g.:
uwsgi
Add one or more lines in , e.g.:
Mind there must not be any blanks around the second =.