pyrox.dev
1# Nextcloud {#module-services-nextcloud}
2
3[Nextcloud](https://nextcloud.com/) is an open-source,
4self-hostable cloud platform. The server setup can be automated using
5[services.nextcloud](#opt-services.nextcloud.enable). A
6desktop client is packaged at `pkgs.nextcloud-client`.
7
8The current default by NixOS is `nextcloud31` which is also the latest
9major version available.
10
11## Basic usage {#module-services-nextcloud-basic-usage}
12
13Nextcloud is a PHP-based application which requires an HTTP server
14([`services.nextcloud`](#opt-services.nextcloud.enable)
15and optionally supports
16[`services.nginx`](#opt-services.nginx.enable)).
17
18For the database, you can set
19[`services.nextcloud.config.dbtype`](#opt-services.nextcloud.config.dbtype) to
20either `sqlite` (the default), `mysql`, or `pgsql`. The simplest is `sqlite`,
21which will be automatically created and managed by the application. For the
22last two, you can easily create a local database by setting
23[`services.nextcloud.database.createLocally`](#opt-services.nextcloud.database.createLocally)
24to `true`, Nextcloud will automatically be configured to connect to it through
25socket.
26
27A very basic configuration may look like this:
28```nix
29{ pkgs, ... }:
30{
31 services.nextcloud = {
32 enable = true;
33 hostName = "nextcloud.tld";
34 database.createLocally = true;
35 config = {
36 dbtype = "pgsql";
37 adminpassFile = "/path/to/admin-pass-file";
38 };
39 };
40
41 networking.firewall.allowedTCPPorts = [ 80 443 ];
42}
43```
44
45The `hostName` option is used internally to configure an HTTP
46server using [`PHP-FPM`](https://php-fpm.org/)
47and `nginx`. The `config` attribute set is
48used by the imperative installer and all values are written to an additional file
49to ensure that changes can be applied by changing the module's options.
50
51In case the application serves multiple domains (those are checked with
52[`$_SERVER['HTTP_HOST']`](https://www.php.net/manual/en/reserved.variables.server.php))
53it's needed to add them to
54[`services.nextcloud.settings.trusted_domains`](#opt-services.nextcloud.settings.trusted_domains).
55
56Auto updates for Nextcloud apps can be enabled using
57[`services.nextcloud.autoUpdateApps`](#opt-services.nextcloud.autoUpdateApps.enable).
58
59## Common problems {#module-services-nextcloud-pitfalls-during-upgrade}
60
61 - **General notes.**
62 Unfortunately Nextcloud appears to be very stateful when it comes to
63 managing its own configuration. The config file lives in the home directory
64 of the `nextcloud` user (by default
65 `/var/lib/nextcloud/config/config.php`) and is also used to
66 track several states of the application (e.g., whether installed or not).
67
68 All configuration parameters are also stored in
69 {file}`/var/lib/nextcloud/config/override.config.php` which is generated by
70 the module and linked from the store to ensure that all values from
71 {file}`config.php` can be modified by the module.
72 However {file}`config.php` manages the application's state and shouldn't be
73 touched manually because of that.
74
75 ::: {.warning}
76 Don't delete {file}`config.php`! This file
77 tracks the application's state and a deletion can cause unwanted
78 side-effects!
79 :::
80
81 ::: {.warning}
82 Don't rerun `nextcloud-occ maintenance:install`!
83 This command tries to install the application
84 and can cause unwanted side-effects!
85 :::
86 - **Multiple version upgrades.**
87 Nextcloud doesn't allow to move more than one major-version forward. E.g., if you're on
88 `v16`, you cannot upgrade to `v18`, you need to upgrade to
89 `v17` first. This is ensured automatically as long as the
90 [stateVersion](#opt-system.stateVersion) is declared properly. In that case
91 the oldest version available (one major behind the one from the previous NixOS
92 release) will be selected by default and the module will generate a warning that reminds
93 the user to upgrade to latest Nextcloud *after* that deploy.
94 - **`Error: Command "upgrade" is not defined.`**
95 This error usually occurs if the initial installation
96 ({command}`nextcloud-occ maintenance:install`) has failed. After that, the application
97 is not installed, but the upgrade is attempted to be executed. Further context can
98 be found in [NixOS/nixpkgs#111175](https://github.com/NixOS/nixpkgs/issues/111175).
99
100 First of all, it makes sense to find out what went wrong by looking at the logs
101 of the installation via {command}`journalctl -u nextcloud-setup` and try to fix
102 the underlying issue.
103
104 - If this occurs on an *existing* setup, this is most likely because
105 the maintenance mode is active. It can be deactivated by running
106 {command}`nextcloud-occ maintenance:mode --off`. It's advisable though to
107 check the logs first on why the maintenance mode was activated.
108 - ::: {.warning}
109 Only perform the following measures on
110 *freshly installed instances!*
111 :::
112
113 A re-run of the installer can be forced by *deleting*
114 {file}`/var/lib/nextcloud/config/config.php`. This is the only time
115 advisable because the fresh install doesn't have any state that can be lost.
116 In case that doesn't help, an entire re-creation can be forced via
117 {command}`rm -rf ~nextcloud/`.
118
119 - **Server-side encryption.**
120 Nextcloud supports [server-side encryption (SSE)](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html).
121 This is not an end-to-end encryption, but can be used to encrypt files that will be persisted
122 to external storage such as S3.
123
124 - **Issues with file permissions / unsafe path transitions**
125
126 {manpage}`systemd-tmpfiles(8)` makes sure that the paths for
127
128 * configuration (including declarative config)
129 * data
130 * app store
131 * home directory itself (usually `/var/lib/nextcloud`)
132
133 are properly set up. However, `systemd-tmpfiles` will refuse to do so
134 if it detects an unsafe path transition, i.e. creating files/directories
135 within a directory that is neither owned by `root` nor by `nextcloud`, the
136 owning user of the files/directories to be created.
137
138 Symptoms of that include
139
140 * `config/override.config.php` not being updated (and the config file
141 eventually being garbage-collected).
142 * failure to read from application data.
143
144 To work around that, please make sure that all directories in question
145 are owned by `nextcloud:nextcloud`.
146
147 - **`Failed to open stream: No such file or directory` after deploys**
148
149 Symptoms are errors like this after a deployment that disappear after
150 a few minutes:
151
152 ```
153 Warning: file_get_contents(/run/secrets/nextcloud_db_password): Failed to open stream: No such file or directory in /nix/store/lqw657xbh6h67ccv9cgv104qhcs1i2vw-nextcloud-config.php on line 11
154
155 Warning: http_response_code(): Cannot set response code - headers already sent (output started at /nix/store/lqw657xbh6h67ccv9cgv104qhcs1i2vw-nextcloud-config.php:11) in /nix/store/ikxpaq7kjdhpr4w7cgl1n28kc2gvlhg6-nextcloud-29.0.7/lib/base.php on line 639
156 Cannot decode /run/secrets/nextcloud_secrets, because: Syntax error
157 ```
158
159 This can happen if [](#opt-services.nextcloud.secretFile) or
160 [](#opt-services.nextcloud.config.dbpassFile) are managed by
161 [sops-nix](https://github.com/Mic92/sops-nix/).
162
163 Here, `/run/secrets/nextcloud_secrets` is a symlink to
164 `/run/secrets.d/N/nextcloud_secrets`. The `N` will be incremented
165 when the sops-nix activation script runs, i.e.
166 `/run/secrets.d/N` doesn't exist anymore after a deploy,
167 only `/run/secrets.d/N+1`.
168
169 PHP maintains a [cache for `realpath`](https://www.php.net/manual/en/ini.core.php#ini.realpath-cache-size)
170 that still resolves to the old path which is causing
171 the `No such file or directory` error. Interestingly,
172 the cache isn't used for `file_exists` which is why this warning
173 comes instead of the error from `nix_read_secret` in
174 `override.config.php`.
175
176 One option to work around this is to turn off the cache by setting
177 the cache size to zero:
178
179 ```nix
180 services.nextcloud.phpOptions."realpath_cache_size" = "0";
181 ```
182
183## Using an alternative webserver as reverse-proxy (e.g. `httpd`) {#module-services-nextcloud-httpd}
184
185By default, `nginx` is used as reverse-proxy for `nextcloud`.
186However, it's possible to use e.g. `httpd` by explicitly disabling
187`nginx` using [](#opt-services.nginx.enable) and fixing the
188settings `listen.owner` & `listen.group` in the
189[corresponding `phpfpm` pool](#opt-services.phpfpm.pools).
190
191An exemplary configuration may look like this:
192```nix
193{ config, lib, pkgs, ... }: {
194 services.nginx.enable = false;
195 services.nextcloud = {
196 enable = true;
197 hostName = "localhost";
198
199 /* further, required options */
200 };
201 services.phpfpm.pools.nextcloud.settings = {
202 "listen.owner" = config.services.httpd.user;
203 "listen.group" = config.services.httpd.group;
204 };
205 services.httpd = {
206 enable = true;
207 adminAddr = "webmaster@localhost";
208 extraModules = [ "proxy_fcgi" ];
209 virtualHosts."localhost" = {
210 documentRoot = config.services.nextcloud.package;
211 extraConfig = ''
212 <Directory "${config.services.nextcloud.package}">
213 <FilesMatch "\.php$">
214 <If "-f %{REQUEST_FILENAME}">
215 SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
216 </If>
217 </FilesMatch>
218 <IfModule mod_rewrite.c>
219 RewriteEngine On
220 RewriteBase /
221 RewriteRule ^index\.php$ - [L]
222 RewriteCond %{REQUEST_FILENAME} !-f
223 RewriteCond %{REQUEST_FILENAME} !-d
224 RewriteRule . /index.php [L]
225 </IfModule>
226 DirectoryIndex index.php
227 Require all granted
228 Options +FollowSymLinks
229 </Directory>
230 '';
231 };
232 };
233}
234```
235
236## Installing Apps and PHP extensions {#installing-apps-php-extensions-nextcloud}
237
238Nextcloud apps are installed statefully through the web interface.
239Some apps may require extra PHP extensions to be installed.
240This can be configured with the [](#opt-services.nextcloud.phpExtraExtensions) setting.
241
242Alternatively, extra apps can also be declared with the [](#opt-services.nextcloud.extraApps) setting.
243When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps
244that are managed by Nix:
245
246```nix
247{ config, pkgs, ... }: {
248 services.nextcloud.extraApps = with config.services.nextcloud.package.packages.apps; [
249 inherit user_oidc calendar contacts;
250 ];
251}
252```
253
254Keep in mind that this is essentially a mirror of the apps from the appstore, but managed in
255nixpkgs. This is by no means a curated list of apps that receive special testing on each update.
256
257If you want automatic updates it is recommended that you use web interface to install apps.
258
259## Known warnings {#module-services-nextcloud-known-warnings}
260
261### Logreader application only supports "file" log_type {#module-services-nextcloud-warning-logreader}
262
263This is because
264
265* our module writes logs into the journal (`journalctl -t Nextcloud`)
266* the Logreader application that allows reading logs in the admin panel is enabled
267 by default and requires logs written to a file.
268
269If you want to view logs in the admin panel,
270set [](#opt-services.nextcloud.settings.log_type) to "file".
271
272If you prefer logs in the journal, disable the logreader application to shut up the
273"info". We can't really do that by default since whether apps are enabled/disabled
274is part of the application's state and tracked inside the database.
275
276## Maintainer information {#module-services-nextcloud-maintainer-info}
277
278As stated in the previous paragraph, we must provide a clean upgrade-path for Nextcloud
279since it cannot move more than one major version forward on a single upgrade. This chapter
280adds some notes how Nextcloud updates should be rolled out in the future.
281
282While minor and patch-level updates are no problem and can be done directly in the
283package-expression (and should be backported to supported stable branches after that),
284major-releases should be added in a new attribute (e.g. Nextcloud `v19.0.0`
285should be available in `nixpkgs` as `pkgs.nextcloud19`).
286To provide simple upgrade paths it's generally useful to backport those as well to stable
287branches. As long as the package-default isn't altered, this won't break existing setups.
288After that, the versioning-warning in the `nextcloud`-module should be
289updated to make sure that the
290[package](#opt-services.nextcloud.package)-option selects the latest version
291on fresh setups.
292
293If major-releases will be abandoned by upstream, we should check first if those are needed
294in NixOS for a safe upgrade-path before removing those. In that case we should keep those
295packages, but mark them as insecure in an expression like this (in
296`<nixpkgs/pkgs/servers/nextcloud/default.nix>`):
297```nix
298/* ... */
299{
300 nextcloud17 = generic {
301 version = "17.0.x";
302 sha256 = "0000000000000000000000000000000000000000000000000000";
303 eol = true;
304 };
305}
306```
307
308Ideally we should make sure that it's possible to jump two NixOS versions forward:
309i.e. the warnings and the logic in the module should guard a user to upgrade from a
310Nextcloud on e.g. 19.09 to a Nextcloud on 20.09.