Nextcloud - ArchWiki

Jump to content

# Nextcloud

From ArchWiki

Related articles

- Apache HTTP Server
- Nginx
- UWSGI
- OpenSSL
- WebDAV

From Wikipedia:Nextcloud:

  Nextcloud is a suite of client-server software for creating and using file hosting services. It is functionally similar to Dropbox, although Nextcloud is free and open-source, allowing anyone to install and operate it on a private server. In contrast to proprietary services like Dropbox, the open architecture allows adding additional functionality to the server in form of applications.

Nextcloud is a fork of ownCloud. For differences between the two, see Wikipedia:Nextcloud#Differences from ownCloud.

Note: For version 23 Nextcloud's PHP code has been extensively patched for the Arch Linux package to achieve PHP 8.1 compatibility. The downside of this is that Nextcloud's built-in code integrity check fails for all patched files. The corresponding warnings in the admin's view can be ignored. Version 24 is expected to be compatible with PHP 8.1 and is scheduled for early May.

## Setup overview

A complete installation of Nextcloud comprises (at least) the following components:

A web server paired with an application server on which runs Nextcloud (i.e. the PHP code) using a database.

This article will cover MariaDB/MySQL and PostgreSQL as databases and the following combinations of web server and application server:

- nginx → uWSGI (plus uwsgi-plugin-php)
- nginx → php-fpm,
- Apache (using mod_proxy_uwsgi) → uWSGI (plus uwsgi-plugin-php)
- Apache (using mod_proxy_fcgi) → php-fpm

The Nextcloud package complies with the web application package guidelines. Among other things this mandates that the web application to be run with a dedicated user - in this case `nextcloud`. This is one of the reasons why the application server comes into play here. For the very same reason it is not possible anymore to execute Nextcloud's PHP code directly in the Apache process by means of php-apache.

## Installation

Install the nextcloud package. This will pull in quite a few dependent packages. All required PHP extensions will be taken care of this way. Additionally install the recommended packages php-imagick for preview generation and php-intl for increased translation performance and fixed sorting (preferrably as dependent package with pacman option `--asdeps`). Other optional dependencies will be covered later depending on your concrete setup (e.g. which database you choose).

## Configuration

### PHP

This guide does not tamper with PHP's central configuration file `/etc/php/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/php.ini` (for the `occ` command line tool and the background job).
- Corresponding settings in the configuration of the application server. These will be covered in the section about application servers.

Make a copy of `/etc/php/php.ini` in `/etc/webapps/nextcloud`. Although not strictly necessary change ownership of the copy:

    chown nextcloud:nextcloud /etc/webapps/nextcloud/php.ini

Most of the prerequisites listed in Nextcloud's installation instructions are already enabled in a bare PHP installation. Additionally enable the following extensions:

    /etc/webapps/nextcloud/php.ini

    extension=bcmath
    extension=bz2
    extension=exif
    extension=gd
    extension=iconv
    ; in case you installed php-imagick (as recommended)
    extension=imagick
    ; in case you also installed php-intl (as recommended)
    extension=intl

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/data:/var/lib/nextcloud/apps:/tmp:/usr/share/webapps/nextcloud:/etc/webapps/nextcloud:/dev/urandom:/usr/lib/php/modules:/var/log/nextcloud:/proc/meminfo

Depending on which additional extensions you configure you may need to extend this list, e.g. `/run/redis` in case you opt for Redis.

It is not necessary to configure opcache here as this `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.example.org',
      ),
    'overwrite.cli.url' => 'https://cloud.example.org/',
    'htaccess.RewriteBase' => '/',

Adapt the given example hostname `cloud.example.com`. In case your Nextcloud installation will be reachable via a subfolder (e.g. `https://www.example.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` 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 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

