# Nextcloud {#module-services-nextcloud}

[Nextcloud](https://nextcloud.com/) is an open-source,
self-hostable cloud platform. The server setup can be automated using
[services.nextcloud](#opt-services.nextcloud.enable). A
desktop client is packaged at `pkgs.nextcloud-client`.

The current default by NixOS is `nextcloud31` which is also the latest
major version available.

## Basic usage {#module-services-nextcloud-basic-usage}

Nextcloud is a PHP-based application which requires an HTTP server
([`services.nextcloud`](#opt-services.nextcloud.enable)
and optionally supports
[`services.nginx`](#opt-services.nginx.enable)).

For the database, you can set
[`services.nextcloud.config.dbtype`](#opt-services.nextcloud.config.dbtype) to
either `sqlite` (the default), `mysql`, or `pgsql`. The simplest is `sqlite`,
which will be automatically created and managed by the application. For the
last two, you can easily create a local database by setting
[`services.nextcloud.database.createLocally`](#opt-services.nextcloud.database.createLocally)
to `true`, Nextcloud will automatically be configured to connect to it through
socket.

A very basic configuration may look like this:
```nix
{ pkgs, ... }:
{
  services.nextcloud = {
    enable = true;
    hostName = "nextcloud.tld";
    database.createLocally = true;
    config = {
      dbtype = "pgsql";
      adminpassFile = "/path/to/admin-pass-file";
    };
  };

  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
}
```

The `hostName` option is used internally to configure an HTTP
server using [`PHP-FPM`](https://php-fpm.org/)
and `nginx`. The `config` attribute set is
used by the imperative installer and all values are written to an additional file
to ensure that changes can be applied by changing the module's options.

In case the application serves multiple domains (those are checked with
[`$_SERVER['HTTP_HOST']`](https://www.php.net/manual/en/reserved.variables.server.php))
it's needed to add them to
[`services.nextcloud.settings.trusted_domains`](#opt-services.nextcloud.settings.trusted_domains).

Auto updates for Nextcloud apps can be enabled using
[`services.nextcloud.autoUpdateApps`](#opt-services.nextcloud.autoUpdateApps.enable).

## `nextcloud-occ` {#module-services-nextcloud-occ}

The management command [`occ`](https://docs.nextcloud.com/server/stable/admin_manual/occ_command.html) can be
invoked by using the `nextcloud-occ` wrapper that's globally available on a system with Nextcloud enabled.

It requires elevated permissions to become the `nextcloud` user. Given the way the privilege
escalation is implemented, parameters passed via the environment to Nextcloud are
currently ignored, except for `OC_PASS` and `NC_PASS`.

Custom service units that need to run `nextcloud-occ` either need elevated privileges
or the systemd configuration from `nextcloud-setup.service` (recommended):

```nix
{ config, ... }:
{
  systemd.services.my-custom-service = {
    script = ''
      nextcloud-occ …
    '';
    serviceConfig = {
      inherit (config.systemd.services.nextcloud-cron.serviceConfig)
        User
        LoadCredential
        KillMode
        ;
    };
  };
}
```

Please note that the options required are subject to change. Please make sure to read the
release notes when upgrading.

## Common problems {#module-services-nextcloud-pitfalls-during-upgrade}

  - **General notes.**
    Unfortunately Nextcloud appears to be very stateful when it comes to
    managing its own configuration. The config file lives in the home directory
    of the `nextcloud` user (by default
    `/var/lib/nextcloud/config/config.php`) and is also used to
    track several states of the application (e.g., whether installed or not).

     All configuration parameters are also stored in
    {file}`/var/lib/nextcloud/config/override.config.php` which is generated by
    the module and linked from the store to ensure that all values from
    {file}`config.php` can be modified by the module.
    However {file}`config.php` manages the application's state and shouldn't be