diff options
Diffstat (limited to 'nixos/modules/services/web-apps/nextcloud.md')
| -rw-r--r-- | nixos/modules/services/web-apps/nextcloud.md | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/nixos/modules/services/web-apps/nextcloud.md b/nixos/modules/services/web-apps/nextcloud.md new file mode 100644 index 000000000000..014807f3da23 --- /dev/null +++ b/nixos/modules/services/web-apps/nextcloud.md @@ -0,0 +1,237 @@ +# 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 `nextcloud25` 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) +optionally supports +[`services.nginx`](#opt-services.nginx.enable)) +and a database (it's recommended to use +[`services.postgresql`](#opt-services.postgresql.enable)). + +A very basic configuration may look like this: +``` +{ pkgs, ... }: +{ + services.nextcloud = { + enable = true; + hostName = "nextcloud.tld"; + config = { + dbtype = "pgsql"; + dbuser = "nextcloud"; + dbhost = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself + dbname = "nextcloud"; + adminpassFile = "/path/to/admin-pass-file"; + adminuser = "root"; + }; + }; + + services.postgresql = { + enable = true; + ensureDatabases = [ "nextcloud" ]; + ensureUsers = [ + { name = "nextcloud"; + ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES"; + } + ]; + }; + + # ensure that postgres is running *before* running the setup + systemd.services."nextcloud-setup" = { + requires = ["postgresql.service"]; + after = ["postgresql.service"]; + }; + + 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']`](http://php.net/manual/en/reserved.variables.server.php)) +it's needed to add them to +[`services.nextcloud.config.extraTrustedDomains`](#opt-services.nextcloud.config.extraTrustedDomains). + +Auto updates for Nextcloud apps can be enabled using +[`services.nextcloud.autoUpdateApps`](#opt-services.nextcloud.autoUpdateApps.enable). + +## 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 + touched manually because of that. + + ::: {.warning} + Don't delete {file}`config.php`! This file + tracks the application's state and a deletion can cause unwanted + side-effects! + ::: + + ::: {.warning} + Don't rerun `nextcloud-occ maintenance:install`! + This command tries to install the application + and can cause unwanted side-effects! + ::: + - **Multiple version upgrades.** + Nextcloud doesn't allow to move more than one major-version forward. E.g., if you're on + `v16`, you cannot upgrade to `v18`, you need to upgrade to + `v17` first. This is ensured automatically as long as the + [stateVersion](#opt-system.stateVersion) is declared properly. In that case + the oldest version available (one major behind the one from the previous NixOS + release) will be selected by default and the module will generate a warning that reminds + the user to upgrade to latest Nextcloud *after* that deploy. + - **`Error: Command "upgrade" is not defined.`** + This error usually occurs if the initial installation + ({command}`nextcloud-occ maintenance:install`) has failed. After that, the application + is not installed, but the upgrade is attempted to be executed. Further context can + be found in [NixOS/nixpkgs#111175](https://github.com/NixOS/nixpkgs/issues/111175). + + First of all, it makes sense to find out what went wrong by looking at the logs + of the installation via {command}`journalctl -u nextcloud-setup` and try to fix + the underlying issue. + + - If this occurs on an *existing* setup, this is most likely because + the maintenance mode is active. It can be deactivated by running + {command}`nextcloud-occ maintenance:mode --off`. It's advisable though to + check the logs first on why the maintenance mode was activated. + - ::: {.warning} + Only perform the following measures on + *freshly installed instances!* + ::: + + A re-run of the installer can be forced by *deleting* + {file}`/var/lib/nextcloud/config/config.php`. This is the only time + advisable because the fresh install doesn't have any state that can be lost. + In case that doesn't help, an entire re-creation can be forced via + {command}`rm -rf ~nextcloud/`. + + - **Server-side encryption.** + Nextcloud supports [server-side encryption (SSE)](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html). + This is not an end-to-end encryption, but can be used to encrypt files that will be persisted + to external storage such as S3. Please note that this won't work anymore when using OpenSSL 3 + for PHP's openssl extension because this is implemented using the legacy cipher RC4. + If [](#opt-system.stateVersion) is *above* `22.05`, + this is disabled by default. To turn it on again and for further information please refer to + [](#opt-services.nextcloud.enableBrokenCiphersForSSE). + +## Using an alternative webserver as reverse-proxy (e.g. `httpd`) {#module-services-nextcloud-httpd} + +By default, `nginx` is used as reverse-proxy for `nextcloud`. +However, it's possible to use e.g. `httpd` by explicitly disabling +`nginx` using [](#opt-services.nginx.enable) and fixing the +settings `listen.owner` & `listen.group` in the +[corresponding `phpfpm` pool](#opt-services.phpfpm.pools). + +An exemplary configuration may look like this: +``` +{ config, lib, pkgs, ... }: { + services.nginx.enable = false; + services.nextcloud = { + enable = true; + hostName = "localhost"; + + /* further, required options */ + }; + services.phpfpm.pools.nextcloud.settings = { + "listen.owner" = config.services.httpd.user; + "listen.group" = config.services.httpd.group; + }; + services.httpd = { + enable = true; + adminAddr = "webmaster@localhost"; + extraModules = [ "proxy_fcgi" ]; + virtualHosts."localhost" = { + documentRoot = config.services.nextcloud.package; + extraConfig = '' + <Directory "${config.services.nextcloud.package}"> + <FilesMatch "\.php$"> + <If "-f %{REQUEST_FILENAME}"> + SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/" + </If> + </FilesMatch> + <IfModule mod_rewrite.c> + RewriteEngine On + RewriteBase / + RewriteRule ^index\.php$ - [L] + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule . /index.php [L] + </IfModule> + DirectoryIndex index.php + Require all granted + Options +FollowSymLinks + </Directory> + ''; + }; + }; +} +``` + +## Installing Apps and PHP extensions {#installing-apps-php-extensions-nextcloud} + +Nextcloud apps are installed statefully through the web interface. +Some apps may require extra PHP extensions to be installed. +This can be configured with the [](#opt-services.nextcloud.phpExtraExtensions) setting. + +Alternatively, extra apps can also be declared with the [](#opt-services.nextcloud.extraApps) setting. +When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps +that are managed by Nix. If you want automatic updates it is recommended that you use web interface to install apps. + +## Maintainer information {#module-services-nextcloud-maintainer-info} + +As stated in the previous paragraph, we must provide a clean upgrade-path for Nextcloud +since it cannot move more than one major version forward on a single upgrade. This chapter +adds some notes how Nextcloud updates should be rolled out in the future. + +While minor and patch-level updates are no problem and can be done directly in the +package-expression (and should be backported to supported stable branches after that), +major-releases should be added in a new attribute (e.g. Nextcloud `v19.0.0` +should be available in `nixpkgs` as `pkgs.nextcloud19`). +To provide simple upgrade paths it's generally useful to backport those as well to stable +branches. As long as the package-default isn't altered, this won't break existing setups. +After that, the versioning-warning in the `nextcloud`-module should be +updated to make sure that the +[package](#opt-services.nextcloud.package)-option selects the latest version +on fresh setups. + +If major-releases will be abandoned by upstream, we should check first if those are needed +in NixOS for a safe upgrade-path before removing those. In that case we should keep those +packages, but mark them as insecure in an expression like this (in +`<nixpkgs/pkgs/servers/nextcloud/default.nix>`): +``` +/* ... */ +{ + nextcloud17 = generic { + version = "17.0.x"; + sha256 = "0000000000000000000000000000000000000000000000000000"; + eol = true; + }; +} +``` + +Ideally we should make sure that it's possible to jump two NixOS versions forward: +i.e. the warnings and the logic in the module should guard a user to upgrade from a +Nextcloud on e.g. 19.09 to a Nextcloud on 20.09. |