Note: Surprisingly Nextcloud is not compatible with MariaDB version 10.6 or higher (see FS#71549). This is due to MariaDB forcing read-only for compressed InnoDB tables[3] and Nextcloud using these kind of tables:

  From MariaDB 10.6.0, tables that are of the `COMPRESSED` row format are read-only by default. This is the first step towards removing write support and deprecating the feature.

Upstream is aware of this problem but a quick fix seems unlikely.

One easy remedy for this issue is to allow write access to compressed InnoDB tables again by means of MariaDB's system variable innodb_read_only_compressed. Just add the following section to your configuration of MariaDB:

    /etc/my.cnf.d/server.cnf

    [mariadb-10.6]
    innodb_read_only_compressed=OFF

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 'xxxxxxxx';
    CREATE DATABASE IF NOT EXISTS nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
    GRANT ALL PRIVILEGES on nextcloud.* to 'nextcloud'@'localhost';
    FLUSH privileges;

(`XXXXXXXX` 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 [4].

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=xxxxxxxx \
        --admin-pass=zzzzzzzz \
        --admin-email=aaaa@bbbbb \
        --data-dir=/var/lib/nextcloud/data

Mind the placeholders (e.g. `xxxxxxxx`) 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.

### 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 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`

    runuser -u postgres -- psql

and create the database user `nextcloud` and the database of the same name

    CREATE USER nextcloud WITH PASSWORD 'xxxxxxxx';
    CREATE DATABASE nextcloud TEMPLATE template0 ENCODING 'UNICODE';
    ALTER DATABASE nextcloud OWNER TO nextcloud;
    GRANT ALL PRIVILEGES ON DATABASE nextcloud TO nextcloud;
    \q

(`xxxxxxxx` is a placeholder for the passwort of database user nextcloud that you have to choose.)

Install the additional package php-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=xxxxxxxx \
        --admin-pass=zzzzzzzz \
        --admin-email=aaaa@bbbbb \
        --data-dir=/var/lib/nextcloud/data

Mind the placeholders (e.g. `xxxxxxxx`) 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.

## Application server

There are two prevalent application servers that can be used to process PHP code: uWSGI or php-fpm. php-fpm as the name suggests is specialized on PHP. The protocol used between the web server and php-fpm is fastcgi. The tool's documentation leaves room for improvement. uWSGI on the other hand can serve code written in a handful of languages by means of language specific plugins. The protocol used is uwsgi (lowercase). The tool is extensively documented - albeit the sheer amount of documentation can become confusing and unwieldy.

Warning: It has to be mentioned that maintenance of uWSGI and especially of its PHP plugin has been sparse lately[5]. 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.

### uWSGI

uWSGI has its own article. A lot of useful information can be found there. Install uwsgi and the plugin uwsgi-plugin-php - 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).

See section Background jobs for arguments why not to configure recurring jobs in this file. In general keep the enabled extensions, extension specific settings and `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`.

Enable and start

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/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.

### php-fpm

In case you opt to use php-fpm as your application server install php-fpm - preferrably as a dependent package (`--asdeps`).

Configuration consists of a copy of `php.ini` relevant for all applications served by php-fpm and a so-called pool file specific for the application (here Nextcloud). Finally you have to tweak the systemd service file.

php-fpm.ini

As stated earlier this article avoids modifications of PHP's central configuration in `/etc/php/php.ini`. Instead create a php-fpm specific copy.

    cp /etc/php/php.ini /etc/php/php-fpm.ini

Make sure it is owned and only writeable by root (`-rw-r--r-- 1 root root ... php-fpm.ini`). Enable the op-cache, i.e. uncomment the line

    ;zend_extension=opcache

and put the following parameters below the existing line `[opcache]`:

    /etc/php/php-fpm.ini

    opcache.enable = 1
    opcache.interned_strings_buffer = 8
    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 php-fpm processes will consistently crash with the very first request.

nextcloud.conf pool file

Next you have to create a so called pool file for php-fpm. It is responsible for spawning dedicated php-fpm processes for the Nextcloud application. Create a file `/etc/php/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`). 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/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 php-fpm.

Tip: The package php-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-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.

php-fpm service

php-fpm is (of course) run as a systemd service. You have to modify the service configuration to be able to run Nextcloud. This is best achieved by means of a drop-in file and add:

    /etc/systemd/system/php-fpm.service.d/override.conf

    [Service]
    ExecStart=
    ExecStart=/usr/bin/php-fpm --nodaemonize --fpm-config /etc/php/php-fpm.conf --php-ini /etc/php/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 php-fpm processes.

Enable and start

