Nextcloud

Related articles
Apache HTTP Server
Nginx
UWSGI
OpenSSL
WebDAV
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:Nextcloud#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. This will pull in quite a few dependent packages. Most of the
required PHP extensions
will be taken care of this way.
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
(preferrably as
dependent package
). 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 the
occ
command line tool and the background job). This is literally a copy of the original
php.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/valkey
in case you opt for
Valkey
.
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
:
NEXTCLOUD_PHP_CONFIG=/etc/webapps/nextcloud/php.ini
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-lts
(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
.
Note
MariaDB has a flawed understanding of what UTF8 means resulting in the inability to store any characters with codepoints 0x10000 and above (e.g. emojis). They 'fixed' this issue with version 5.5 by introducing a new encoding called
utf8mb4
. Bottom line: Never ever use MariaDB's
utf8
, always use
utf8mb4
. In case you need to migrate see
[3]
.
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
(preferrably as
dependent package
) 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
dependent packages
). 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.
Warning
It has to be mentioned that maintenance of uWSGI and especially of its PHP plugin has been sparse lately
[4]
. This has already caused
issues
that could only be solved by patching uWSGI code by the maintainers of Arch Linux packages, i.e. not upstream.
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).
Tip
The changes to
/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 with
diff 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
over
nextcloud.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
(preferably as
dependent package
).
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
Warning
Do not try to put these settings in the pool file by means of
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
.
Tip
The package
php-legacy-fpm
comes with its own pool file
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 the
php-fpm.ini
covered in the previous section.
The directories
/var/lib/nextcloud
and
/etc/webapps/nextcloud/config
(and everything below) are made writable. The
ProtectSystem=full
in the original service definition causes
/usr
,
/boot
and
/etc
to be mounted read-only for the
FPM
processes.
If you want to use
hardware transcoding
(e.g. in the memories app) you need to explicitly allow access to your graphics device as
PrivateDevices=true
hides any devices from the
FPM
processes. For example adding
BindPaths=/dev/dri/renderD128
and
DeviceAllow=/dev/dri/renderD128 rw
to the drop-in file allows usage of a properly configured Intel iGpu.
Do not forget to
enable/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 of
try_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
. (Note that
Let's Encrypt does not support OCSP anymore
, so if you are using a Let's Encrypt certificate, there is no need for this.)
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/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.
Warning
Do not try to install and use
nextcloud-systemd-timers
AUR
. It is outdated and unmaintained.
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
(preferrably as
dependent package
). Enable the extension in the relevant configuration files. These are
/etc/webapps/nextcloud/php.ini
used by the
occ
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',
Valkey (Redis)
Note
Valkey is only necessary for multi-server setups (like clusters with shared cache). It is not necessary for single-machine or personal installations and can be omitted.
Push notify
(the Nextcloud service that replaces client polling by notification by the server thus drastically reducing sync latency) depends on
Valkey
.
Using
Valkey
does not exclude using
APCu
as a local cache. In fact, Nextcloud's documentation recommends using
Redis
(here
Valkey
) and
APCu
in parallel.
Valkey was forked from Redis version 7.2.4 in
March 2024
due to license issues.
Nextcloud's documentation
still only mentions Redis. However, one year later Valkey can still be considered a drop-in replacement for Redis. (Future will show how long this will stand.)
Valkey
can be run locally (i.e. on the same host as
Nextcloud
) or on a different machine. (For more information see
Nextcloud's documentation
.) In any case install
php-legacy-igbinary
and
php-legacy-redis
(preferrably as
dependent packages
).
Enable these extensions in
/etc/webapps/nextcloud/php.ini
and, depending on the application server you use, in
/etc/uwsgi/nextcloud.ini
or
/etc/php-legacy/php-fpm.d/nextcloud.conf
. This can be done by locating the existing sections where other extensions are enabled and adding two additional lines corresponding to
igbinary
and
redis
.
Alternatively, you can enable the required extensions
igbinary
and
redis
in their respective initialization files in
/etc/php-legacy/conf.d/
by uncommenting the
extension=
lines.
Note
It is important to load
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
Valkey
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
Valkey
, e.g.
/run/valkey
.
Note
The sample configuration files
nextcloud.ini
and
nextcloud.conf
mentionend in the
#Application server
section already have
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/valkey/valkey.sock',
     'port'     => 0,
     'dbindex'  => 0,
     'password' => '
',
     'timeout'  => 1.5,
],
Again, adapt
/run/valkey/valkey.sock
as required.
dbindex
,
password
and
timeout
are optional.
In case
Valkey
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' => '
valkey-host.mysite.com
',
     'port' => 6379,
],
valkey-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
Tip
It is recommended not to use your personal password but so-called app tokens for all software automatically authenticating against your Nextcloud server. This way in case you suspect credentials in one of the programs may have leaked you just need to revoke this one affected app token - instead of having to change your personal password and propagating this change to all places where it has been stored. You can generate a new app token in Nextcloud's web GUI in
Settings > Security
in the
Devices & Sessions
section.
Desktop
The official client can be installed with the
nextcloud-client
package. 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
. E.g.
Nautilus
requires
nautilus-python
. Install
as dependent package
.
Note
The desktop client provides a system tray icon that indicates sync status
[5]
, but GNOME does not provide a system tray icon API out-of-the-box
[6]
. If this is a desired feature, one possible solution is to install and enable
gnome-shell-extension-appindicator
. See
GNOME#Extensions
for more info.
By default nextcloud provides a dbus activated service that might be triggered by a lot of randomly seeming things
like opening a file dialog
. You can add the following to your pacman config to disable it, before installing the client.
/etc/pacman.conf
NoExtract = usr/share/dbus-1/services/com.nextcloudgmbh.Nextcloud.service
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
davfs2
(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
Tip
In order to allow automount you can also store your username (and password if you like) in a file as described in
davfs2#Storing credentials
.
Note
If creating/copying files is not possible, while the same operations work on directories, see
davfs2#Creating/copying files not possible and/or freezes
.
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.
Note
Make sure you have installed
gvfs-dnssd
, otherwise you may get an error 'Location is not mountable'.
Android
Download the official Nextcloud app from
Google Play
or
F-Droid
.
To enable contacts and calendar sync (Android 4+):
Download
DAVx
5
(
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.
Note
There is no need for the
/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
.
Warning
When using
php-legacy-apcu
for caching, make sure to set
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.
Note
Do not forget to configure the
.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:
Collabora Online
ONLYOFFICE
MS Office Online Server
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:
Collabora online
,
app
ONLYOFFICE
,
app
MS Office Online Server
,
app
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
calcardbackup
AUR
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
.
Data directory on different drive
Over time the
datadirectory
of you Nextcloud installation will probably grow considerably. The location of this directory is specified in
/usr/share/webapps/nextcloud/config/config.php
, typically:
'datadirectory' => '/var/lib/nextcloud/data',
It is advisable to put this directory on a separate file system with enough space, in many cases on a separate drive. This additionally offers the option to implement some form of redundancy on that file system (aka RAID). A (non-exhaustive) list of options how to accomplish that:
Change the above mentioned configuration entry to point to some other location on a separate file system.
Create a symbolic link at
/var/lib/nextcloud/data
referencing a location on a separate file system.
Mount a separate file system on
/var/lib/nextcloud/data
(or one of its parent directories).
To a lesser extend the same applies for the writable apps directory that is also specified in
/usr/share/webapps/nextcloud/config/config.php
, typically:
'apps_paths' => 
  array (
    0 => ....,
    1 => 
    array (
      'path' => '/var/lib/nextcloud/apps',
      'url' => '/wapps',
      'writable' => true,
    ),
  ),
Do
not
try to change anything with the entry in the same array that has
'writable' => false,
(the so-called read-only apps directory).
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
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 the
occ 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
.
Login page loop
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/
Tip
Use
ls -lahH
path/to/dir
as the
nextcloud
user to follow links and see what it can access.
Also, this can be caused by a full file system due to an extensive size of
nextcloud.log
. In the past there have been bugs flooding the log file with error messages, e.g.
this one
. In this case, truncating the log file and
restarting
uwsgi
or
php-fpm-legacy
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
.
Reset after failed login attempts
To unblock an IP address after too many failed login attempts, run
$ occ security:bruteforce:reset
IP_address
See also
Nextcloud Documentation Overview
Nextcloud Admin Manual