Nextcloud
Nextcloud is a suite of client-server-software that (by means of so-called apps) allows all kinds of sharing, collaboration and communication, e.g.:
- file sharing
- personal information manager (contacts, calendar, tasks)
- messaging (mail, chat, video conferencing)
- collaborative editing of documents (text, Office integration)
Nextcloud is open source and based on open standards. Data sovereignty is a big plus, i.e. with your own instance of Nextcloud, you break free from proprietary (and potentially untrustworthy) services like Dropbox, Office 365, or Google Drive.
Depending on your needs Nextcloud can be deployed from single-board computers (like e.g. a Raspberry Pi) all the way up to full scale data centers serving millions of users. With an elaborated authorization scheme and the option for federation (connecting discrete instances) Nextcloud is well suited for use in enterprise environments.
Nextcloud is a fork of ownCloud. See Wikipedia for the history.
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 → FPM,
- Apache HTTP server (using mod_proxy_uwsgi) → uWSGI (plus uwsgi-plugin-php)
- Apache HTTP server (using mod_proxy_fcgi) → 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. When asked choose php-legacy as your PHP version. This will pull in quite a few dependent packages. Most of the required PHP extensions will be taken care of this way. Additionally, you have to install php-legacy-gd (preferrably as dependent package with pacman option --asdeps
).
It is recommended to also install the packages
- php-legacy-sodium for the argon2 hashing algorithm and
- php-legacy-imagick and librsvg for preview generation
(also with --asdeps
). Other optional dependencies will be covered later depending on your concrete setup (e.g. what database you choose).
Mind that some modules (namely bcmath, exif, gmp, intl and sysvsem) come with php-legacy. So no explicit installation is required for those.
Configuration
PHP
This guide does not tamper with PHP's central configuration file /etc/php-legacy/php.ini
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
php.ini
in/etc/webapps/nextcloud
(for theocc
command line tool and the background job). This is literally a copy of the originalphp.ini
as provided by the php-legacy package with some Nextcloud specific additions / modifications.
- Corresponding settings in the configuration of the application server. These will be covered in the section about application servers.
Make a copy of /etc/php-legacy/php.ini
to /etc/webapps/nextcloud
(or even better, extract php.ini
from the php-legacy package tarball below /var/cache/pacman/pkg
). Although not strictly necessary, change ownership of the copy:
# cp /etc/php-legacy/php.ini /etc/webapps/nextcloud # chown nextcloud:nextcloud /etc/webapps/nextcloud/php.ini
Most of the required PHP modules listed in Nextcloud's documentation are already enabled in the just copied bare PHP installation configuration file. Additionally enable the following extensions:
/etc/webapps/nextcloud/php.ini
extension=exif extension=gd extension=iconv extension=intl extension=sysvsem ; bcmath and gmp for passwordless login extension=bcmath extension=gmp ; sodium for the argon2 hashing algorithm extension=sodium ; in case you installed php-legacy-imagick (as recommended) extension=imagick
Depending on the database you are going to use enable the corresponding pdo_xxxx
module. See Database below.
Set date.timezone
to your preferred timezone, e.g.:
/etc/webapps/nextcloud/php.ini
date.timezone = Europe/Berlin
Raise PHP's memory limit to at least 512MiB:
/etc/webapps/nextcloud/php.ini
memory_limit = 512M
Optional: For additional security configure open_basedir
. This limits the locations where Nextcloud's PHP code can read and write files. Proven settings are
/etc/webapps/nextcloud/php.ini
open_basedir=/var/lib/nextcloud:/tmp:/usr/share/webapps/nextcloud:/etc/webapps/nextcloud:/dev/urandom:/usr/lib/php-legacy/modules:/var/log/nextcloud:/proc/meminfo:/proc/cpuinfo
Depending on what 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 php.ini
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 cloud.mysite.com
. In case your Nextcloud installation will be reachable via a subfolder (e.g. https://www.mysite.com/nextcloud
) overwrite.cli.url
and htaccess.RewriteBase
have to be modified accordingly.
System and environment
To make sure the Nextcloud specific php.ini
is used by the occ
tool set the environment variable NEXTCLOUD_PHP_CONFIG
:
$ export NEXTCLOUD_PHP_CONFIG=/etc/webapps/nextcloud/php.ini
Also add this line to your .bashrc
(or .bash_profile
) 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.
- The MySQL or MariaDB databases are the recommended database engines.[1]
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[2] this text only mentions MariaDB.
In case you want to run your database on the same host as Nextcloud install, configure and start mariadb (if you have not done so already). See the corresponding article for details. Do not forget to initialize MariaDB with mariadb-install-db
. It is recommended for additional security to configure MariaDB to only listen on a local Unix socket:
/etc/my.cnf.d/server.cnf
[mysqld] skip_networking
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.
/etc/my.cnf.d/server.cnf
[mysqld] transaction_isolation=READ-COMMITTED
The other recommendation to set binlog_format=ROW
is obsolete. The default MIXED
in recent MariaDB versions is at least as good as the recommended ROW
. In any case the setting is only relevant when replication is applied.
Start the CLI tool mysql
with database user root. (Default password is empty, but hopefully you change it as soon as possible.)
$ mysql -u root -p
Create the user and database for Nextcloud with
CREATE USER 'nextcloud'@'localhost' IDENTIFIED BY 'db-password'; CREATE DATABASE IF NOT EXISTS nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; GRANT ALL PRIVILEGES on nextcloud.* to 'nextcloud'@'localhost'; FLUSH privileges;
(db-password
is a placeholder for the actual password of DB user nextcloud you must choose.) Quit the tool with \q
.
So that you have decided to use MariaDB as the database of your Nextcloud installation you have to enable the corresponding PHP extension:
/etc/webapps/nextcloud/php.ini
extension=pdo_mysql
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:
$ occ maintenance:install \ --database=mysql \ --database-name=nextcloud \ --database-host=localhost:/run/mysqld/mysqld.sock \ --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 occ help maintenance:install
and see Nextcloud's documentation for other options. See Using the "occ" command line tool for Arch-specific details about this tool.
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, configure and start postgresql (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:
/var/lib/postgres/data/postgresql.conf
listen_addresses = ''
Especially do not forget to initialize your database with initdb
. After having done so start PostgreSQL's CLI tool psql and create the database user nextcloud
and the database of the same name
[postgres]$ psql
CREATE USER nextcloud WITH PASSWORD 'db-password'; CREATE DATABASE nextcloud TEMPLATE template0 ENCODING 'UNICODE'; ALTER DATABASE nextcloud OWNER TO nextcloud; GRANT ALL PRIVILEGES ON DATABASE nextcloud TO nextcloud; \q
(db-password
is a placeholder for the password of database user nextcloud that you have to choose.)
Install the additional package php-legacy-pgsql as dependency (pacman option --asdeps
) and enable the corresponding PHP extension in /etc/webapps/nextcloud/php.ini
:
/etc/webapps/nextcloud/php.ini
extension=pdo_pgsql
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 occ help maintenance:install
and see Nextcloud's documentation for other options. See Using the "occ" command line tool for Arch-specific details about this tool.
Application server
There are two prevalent application servers that can be used to process PHP code: uWSGI or FPM. FPM is specialized on PHP. The protocol used between the web server and 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 uwsgi and the plugin uwsgi-plugin-php-legacy - preferrably as dependencies, i.e. with --asdeps
. To run Nextcloud's code with (or in) uWSGI you have to configure one uWSGI specific configuration file (nextcloud.ini
) and define one systemd service.
nextcloud.ini
The nextcloud package includes a sample configuration file already in the right place /etc/uwsgi/nextcloud.ini
. 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).
In general keep the enabled extensions, extension specific settings and open_basedir
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.pacnew
you can identify the changes withdiff nextcloud.ini.package nextcloud.ini.pacnew
. - Selectively apply the changes to your
nextcloud.ini
depending on whether they make sense with your version or not. - Move
nextcloud.ini.pacnew
overnextcloud.ini.package
.
uWSGI service
The package uwsgi provides a template unit file (uwsgi@.service
). The instance ID (here nextcloud) is used to pick up the right configuration file. Enable and start uwsgi@nextcloud.service
.
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.
FPM
In case you opt to use FPM as your application server install php-legacy-fpm - preferrably as a dependent package (--asdeps
).
Configuration consists of a copy of php.ini
relevant for all applications served by 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 /etc/php-legacy/php.ini
. Instead create a FPM specific copy.
# cp /etc/php-legacy/php.ini /etc/php-legacy/php-fpm.ini
Make sure it is owned and only writeable by root (-rw-r--r-- 1 root root ... php-fpm.ini
). Enable the op-cache, i.e. uncomment the line
/etc/php-legacy/php-fpm.ini
zend_extension=opcache
and put the following parameters below the existing line [opcache]
:
/etc/php-legacy/php-fpm.ini
opcache.enable = 1 opcache.interned_strings_buffer = 16 opcache.max_accelerated_files = 10000 opcache.memory_consumption = 128 opcache.save_comments = 1 opcache.revalidate_freq = 1
php_value[...]
and php_flag[...]
. Your FPM processes will consistently crash with the very first request.nextcloud.conf
Next you have to create a so called pool file for FPM. It is responsible for spawning dedicated FPM processes for the Nextcloud application. Create a file /etc/php-legacy/php-fpm.d/nextcloud.conf
- 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
). Depending on whether access log is configured (it is with above sample nextcloud.conf
) you may need to create the corresponding directory (here /var/log/php-fpm-legacy/access
). Adapt or add settings (especially pm...
, php_value[...]
and php_flag[...]
) to your liking. The settings php_value[...]
and php_flag[..]
must be consistent with the corresponding settings in /etc/webapps/nextcloud/php.ini
(but not /etc/php-legacy/php-fpm.ini
).
The settings done by means of php_value[...]
and php_flag[...]
could instead be specified in php-fpm.ini
. But mind that settings in php-fpm.ini
apply for all applications served by FPM.
www.conf
that is of little use here. A good approach to get rid of it is to rename it to www.conf.package
and create a file www.conf
with only comment lines (lines starting with a semicolon). This way www.conf
becomes a no-op. It is also not overwritten during installation of a new version of php-legacy-fpm. Instead a file www.conf.pacnew
is created. You can compare this against www.conf.package
to see if anything significant has changed in the pool file that you may have to reproduce in nextcloud.conf
. Do not forget to rename www.conf.pacnew
to www.conf.package
at the end of this procedure.Systemd service
FPM is 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:
/etc/systemd/system/php-fpm-legacy.service.d/override.conf
[Service] ExecStart= ExecStart=/usr/bin/php-fpm-legacy --nodaemonize --fpm-config /etc/php-legacy/php-fpm.conf --php-ini /etc/php-legacy/php-fpm.ini ReadWritePaths=/var/lib/nextcloud ReadWritePaths=/etc/webapps/nextcloud/config
- It replaces the
ExecStart
line by a start command that uses thephp-fpm.ini
covered in the previous section. - The directories
/var/lib/nextcloud
and/etc/webapps/nextcloud/config
(and everything below) are made writable. TheProtectSystem=full
in the original service definition causes/usr
,/boot
and/etc
to be mounted read-only for the FPM processes.
Do not forget to enable and start the service php-fpm-legacy.
Keep /etc tidy
The Nextcloud package unconditionally creates the uWSGI configuration file /etc/uwsgi/nextcloud.ini
. Of course it is of no use when you run FPM instead of uWSGI (and it does no harm whatsoever). In case you nevertheless want to get rid of it, just add the following NoExtract line to /etc/pacman.conf
:
/etc/pacman.conf
# uWSGI configuration that comes with Nextcloud is not needed NoExtract = etc/uwsgi/nextcloud.ini
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. It is up to you how to include this snippet into your nginx' configuration. One common approach is to use directories /etc/nginx/sites-available
and /etc/nginx/sites-enabled
to separate configurations for various servers (aka virtual hosts). See Nginx#Managing server entries for details.
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 upstream php-handler { ... }
is not necessary. Just specify fastcgi_pass unix:/run/php-fpm-legacy/nextcloud.sock;
in the location
block that deals with forwarding request with PHP URIs to the application server. When using uWSGI instead of FPM replace this location
block with:
cloud.mysite.com.conf
location ~ \.php(?:$|/) { include uwsgi_params; uwsgi_modifier1 14; # Avoid duplicate headers confusing OC checks uwsgi_hide_header X-Frame-Options; uwsgi_hide_header X-XSS-Protection; uwsgi_hide_header X-Content-Type-Options; uwsgi_hide_header X-Robots-Tag; uwsgi_hide_header X-Download-Options; uwsgi_hide_header X-Permitted-Cross-Domain-Policies; uwsgi_pass unix:/run/uwsgi/nextcloud.sock; }
Things you might have to adapt (not exhaustive):
- Your server name (
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
alias
instead oftry_files
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 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 HTTP server
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 implicitly 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 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:
/etc/httpd/conf/httpd.conf
# these are already loaded in a standard Apache installation LoadModule headers_module modules/mod_headers.so LoadModule env_module modules/mod_env.so LoadModule dir_module modules/mod_dir.so LoadModule mime_module modules/mod_mime.so LoadModule setenvif_module modules/mod_setenvif.so # these need to be uncommented explicitly LoadModule rewrite_module modules/mod_rewrite.so LoadModule ssl_module modules/mod_ssl.so LoadModule socache_shmcb_module modules/mod_socache_shmcb.so LoadModule proxy_module modules/mod_proxy.so # either this one in case you use FPM LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so # or this one in case you opt for uWSGI LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so
Also uncomment the following directive to pull in TLS configuration parameters:
/etc/httpd/conf/httpd.conf
Include conf/extra/httpd-ssl.conf
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/etc/httpd/conf/extra/httpd-vhosts.conf
.
- In case your Nextcloud installation is located in a subfolder of your web site (e.g.
https://www.mysite.com/nextcloud/
) put this fragment in your/etc/httpd/conf/httpd.conf
.
Of course you must adapt these sample configuration files to your concrete setup. Replace the SetHandler
directive by SetHandler "proxy:unix:/run/uwsgi/nextcloud.sock|uwsgi://nextcloud/"
when you use uWSGI.
The Nextcloud package comes with a .htaccess
that already takes care of a lot of rewriting and header stuff. Run occ maintenance:update:htaccess
to adapt this file. Parameter htaccess.RewriteBase
in /etc/webapps/nextcloud/config/config.php
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 php.ini
). Create a drop-in file and add:
/etc/systemd/system/nextcloud-cron.service.d/override.conf
[Service] ExecStart= ExecStart=/usr/bin/php-legacy -c /etc/webapps/nextcloud/php.ini -f /usr/share/webapps/nextcloud/cron.php
After that enable and start nextcloud-cron.timer
(not the service).
As recommended by the documentation add the parameter
/etc/webapps/nextcloud/config/config.php
.... 'maintenance_window_start' => 0, ....
to Nextcloud's configuration file. The value is the hour of the day in UTC defining the start of a 4 hours window. Time consuming jobs that need to be run only once a day will be scheduled in this time frame, i.e. outside working hours.
In-memory caching
Nextcloud's documentation recommends to apply some kind of in-memory object cache to significantly improve performance.
APCu
Install php-legacy-apcu (as dependency --asdeps
). Enable the extension in the relevant configuration files. These are
/etc/webapps/nextcloud/php.ini
used by theocc
command and the background jobs and- depending on the application server you use either
/etc/uwsgi/nextcloud.ini
in case of uWSGI or/etc/php-legacy/php-fpm.d/nextcloud.conf
in case of FPM.
In /etc/webapps/nextcloud/php.ini
add the lines
/etc/webapps/nextcloud/php.ini
extension=apcu apc.ttl=7200 apc.enable_cli = 1
(preferably somewhere below Module Settings
).
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-legacy/php.ini
or /etc/php-legacy/conf.d/apcu.ini
.
Restart your application server (not the web server as Nextcloud's documentation claims). Add the following line to your Nextcloud configuration file:
/etc/webapps/nextcloud/config/config.php
'memcache.local' => '\OC\Memcache\APCu',
Redis
Install php-legacy-igbinary and php-legacy-redis (as dependency --asdeps
) in case you run this component locally (i.e. on the same host as Nextcloud). Alternatively the Redis server can be run on a different machine. For more information see Nextcloud's documentation.
Enable the required extensions igbinary
and redis
in the relevant configuration files. These are:
/etc/webapps/nextcloud/php.ini
used by theocc
command and the background jobs and- depending on the application server you use either
/etc/uwsgi/nextcloud.ini
in case of uWSGI or/etc/php-legacy/php-fpm.d/nextcloud.conf
in case of FPM.
Locate the existing sections where other extensions are enabled and add two additional lines corresponding to igbinary
and redis
.
extension=igbinary
before extension=redis
. Otherwise occ
will report an error (/usr/lib/php-legacy/modules/redis.so: undefined symbol: igbinary_serialize).In case you have specified the open_basedir
option in the above configuration files and use Redis locally with a local Unix socket, you have to extend the list of directories where PHP is allowed to read and write files. Locate the relevant lines in the files specified above and add the directory containing the local Unix socket created by Redis, e.g. /run/redis
.
open_basedir
enabled. So in case you use a copy of one of these files you have to adapt it.Extend your Nextcloud configuration as follows:
/etc/webapps/nextcloud/config/config.php
'memcache.local' => '\OC\Memcache\APCu', 'memcache.distributed' => '\OC\Memcache\Redis', 'memcache.locking' => '\OC\Memcache\Redis', 'redis' => [ 'host' => '/run/redis/redis.sock', 'port' => 0, 'dbindex' => 0, 'password' => '', 'timeout' => 1.5, ],
Again, adapt /run/redis/redis.sock
as required. dbindex
, password
and timeout
are optional.
In case Redis runs on a different machine:
/etc/webapps/nextcloud/config/config.php
'memcache.local' => '\OC\Memcache\APCu', 'memcache.distributed' => '\OC\Memcache\Redis', 'memcache.locking' => '\OC\Memcache\Redis', 'redis' => [ 'host' => 'redis-host.mysite.com', 'port' => 6379, ],
redis-host.mysite.com
is just a placeholder. Adapt to your actual setup.
Security Hardening
See the Nextcloud documentation and Security. Nextcloud additionally provides a Security scanner.
Synchronization
Desktop
The official client can be installed with the nextcloud-client package. Alternative versions are available in the AUR: nextcloud-client-gitAUR. Please keep in mind that using owncloud-client 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 nextcloud-client (pacman -Qi nextcloud-client
). E.g. Nautilus (Gnome) requires nautilus-python. Install as dependent package with pacman -S --asdeps
).
Thunderbird
Since version 102 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). See Nextcloud's documentation for details.
Mounting files with davfs2
If you want to mount your Nextcloud using WebDAV, install davfs2AUR (as described in davfs2).
To mount your Nextcloud, use:
# mount -t davfs https://cloud.mysite.com/remote.php/dav/files/username/ /path/to/mount
You can also create an entry for this in /etc/fstab
:
/etc/fstab
https://cloud.mysite.com/remote.php/dav/files/username/ /path/to/mount davfs rw,user,noauto 0 0
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. https://cloud.mysite.com/remote.php/webdav/
) but replace the protocol name https
by davs
. 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.
https://cloud.mysite.com
) 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 /usr/share/webapps/nextcloud/occ
is provided with /usr/bin/occ
which automatically runs as the default user (nextcloud), using the default PHP executable and PHP configuration file. The environment variables NEXTCLOUD_USER
, NEXTCLOUD_PHP
and NEXTCLOUD_PHP_CONFIG
can be used to specify a non-default user, PHP executable and PHP configuration file (respectively). Especially the latter (using NEXTCLOUD_PHP_CONFIG
) 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 export NEXTCLOUD_PHP_CONFIG=/etc/webapps/nextcloud/php.ini
in your .bashrc
.
When using package php instead of the recommended package php-legacy you also have to set NEXTCLOUD_PHP
, i.e. export NEXTCLOUD_PHP=/usr/bin/php
.
apc.enable_cli=1
in /etc/webapps/nextcloud/php.ini
. Otherwise the occ
command will complain about APCu not being configured properly.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 /usr/share/doc/nextcloud/nextcloud.hook
.
Unfortunately, this hook unconditionally uses the global php.ini
when running occ upgrade
, i.e. it does not take into account the value of environment variable NEXTCLOUD_PHP_CONFIG
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:
# mkdir -vp /etc/pacman.d/hooks # cp -a /usr/share/doc/nextcloud/nextcloud.hook /etc/pacman.d/hooks/10-nextcloud.hook
and change the line starting with Exec
to:
/etc/pacman.d/hooks/10-nextcloud.hook
Exec = /usr/bin/runuser -u nextcloud -- /usr/bin/php-legacy --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. cloud.mysite.com
. If you would like to have Nextcloud located in a subdirectory. e.g. www.mysite.com/nextcloud
, then:
- For nginx refer to the section in Nextcloud's documentation that explicitly covers this topic.
- For apache edit the
/etc/httpd/conf/extra/nextcloud.conf
you included and comment out the<VirtualHost *:80> ... </VirtualHost>
part of the include file.
.well-known
URLs for service discovery. For more information please see Service discovery in Nextcloud's documentation.Docker
See the Nextcloud repository on Docker Hub for running Nextcloud in Docker.
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 recommendations app using occ app:disable recommendations
.
Backup calendars and address books with calcardbackup
The calcardbackupAUR package can be installed and configured to provide regular backups of the calendar and/or address book databases. Edit /etc/calcardbackup/calcardbackup.conf
to your liking and then start and enable calcardbackup.timer
.
Troubleshooting
Reading the log
By default, the logs of the web application are available in /var/log/nextcloud/nextcloud.log
. The entries (lines) are in JSON format and can be very long. Readability can be greatly improved by using jq:
# jq . </var/log/nextcloud/nextcloud.log | less
Work around "is_file(): open_basedir restriction in effect"
With Nextcloud v28.0.4 a regression was introduced that manifests in error messages containing
is_file(): open_basedir restriction in effect
in the log file /var/log/nextcloud/nextcloud.log
. The file path given after this messages is missing one slash at one position, whereas at another position there is one too many, e.g.
File (/usr/share/webapps/nextcloudapps//dav/l10n/de.js)
This is a known bug that has already been fixed and backported to v28.0.5. For v28.0.4 you may apply the following work-around:
- Add a symbolic link
/usr/share/webapps/nextcloudapps
pointing to/usr/share/webapps/nextcloud/apps
# cd /usr/share/webapps # ln -sf nextcloud/apps nextcloudapps
- Add the path of this symbolic link to the
open_basedir
settings relevant for your Nextcloud installation. These are:
/etc/webapps/nextcloud/php.ini
open_basedir=...:/usr/share/webapps/nextcloudapps:...
and depending on the application server you use either (FPM)
/etc/php-legacy/php-fpm.d/nextcloud.conf
php_value[open_basedir] = ...:/usr/share/webapps/nextcloudapps:...
or (uWSGI)
/etc/uwsgi/nextcloud.ini
php-set = open_basedir=...:/usr/share/webapps/nextcloudapps:...
With v28.0.5 you should be able to roll back this work-around again.
Upgrading v27 to v28
Upgrading a version 27 installation to version 28 requires the following steps:
Install and enable extension sodium
With version 28 it is recommended to install and enable PHP extension sodium that provides the argon2 hashing algorithm. Install the corresponding package php-legacy-sodium as a dependency (i.e. with --asdeps
) and enable it in two places:
/etc/webapps/nextcloud/php.ini
used by theocc
command and the background jobs and- depending on the application server you use either
/etc/uwsgi/nextcloud.ini
in case of uWSGI or/etc/php-legacy/php-fpm.d/nextcloud.conf
in case of FPM.
Just look for the existing sections where other extensions are enabled and add an additional line corresponding to sodium
.
Add maintenance_window_start to configuration
It is recommended to add parameter maintenance_window_start
to Nextcloud's configuration file /etc/webapps/nextcloud/config/config.php
. See section #Background jobs and Nextcloud's documentation for details.
Work around "ResourceLocator can not find a web root"
Up until version 28.0.3 Nextcloud suffers a regression that manifests in the log /var/log/nextcloud/nextcloud.log
being flooded with messages like
- ResourceLocator can not find a web root
See the corresponding GitHub ticket. Fortunately, the issue has no impact on Nextcloud's functionality, but real problems may become burried in this log noise. The work-around is to change Nextcloud's configuration file:
/etc/webapps/nextcloud/config/config.php
'apps_paths' => array ( 0 => array ( 'path' => '/usr/share/webapps/nextcloud/apps', 'url' => '/apps', 'writable' => false, ), 1 => array ( 'path' => '/usr/share/webapps/nextcloud/wapps', 'url' => '/wapps', 'writable' => true, ), ),
/usr/share/webapps/nextcloud/wapps
is a symlink to /var/lib/nextcloud/apps
. It is part of the nextcloud package - so usually is already present. If it does not exist for whatever reason create it with:
# ln -sf /var/lib/nextcloud/apps /usr/share/webapps/nextcloud/wapps
When the issue has been resolved the path
can be changed back to /var/lib/nextcloud/apps
.
Migrating to php-legacy
In the past it had happened several times that the php package was updated to the latest PHP version in a timely manner (in line with Arch Linux' rolling release philosophy) but Nextcloud not being compatible with this brand new version - breaking existing installations and causing lots of efforts for maintainers and users of package nextcloud. When package php switched from version 8.1 to version 8.2 this was about to happen once again.
To avoid this frequent hassle a new set of php-legacy packages has been introduced by that time. These will follow the oldest but still actively supported PHP branch. Package nextcloud has been modified to depend on meta package php-interpreter which is provided by php and php-legacy. This way users of package nextcloud have the choice to build their Nextcloud installation either on top of php or on top of php-legacy.
It is highly recommended to go for php-legacy. With this only slightly aged version of PHP it will be very unlikely that a system upgrade renders an existing Nextcloud installation unusable.
Migrating to php-legacy requires some manual actions. Depending on your actual setup a subset of the following tasks must be applied:
PHP extensions
Replace php extensions by their corresponding php-legacy counterparts. For example
$ pacman -R php-apcu php-fpm php-gd php-imagick php-pgsql $ pacman -S --asdeps php-legacy-apcu php-legacy-gd php-legacy-fpm php-legacy-imagick php-legacy-pgsql
The former extension php-intl is an exception as it has become an integral part of php and php-legacy. So there is no need to explicitly take care of this package here.
The actual set of PHP extensions is subject to the database, the in-memory object cache, the application server and other factors. Of course, in case another application depends on the most recent PHP version the non-legacy module may still be needed. Same applies for php itself.
Nextcloud specific copy of php.ini
/etc/webapps/nextcloud/php.ini
open_basedir=...:/usr/lib/php-legacy/modules:... extension_dir = "/usr/lib/php-legacy/modules/" ;extension=imap <= to be deleted
FPM configuration
(This only applies if the application server FPM is used.)
$ mv /etc/php/php-fpm.ini /etc/php-legacy/php-fpm.ini $ mv /etc/php/php-fpm.d/nextcloud.conf /etc/php-legacy/php-fpm.d/nextcloud.conf
Modify /etc/php-legacy/php-fpm.ini
/etc/php-legacy/php-fpm.ini
extension_dir = "/usr/lib/php-legacy/modules/" ;extension=imap <= to be deleted
Modify /etc/php-legacy/php-fpm.d/nextcloud.conf
/etc/php-legacy/php-fpm.d/nextcloud.conf
listen = /run/php-fpm-legacy/nextcloud.sock ; It's available in: /usr/share/php-legacy/fpm/status.html access.log = /var/log/php-fpm-legacy/access/$pool.log ; uncomment if php-imap is installed and used <= to be deleted ; php_value[extension] = imap <= to be deleted
Optional, but recommended: Make www.conf
a no-op while still being able to track modifications of this file that might come in with future updates of php-legacy-fpm
$ mv /etc/php-legacy/php-fpm.d/www.conf /etc/php-legacy/php-fpm.d/www.conf.package $ echo "; just a no-op" > /etc/php-legacy/php-fpm.d/www.conf
Stop and disable the systemd service php-fpm.service. Create a drop-in file for php-fpm-legacy.service:
/etc/systemd/system/php-fpm-legacy.service.d/override.conf
[Service] ExecStart= ExecStart=/usr/bin/php-fpm-legacy --nodaemonize --fpm-config /etc/php-legacy/php-fpm.conf --php-ini /etc/php-legacy/php-fpm.ini ReadWritePaths=/var/lib/nextcloud ReadWritePaths=/etc/webapps/nextcloud/config
Enable and start the systemd service php-fpm-legacy.service.
uWSGI configuration
(This only applies if the application server uWSGI is used.)
/etc/uwsgi/nextcloud.ini
php-set = open_basedir=...:/usr/lib/php-legacy/modules... # uncomment if php-imap is installed and used <= to be deleted # php-set = extension=imap <= to be deleted
Nginx configuration
Modify the file where the forwarding of certain requests to the application server is configured. In case of FPM e.g.
cloud.mysite.com.conf
fastcgi_pass unix:/run/php-fpm-legacy/nextcloud.sock;
In case of uWSGI no adaptation is required.
Apache HTTP server configuration
In case you use Apache's HTTP server and FPM as application server adapt this line in your configuration
SetHandler "proxy:unix:/run/php-fpm-legacy/nextcloud.sock|fcgi://nextcloud/"
In case of uWSGI no adaptation is required.
Background jobs
Update the drop-in file for Nextcloud's scheduled background job:
/etc/systemd/system/nextcloud-cron.service.d/override.conf
[Service] ExecStart= ExecStart=/usr/bin/php-legacy -c /etc/webapps/nextcloud/php.ini -f /usr/share/webapps/nextcloud/cron.php
Pacman hook
The pacman hook /etc/pacman.d/hooks/10-nextcloud.hook
needs to be adapted as well. Change the line starting with Exec
to:
/etc/pacman.d/hooks/10-nextcloud.hook
Exec = /usr/bin/runuser -u nextcloud -- /usr/bin/php-legacy --php-ini /etc/webapps/nextcloud/php.ini /usr/share/webapps/nextcloud/occ upgrade
Otherwise during the next upgrade of Nextcloud pacman will complain about /usr/bin/php
not being found.
Cleanup
Do not forget to cleanup files and directories that may have become obsolete. Potential candidates are:
/usr/lib/php /etc/php
Weird behavior of one or more apps
There are two locations where folders with files of Nextcloud's apps can be found:
/usr/share/webapps/nextcloud/apps
(aka read-only apps directory). This is where the nextcloud package and the app packages (e.g. nextcloud-app-contacts) 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 theocc app:install
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:
Uncaught Error: Could not find initial state contactsinteraction of contacts
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
# cd /usr/share/webapps/nextcloud/apps # pacman -Qo * >/dev/null
All folders reported with
error: No package owns ....
(and that can also be found in the writeable apps directory) can be safely deleted from /usr/share/webapps/nextcloud/apps
. Other double installed apps (i.e. those belonging to a package) should be removed from /var/lib/nextcloud/apps
.
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
occ db:convert-type
. See Nextcloud's documentation for details.
Issues with permissions and setup after upgrade to >= 21.0.0
http
user. This is a security concern in regards to cross-application access of this user (it has access to all data of all web applications).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
/var/lib/nextcloud/data
- 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
nextcloud
user - the web application configuration file resides in
/etc/webapps/nextcloud/config/
and that that directory and its contents are writable and owned by thenextcloud
user - an application server, such as FPM or uWSGI is configured to run the web application as the
nextcloud
user and not thehttp
user - update the cron job/systemd timer to run with the new user
- Finally allow read access to the nextcloud installation
/usr/share/webapps/nextcloud
to your web-server userhttp
by doing:
# chown -R nextcloud:http /usr/share/webapps/nextcloud
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.
/var/lib/nextcloud
should look like this:
drwxr-xr-x 6 nextcloud nextcloud 4096 17. Apr 00:56 ./ drwxr-xr-x 21 root root 4096 17. Apr 00:53 ../ drwxr-xr-x 2 nextcloud nextcloud 4096 16. Feb 00:21 apps/ drwxrwx--- 10 nextcloud nextcloud 4096 16. Apr 13:46 data/ drwx------ 2 nextcloud nextcloud 4096 17. Apr 01:04 sessions/
Also, this can be caused by a full system-partition caused by an extensive size of nextcloud.log because of this bug. In this case, truncating the log-file and disabling the preview-generator or setting the log-level to 4 in config.php and restarting Nextcloud helps.
Environment variables not available
Depending on what application server you use custom environment variables can be provided to Nextcloud's PHP code.
FPM
Add one or more lines in /etc/php-legacy/php-fpm.d/nextcloud.conf
as per Nextcloud's documentation, e.g.:
/etc/php-legacy/php-fpm.d/nextcloud.conf
env[PATH] = /usr/local/bin:/usr/bin:/bin
uWSGI
Add one or more lines in /etc/uwsgi/nextcloud.ini
, e.g.:
/etc/uwsgi/nextcloud.ini
env = PATH=/usr/local/bin:/usr/bin:/bin
Mind there must not be any blanks around the second =
.
You are accessing your instance over a secure connection, however your instance is generating insecure URLs
If you get the following message in your administration settings:
- You are accessing your instance over a secure connection, however your instance is generating insecure URLs. This most likely means that you are behind a reverse proxy and the overwrite config variables are not set correctly. Please read the documentation page about this.
Add the following in your configuration file: [7]
/etc/webapps/nextcloud/config/config.php
'trusted_proxies' => ['192.168.1.0'], 'overwriteprotocol' => 'https',
Replace 192.168.1.0
with your public IP.
Nextcloud reports corrupted index (MariaDB)
If Nextcloud reports corrupted indices (e.g. during occ db:
commands or in Administration > Logging) you can repair your database by executing:
$ mysqlcheck --check --auto-repair nextcloud -u nextcloud -p
If the command fails, it still will point out the table TABLE
containing a corrupted index. Repair it by logging into mariadb:
$ mysql -u nextcloud -p mysql> use nextcloud; mysql> check table TABLE; mysql> optimize table TABLE; mysql> exit;
Replace TABLE
to match your findings.
Failed to fetch the Collabora capabilities endpoint
In case you get responses with:
- Failed to fetch the Collabora capabilities endpoint: Client error: `GET http://localhost/wapps/richdocumentscode/proxy.php?req=/hosting/capabilities` resulted in a `404 Not Found` response
double-check your config.php
that entry overwrite.cli.url
has been set as described in section Configuration / Nextcloud.