Do not forget to enable and start the php-fpm service.

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 php-fpm instead of uWSGI (and it does no harm whatsoever). In case you nevertheless want to get rid of it just add the following lines to `/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. Most likely you will have to copy it into a file with an appropriate name below `/etc/nginx/sites-available` and create the corresponding symbolic link in `/etc/nginx/sites-enabled`.

The usage of the block `upstream php-handler { ... }` is not necessary. Just specify `fastcgi_pass unix:/run/php-fpm/nextcloud.sock;` in the `location` block that deals with forwarding request with PHP URIs to the application server. When using uWSGI instead of php-fpm replace this `location` block with:

    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 php-fpm) you are using, i.e. how and where nginx will pass requests that need to trigger some PHP code. (See above.)
- Configure OCSP stapling.

There is no need to install any additional modules since nginx natively supports both protocols FastCGI and uwsgi.

### Apache httpd

Find lots of useful information in the article about the Apache HTTP Server. Nextcloud's documentation has some sample configuration that can also be found in `/usr/share/doc/nextcloud/apache.example.conf`. Both implicitely rely on mod_php that cannot be used anymore. mod_proxy_fcgi or mod_proxy_uwsgi need to be applied.

Information about how to integrate Apache with php-fpm can be found here in this wiki. uWSGI's documentation has some information about how to integrate Apache with PHP by means of uWSGI and mod_proxy_uwsgi. Mind that the Apache package comes with both modules mod_proxy_fcgi and mod_proxy_uwsgi. They need to be loaded as required.

The following Apache modules are required to run Nextcloud:

    /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 explicitely
    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 php-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.example.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.example.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 (e.g. with systemctl edit) and add:

    /etc/systemd/system/nextcloud-cron.service.d/override.conf

    [Service]
    ExecStart=
    ExecStart=/usr/bin/php -c /etc/webapps/nextcloud/php.ini -f /usr/share/webapps/nextcloud/cron.php

After that enable/start `nextcloud-cron.timer` (not the service).

## In-memory caching

Nextcloud's documentation recommends to apply some kind of in-memory object cache to significantly improve performance. This section demonstrates setup of APCu - mainly to pinpoint the details that differ from the instructions given in Nextcloud's documentation. The other options (Redis and memcached) are also sufficiently covered there.

Install php-apcu (as dependency `--asdeps`). 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 you use uWSGI or
  - `/etc/php/php-fpm.d/nextcloud.conf` in case you use php-fpm.

The parameter to do so is already there and only needs to be uncommented. Two other configuration parameters related to APCu are also already there.

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',

That's it. Enjoy your performance boost!

Note: Mind that push notify (the Nextcloud service that replaces client polling by notification by the server thus drastically reducing sync latency) is dependend on Redis.

## Security Hardening

See the Nextcloud documentation and Security. Nextcloud additionally provides a Security scanner.

## Synchronization

Tip: With all software automatically authenticating against your Nextcloud server it is recommended not to use your personal password but so-called app tokens. 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. 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.

This article or section needs expansion.

Reason: As of 2022-02-06 (desktop client version 3.4.1) the following additional packages do not seem to be necessary any more. Please elaborate in case they still are. (Discuss in Talk:Nextcloud)

Additional packages are needed for some features:

- Auto-login: All of them use qtkeychain-qt5 to store and retrieve account-specific access tokens. To achieve auto-login when the client starts, one of optional dependencies of qtkeychain should be installed as well. Moreover, if you choose libsecret as the backend for qtkeychain, a service that provides org.freedesktop.secrets should be running when the client starts.
- File manager integration: for nextcloud-client, integration with file managers (e.g., show Nextcloud folders in GTK+ file dialogs) requires another package nextcloud-client-cloudproviders. nextcloud-client already includes cloudproviders supports by default.

### Thunderbird

Since version 91 Thunderbird fully supports CalDAV and CardDAV - even with auto detection (i.e. you do not have to provide long URLs to access your calendars and address books). Nextcloud's documentation is not up to date in this respect.

Calendar

There are a few ways how to start the new calendar wizard. One is via the main menu (☰ at the very right) → ➕ New → Calendar… Choose Network and click Next. On the next page enter your username (that on your Nextcloud server) and the top URL of your Nextcloud server (e.g. `https://cloud.mysite.org/`). Click Search calendar. Now provide your password (or even better an app token (see above)). Finally select the calendar(s) you want to see in Thunderbird and click Subscribe. Be sure to mark read-only calendars (e.g. Nextcloud's birtday calendar) as read-only. Otherwise you will repeatably see reminders that you cannot effectively close.

Contacts

Open Thunderbird's address book - e.g. by Shift+Ctrl+B. Choose File → New → CardDAV address book. On the next page enter your username (that on your Nextcloud server) and the top URL of your Nextcloud server (e.g. `https://cloud.mysite.org/`). Click Next. Now provide your password (or even better an app token (see above)). Finally select the address book(s) you want to see in Thunderbird's address book window and click Next.

### Mounting files with davfs2

If you want to mount your Nextcloud using WebDAV, install davfs2AUR (as described in davfs2).

To mount your Nextcloud, use:

    # mount -t davfs https://your_domain/nextcloud/remote.php/dav/files/username/ /path/to/mount

You can also create an entry for this in `/etc/fstab`

    /etc/fstab

    https://your_domain/nextcloud/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') through WebDAV protocol - use the link as shown in your Nextcloud installation Web GUI (typically: https://example.org/remote.php/webdav/) but replace the protocol name from 'https' to '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+):

1. download DAVx5 (Play Store, F-Droid)
2. Enable mod_rewrite.so in httpd.conf
3. create a new DAVdroid account in the Account settings, and specify your "short" server address and login/password couple, e.g. `https://cloud.example.com` (there is no need for the `/remote.php/{carddav,webdav}` part if you configured your web server with the proper redirections, as illustrated previously in the article; 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 `/usr/share/webapps/nextcloud/occ` is provided with `/usr/bin/occ` which automatically runs as the default user (nextcloud), using the default PHP 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 servers, i.e. using PHP configurations specific to Nextcloud. In this case put `export NEXTCLOUD_PHP_CONFIG=/etc/webapps/nextcloud/php.ini` in your `.bashrc`.

Warning: When using php-apcu for caching, make sure to set `apc.enable_cli=1` in `/etc/webapps/nextcloud/php.ini`, as the `occ` command will otherwise run out of memory (FS#69726).

### Pacman hook

To automatically upgrade the Nextcloud database on package update, you can make use of the included pacman hook:

    # mkdir -vp /etc/pacman.d/hooks
    # ln -sv /usr/share/doc/nextcloud/nextcloud.hook /etc/pacman.d/hooks/

Note: The packaged pacman hook implies, that the global `php.ini` is used for the application.

### 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 explicitely 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 ownCloud or Nextcloud repository for 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 reccomends apps to new clients, which can result in a lot of notifications. To disable this, disable the recommendation app using `occ`.

### 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

By default, the logs of the web application are available in `/var/log/nextcloud/nextcloud.log`.

### Issues with permissions and setup after upgrade to >= 21.0.0

Note: Before nextcloud 21.0.0, the web application was run using the `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 the `nextcloud` user
- an application server, such as php-fpm or UWSGI is configured to run the web application as the `nextcloud` user and not the `http` user
- update the cron job/systemd timer to run with the new user

### 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/

### Environment variables not available

Depending on what application server you use custom environment variables can be provided to the Nextcloud's PHP code.

php-fpm

Add one or more lines in `/etc/php/php-fpm.d/nextcloud.conf` as per Nextcloud's documentation, e.g.:

    env[PATH] = /usr/local/bin:/usr/bin:/bin

uwsgi

Add one or more lines in `/etc/uwsgi/nextcloud.ini`, e.g.:

    env = PATH=/usr/local/bin:/usr/bin:/bin

Mind there must not be any blanks around the second `=`.

### Self-signed certificate not accepted

This section is being considered for removal.

Reason: Subsections below and including this one are considered outdated (e.g. mentioning of owncloud). In case you know a certain subsection still applies, please update it and move it above this marker. Any subsection not updated and moved above this marker by 2022-09-30 will be deleted. (Discuss in Talk:Nextcloud)

ownCloud uses Wikipedia:cURL and Wikipedia:SabreDAV to check if WebDAV is enabled. If you use SSL/TLS with a self-signed certificate, e.g. as shown in LAMP, and access ownCloud's admin panel, you will see the following error message:

    Your web server is not yet properly setup to allow files synchronization because the WebDAV interface seems to be broken.

Assuming that you followed the LAMP tutorial, execute the following steps:

Create a local directory for non-distribution certificates and copy LAMPs certificate there. This will prevent `ca-certificates`-updates from overwriting it.

    # cp /etc/httpd/conf/server.crt /usr/share/ca-certificates/WWW.EXAMPLE.COM.crt

Add WWW.EXAMPLE.COM.crt to `/etc/ca-certificates.conf`:

    WWW.EXAMPLE.COM.crt

Now, regenerate your certificate store:

    # update-ca-certificates

Restart the httpd service to activate your certificate.

### Self-signed certificate for Android devices

Once you have followed the setup for SSL, as on Apache HTTP Server#TLS for example, early versions of DAVdroid will reject the connection because the certificate is not trusted. A certificate can be made as follows on your server:

    # openssl x509 -req -days 365 -in /etc/httpd/conf/server.csr -signkey /etc/httpd/conf/server.key -extfile android.txt -out CA.crt
    # openssl x509 -inform PEM -outform DER -in CA.crt -out CA.der.crt

The file `android.txt` should contain the following:

    basicConstraints=CA:true

Then import `CA.der.crt` to your Android device:

Put the `CA.der.crt` file onto the sdcard of your Android device (usually to the internal one, e.g. save from a mail attachment). It should be in the root directory. Go to Settings > Security > Credential storage and select Install from device storage. The `.crt` file will be detected and you will be prompted to enter a certificate name. After importing the certificate, you will find it in Settings > Security > Credential storage > Trusted credentials > User.

Thanks to: [6]

Another way is to import the certificate directly from your server via CAdroid and follow the instructions there.

### CSync failed to find a specific file.

This is most likely a certificate issue. Recreate it, and do not leave the common name empty or you will see the error again.

    # openssl req -new -x509 -nodes -newkey rsa:4096 -keyout server.key -out server.crt

### Seeing white page after login

The cause is probably a new app that you installed. To fix that, you can use the occ command as described here. So with

    # sudo -u http php /usr/share/webapps/nextcloud/occ app:list

you can list all apps (if you installed nextcloud in the standard directory), and with

    # sudo -u http php /usr/share/webapps/nextcloud/occ app:disable <nameOfExtension>

you can disable the troubling app.

Alternatively, you can either use phpMyAdmin to edit the `oc_appconfig` table (if you got lucky and the table has an edit option), or do it by hand with mysql:

    # mysql -u root -p owncloud
    MariaDB [owncloud]> delete from oc_appconfig where appid='<nameOfExtension>' and configkey='enabled' and configvalue='yes';
    MariaDB [owncloud]> insert into oc_appconfig (appid,configkey,configvalue) values ('<nameOfExtension>','enabled','no');

This should delete the relevant configuration from the table and add it again.

### GUI sync client fails to connect

If using HTTP basic authentication, make sure to exclude "status.php", which must be publicly accessible. [7]

### GUI tray icon disappears, but client still running in the background

After waking up from a suspended state, the Nextcloud client tray icon may disappear from the system tray. A workaround is to delay the startup of the client, as noted here. This can be done with the .desktop file, for example:

    .local/share/applications/nextcloud.desktop

    ...
    Exec=bash -c 'sleep 5 && nextcloud'
    ...

### Some files upload, but give an error 'Integrity constraint violation...'

You may see the following error in the ownCloud sync client:

       SQLSTATE[23000]: Integrity constraint violation: ... Duplicate entry '...' for key 'fs_storage_path_hash')...

This is caused by an issue with the File Locking app, which is often not sufficient to keep conflicts from occurring on some webserver configurations. A more complete Transactional File Locking is available that rids these errors, but you must be using the Redis php-caching method. Install redis and php-redis, comment out your current php-cache mechanism, and then in `/etc/php/conf.d/redis.ini` uncomment `extension=redis`. Then in `config.php` make the following changes:

       'memcache.local' => '\OC\Memcache\Redis',
       'filelocking.enabled' => 'true',
       'memcache.locking' => '\OC\Memcache\Redis',
       'redis' => array(
            'host' => 'localhost',
            'port' => 6379,
            'timeout' => 0.0,
             ),

and start/enable `redis.service`.

Finally, disable the File Locking App, as the Transational File Locking will take care of it (and would conflict).

If everything is working, you should see 'Transactional File Locking Enabled' under Server Status on the Admin page, and syncs should no longer cause issues.

### "Cannot write into apps directory"

As mentioned in the official admin manual, either you need an apps directory that is writable by the http user, or you need to set `appstoreenabled` to `false`.

If you have set `open_basedir` in your PHP/web server configuration file (e.g. `/etc/httpd/conf/extra/nextcloud.conf`), it may be necessary to add your /path/to/data directory to the string on the line starting with `php_admin_value open_basedir` :

    /etc/httpd/conf/extra/nextcloud.conf

    php_admin_value open_basedir "/path/to/data/:/srv/http/:/dev/urandom:/tmp/:/usr/share/pear/:/usr/share/webapps/nextcloud/:/etc/webapps/nextcloud"

### Installed apps get blocked because of MIME type error

If you are putting your apps folder outside of the nextcloud installation directory make sure your webserver serves it properly.

In nginx this is accomplished by adding a location block to the nginx configuration as the folder will not be included in it by default.

    location ~ /apps2/(.*)$ {
        alias /var/www/nextcloud/apps/$1;
    }

### CSS and JS resources blocked due to MIME type error

If you load your Nextcloud web gui and it is missing styles etc. check the browser's console logs for lines like:

    The resource from “https://example.com/core/css/guest.css?v=72c34c37-0” was blocked due to MIME type (“text/plain”) mismatch (X-Content-Type-Options: nosniff).

There are a few possible reasons, possibly you have not included any mime types in your `nginx.conf` add the following to `nginx.conf`

    types_hash_max_size 2048;
    types_hash_bucket_size 128;
    include mime.types;

Here we use the `mime.types` provided by mailcap, due to the large number of types included we increase the allowed size of the types hash.

Other possible reasons for these errors are missing permissions on the files. Make sure the files are owned by `http:http` and can be read and written to by this user.

### Security warnings even though the recommended settings have been included in nginx.conf

At the top of the admin page there might be a warning to set the `Strict-Transport-Security`, `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection` and `X-Robots-Tag` according to https://docs.nextcloud.com/server/latest/admin_manual/installation/harden_server.html even though they are already set like that.

A possible cause could be that because owncloud sets those settings, uwsgi passed them along and nginx added them again:

    $ curl -I https://domain.tld

    ...
    X-XSS-Protection: 1; mode=block
    X-Content-Type-Options: nosniff
    X-Frame-Options: Sameorigin
    X-Robots-Tag: none
    Strict-Transport-Security: max-age=15768000; includeSubDomains; preload;
    X-Content-Type-Options: nosniff
    X-Frame-Options: SAMEORIGIN
    X-XSS-Protection: 1; mode=block
    X-Robots-Tag: none

While the fast_cgi sample configuration has a parameter to avoid that ( `fastcgi_param modHeadersAvailable true; #Avoid sending the security headers twice` ), when using uwsgi and nginx the following modification of the uwsgi part in nginx.conf could help:

     /etc/nginx/nginx.conf

    ...
            # pass all .php or .php/path urls to uWSGI
            location ~ ^(.+\.php)(.*)$ {
                include uwsgi_params;
                uwsgi_modifier1 14;
                # hode following headers received from uwsgi, because otherwise we would send them twice since we already add them in nginx itself
                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-Frame-Options;
                #Uncomment line below if you get connection refused error. Remember to commet out line with "uwsgi_pass 127.0.0.1:3001;" below
                uwsgi_pass unix:/run/uwsgi/owncloud.sock;
                #uwsgi_pass 127.0.0.1:3001;
            }
    ...

### "Reading from keychain failed with error: 'No keychain service available'"

Can be fixed for Gnome by installing the following 2 packages, libgnome-keyring and gnome-keyring. Or the following for KDE, libgnome-keyring and qtkeychain-qt5.

### FolderSync: "Method Not Allowed"

FolderSync needs access to `/owncloud/remote.php/webdav`, so you could create another alias for owncloud in your `/etc/httpd/conf/extra/nextcloud.conf`

      <IfModule mod_alias.c>
        Alias /nextcloud /usr/share/webapps/nextcloud/
        Alias /owncloud /usr/share/webapps/nextcloud/
      </IfModule>

### Log file spam

The factual accuracy of this article or section is disputed.

Reason: This section was added 2022-03-08 without referencing an upstream bug, while it might still be relevant, we have no way to know if this issue has been fixed until a link to the issue is provided. (Discuss in Talk:Nextcloud)

The cause could be a too high PHP version. Until this is fixed, the log level in nextcloud's config.php can be adjusted.

## See also

- Nextcloud Documentation Overview
- Nextcloud Admin Manual

Categories:

- File sharing
- Web applications

Hidden categories:

- Pages or sections flagged with Template:Expansion
- Sections flagged with Template:Remove
- Pages or sections flagged with Template:Accuracy