pyrox.dev
lol
nixos/nextcloud: convert manual chapter to MD
+500
-241
+237
nixos/modules/services/web-apps/nextcloud.md
+237
nixos/modules/services/web-apps/nextcloud.md
···
1
+
# Nextcloud {#module-services-nextcloud}
2
+
3
+
[Nextcloud](https://nextcloud.com/) is an open-source,
4
+
self-hostable cloud platform. The server setup can be automated using
5
+
[services.nextcloud](#opt-services.nextcloud.enable). A
6
+
desktop client is packaged at `pkgs.nextcloud-client`.
7
+
8
+
The current default by NixOS is `nextcloud25` which is also the latest
9
+
major version available.
10
+
11
+
## Basic usage {#module-services-nextcloud-basic-usage}
12
+
13
+
Nextcloud is a PHP-based application which requires an HTTP server
14
+
([`services.nextcloud`](#opt-services.nextcloud.enable)
15
+
optionally supports
16
+
[`services.nginx`](#opt-services.nginx.enable))
17
+
and a database (it's recommended to use
18
+
[`services.postgresql`](#opt-services.postgresql.enable)).
19
+
20
+
A very basic configuration may look like this:
21
+
```
22
+
{ pkgs, ... }:
23
+
{
24
+
services.nextcloud = {
25
+
enable = true;
26
+
hostName = "nextcloud.tld";
27
+
config = {
28
+
dbtype = "pgsql";
29
+
dbuser = "nextcloud";
30
+
dbhost = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself
31
+
dbname = "nextcloud";
32
+
adminpassFile = "/path/to/admin-pass-file";
33
+
adminuser = "root";
34
+
};
35
+
};
36
+
37
+
services.postgresql = {
38
+
enable = true;
39
+
ensureDatabases = [ "nextcloud" ];
40
+
ensureUsers = [
41
+
{ name = "nextcloud";
42
+
ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES";
43
+
}
44
+
];
45
+
};
46
+
47
+
# ensure that postgres is running *before* running the setup
48
+
systemd.services."nextcloud-setup" = {
49
+
requires = ["postgresql.service"];
50
+
after = ["postgresql.service"];
51
+
};
52
+
53
+
networking.firewall.allowedTCPPorts = [ 80 443 ];
54
+
}
55
+
```
56
+
57
+
The `hostName` option is used internally to configure an HTTP
58
+
server using [`PHP-FPM`](https://php-fpm.org/)
59
+
and `nginx`. The `config` attribute set is
60
+
used by the imperative installer and all values are written to an additional file
61
+
to ensure that changes can be applied by changing the module's options.
62
+
63
+
In case the application serves multiple domains (those are checked with
64
+
[`$_SERVER['HTTP_HOST']`](http://php.net/manual/en/reserved.variables.server.php))
65
+
it's needed to add them to
66
+
[`services.nextcloud.config.extraTrustedDomains`](#opt-services.nextcloud.config.extraTrustedDomains).
67
+
68
+
Auto updates for Nextcloud apps can be enabled using
69
+
[`services.nextcloud.autoUpdateApps`](#opt-services.nextcloud.autoUpdateApps.enable).
70
+
71
+
## Common problems {#module-services-nextcloud-pitfalls-during-upgrade}
72
+
73
+
- **General notes.**
74
+
Unfortunately Nextcloud appears to be very stateful when it comes to
75
+
managing its own configuration. The config file lives in the home directory
76
+
of the `nextcloud` user (by default
77
+
`/var/lib/nextcloud/config/config.php`) and is also used to
78
+
track several states of the application (e.g., whether installed or not).
79
+
80
+
All configuration parameters are also stored in
81
+
{file}`/var/lib/nextcloud/config/override.config.php` which is generated by
82
+
the module and linked from the store to ensure that all values from
83
+
{file}`config.php` can be modified by the module.
84
+
However {file}`config.php` manages the application's state and shouldn't be
85
+
touched manually because of that.
86
+
87
+
::: {.warning}
88
+
Don't delete {file}`config.php`! This file
89
+
tracks the application's state and a deletion can cause unwanted
90
+
side-effects!
91
+
:::
92
+
93
+
::: {.warning}
94
+
Don't rerun `nextcloud-occ maintenance:install`!
95
+
This command tries to install the application
96
+
and can cause unwanted side-effects!
97
+
:::
98
+
- **Multiple version upgrades.**
99
+
Nextcloud doesn't allow to move more than one major-version forward. E.g., if you're on
100
+
`v16`, you cannot upgrade to `v18`, you need to upgrade to
101
+
`v17` first. This is ensured automatically as long as the
102
+
[stateVersion](#opt-system.stateVersion) is declared properly. In that case
103
+
the oldest version available (one major behind the one from the previous NixOS
104
+
release) will be selected by default and the module will generate a warning that reminds
105
+
the user to upgrade to latest Nextcloud *after* that deploy.
106
+
- **`Error: Command "upgrade" is not defined.`**
107
+
This error usually occurs if the initial installation
108
+
({command}`nextcloud-occ maintenance:install`) has failed. After that, the application
109
+
is not installed, but the upgrade is attempted to be executed. Further context can
110
+
be found in [NixOS/nixpkgs#111175](https://github.com/NixOS/nixpkgs/issues/111175).
111
+
112
+
First of all, it makes sense to find out what went wrong by looking at the logs
113
+
of the installation via {command}`journalctl -u nextcloud-setup` and try to fix
114
+
the underlying issue.
115
+
116
+
- If this occurs on an *existing* setup, this is most likely because
117
+
the maintenance mode is active. It can be deactivated by running
118
+
{command}`nextcloud-occ maintenance:mode --off`. It's advisable though to
119
+
check the logs first on why the maintenance mode was activated.
120
+
- ::: {.warning}
121
+
Only perform the following measures on
122
+
*freshly installed instances!*
123
+
:::
124
+
125
+
A re-run of the installer can be forced by *deleting*
126
+
{file}`/var/lib/nextcloud/config/config.php`. This is the only time
127
+
advisable because the fresh install doesn't have any state that can be lost.
128
+
In case that doesn't help, an entire re-creation can be forced via
129
+
{command}`rm -rf ~nextcloud/`.
130
+
131
+
- **Server-side encryption.**
132
+
Nextcloud supports [server-side encryption (SSE)](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html).
133
+
This is not an end-to-end encryption, but can be used to encrypt files that will be persisted
134
+
to external storage such as S3. Please note that this won't work anymore when using OpenSSL 3
135
+
for PHP's openssl extension because this is implemented using the legacy cipher RC4.
136
+
If [](#opt-system.stateVersion) is *above* `22.05`,
137
+
this is disabled by default. To turn it on again and for further information please refer to
138
+
[](#opt-services.nextcloud.enableBrokenCiphersForSSE).
139
+
140
+
## Using an alternative webserver as reverse-proxy (e.g. `httpd`) {#module-services-nextcloud-httpd}
141
+
142
+
By default, `nginx` is used as reverse-proxy for `nextcloud`.
143
+
However, it's possible to use e.g. `httpd` by explicitly disabling
144
+
`nginx` using [](#opt-services.nginx.enable) and fixing the
145
+
settings `listen.owner` & `listen.group` in the
146
+
[corresponding `phpfpm` pool](#opt-services.phpfpm.pools).
147
+
148
+
An exemplary configuration may look like this:
149
+
```
150
+
{ config, lib, pkgs, ... }: {
151
+
services.nginx.enable = false;
152
+
services.nextcloud = {
153
+
enable = true;
154
+
hostName = "localhost";
155
+
156
+
/* further, required options */
157
+
};
158
+
services.phpfpm.pools.nextcloud.settings = {
159
+
"listen.owner" = config.services.httpd.user;
160
+
"listen.group" = config.services.httpd.group;
161
+
};
162
+
services.httpd = {
163
+
enable = true;
164
+
adminAddr = "webmaster@localhost";
165
+
extraModules = [ "proxy_fcgi" ];
166
+
virtualHosts."localhost" = {
167
+
documentRoot = config.services.nextcloud.package;
168
+
extraConfig = ''
169
+
<Directory "${config.services.nextcloud.package}">
170
+
<FilesMatch "\.php$">
171
+
<If "-f %{REQUEST_FILENAME}">
172
+
SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
173
+
</If>
174
+
</FilesMatch>
175
+
<IfModule mod_rewrite.c>
176
+
RewriteEngine On
177
+
RewriteBase /
178
+
RewriteRule ^index\.php$ - [L]
179
+
RewriteCond %{REQUEST_FILENAME} !-f
180
+
RewriteCond %{REQUEST_FILENAME} !-d
181
+
RewriteRule . /index.php [L]
182
+
</IfModule>
183
+
DirectoryIndex index.php
184
+
Require all granted
185
+
Options +FollowSymLinks
186
+
</Directory>
187
+
'';
188
+
};
189
+
};
190
+
}
191
+
```
192
+
193
+
## Installing Apps and PHP extensions {#installing-apps-php-extensions-nextcloud}
194
+
195
+
Nextcloud apps are installed statefully through the web interface.
196
+
Some apps may require extra PHP extensions to be installed.
197
+
This can be configured with the [](#opt-services.nextcloud.phpExtraExtensions) setting.
198
+
199
+
Alternatively, extra apps can also be declared with the [](#opt-services.nextcloud.extraApps) setting.
200
+
When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps
201
+
that are managed by Nix. If you want automatic updates it is recommended that you use web interface to install apps.
202
+
203
+
## Maintainer information {#module-services-nextcloud-maintainer-info}
204
+
205
+
As stated in the previous paragraph, we must provide a clean upgrade-path for Nextcloud
206
+
since it cannot move more than one major version forward on a single upgrade. This chapter
207
+
adds some notes how Nextcloud updates should be rolled out in the future.
208
+
209
+
While minor and patch-level updates are no problem and can be done directly in the
210
+
package-expression (and should be backported to supported stable branches after that),
211
+
major-releases should be added in a new attribute (e.g. Nextcloud `v19.0.0`
212
+
should be available in `nixpkgs` as `pkgs.nextcloud19`).
213
+
To provide simple upgrade paths it's generally useful to backport those as well to stable
214
+
branches. As long as the package-default isn't altered, this won't break existing setups.
215
+
After that, the versioning-warning in the `nextcloud`-module should be
216
+
updated to make sure that the
217
+
[package](#opt-services.nextcloud.package)-option selects the latest version
218
+
on fresh setups.
219
+
220
+
If major-releases will be abandoned by upstream, we should check first if those are needed
221
+
in NixOS for a safe upgrade-path before removing those. In that case we should keep those
222
+
packages, but mark them as insecure in an expression like this (in
223
+
`<nixpkgs/pkgs/servers/nextcloud/default.nix>`):
224
+
```
225
+
/* ... */
226
+
{
227
+
nextcloud17 = generic {
228
+
version = "17.0.x";
229
+
sha256 = "0000000000000000000000000000000000000000000000000000";
230
+
eol = true;
231
+
};
232
+
}
233
+
```
234
+
235
+
Ideally we should make sure that it's possible to jump two NixOS versions forward:
236
+
i.e. the warnings and the logic in the module should guard a user to upgrade from a
237
+
Nextcloud on e.g. 19.09 to a Nextcloud on 20.09.
+2
nixos/modules/services/web-apps/nextcloud.nix
+2
nixos/modules/services/web-apps/nextcloud.nix
···
1146
1146
}
1147
1147
]);
1148
1148
1149
+
# Don't edit the docbook xml directly, edit the md and generate it:
1150
+
# `pandoc nextcloud.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > nextcloud.xml`
1149
1151
meta.doc = ./nextcloud.xml;
1150
1152
}
+261
-241
nixos/modules/services/web-apps/nextcloud.xml
+261
-241
nixos/modules/services/web-apps/nextcloud.xml
···
1
-
<chapter xmlns="http://docbook.org/ns/docbook"
2
-
xmlns:xlink="http://www.w3.org/1999/xlink"
3
-
xmlns:xi="http://www.w3.org/2001/XInclude"
4
-
version="5.0"
5
-
xml:id="module-services-nextcloud">
6
-
<title>Nextcloud</title>
7
-
<para>
8
-
<link xlink:href="https://nextcloud.com/">Nextcloud</link> is an open-source,
9
-
self-hostable cloud platform. The server setup can be automated using
10
-
<link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. A
11
-
desktop client is packaged at <literal>pkgs.nextcloud-client</literal>.
12
-
</para>
13
-
<para>
14
-
The current default by NixOS is <literal>nextcloud25</literal> which is also the latest
15
-
major version available.
16
-
</para>
17
-
<section xml:id="module-services-nextcloud-basic-usage">
18
-
<title>Basic usage</title>
19
-
1
+
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-nextcloud">
2
+
<title>Nextcloud</title>
20
3
<para>
21
-
Nextcloud is a PHP-based application which requires an HTTP server
22
-
(<link linkend="opt-services.nextcloud.enable"><literal>services.nextcloud</literal></link>
23
-
optionally supports
24
-
<link linkend="opt-services.nginx.enable"><literal>services.nginx</literal></link>)
25
-
and a database (it's recommended to use
26
-
<link linkend="opt-services.postgresql.enable"><literal>services.postgresql</literal></link>).
4
+
<link xlink:href="https://nextcloud.com/">Nextcloud</link> is an
5
+
open-source, self-hostable cloud platform. The server setup can be
6
+
automated using
7
+
<link linkend="opt-services.nextcloud.enable">services.nextcloud</link>.
8
+
A desktop client is packaged at
9
+
<literal>pkgs.nextcloud-client</literal>.
27
10
</para>
28
-
29
11
<para>
30
-
A very basic configuration may look like this:
31
-
<programlisting>
12
+
The current default by NixOS is <literal>nextcloud25</literal> which
13
+
is also the latest major version available.
14
+
</para>
15
+
<section xml:id="module-services-nextcloud-basic-usage">
16
+
<title>Basic usage</title>
17
+
<para>
18
+
Nextcloud is a PHP-based application which requires an HTTP server
19
+
(<link linkend="opt-services.nextcloud.enable"><literal>services.nextcloud</literal></link>
20
+
optionally supports
21
+
<link linkend="opt-services.nginx.enable"><literal>services.nginx</literal></link>)
22
+
and a database (it's recommended to use
23
+
<link linkend="opt-services.postgresql.enable"><literal>services.postgresql</literal></link>).
24
+
</para>
25
+
<para>
26
+
A very basic configuration may look like this:
27
+
</para>
28
+
<programlisting>
32
29
{ pkgs, ... }:
33
30
{
34
31
services.nextcloud = {
35
32
enable = true;
36
-
hostName = "nextcloud.tld";
33
+
hostName = "nextcloud.tld";
37
34
config = {
38
-
dbtype = "pgsql";
39
-
dbuser = "nextcloud";
40
-
dbhost = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself
41
-
dbname = "nextcloud";
42
-
adminpassFile = "/path/to/admin-pass-file";
43
-
adminuser = "root";
35
+
dbtype = "pgsql";
36
+
dbuser = "nextcloud";
37
+
dbhost = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself
38
+
dbname = "nextcloud";
39
+
adminpassFile = "/path/to/admin-pass-file";
40
+
adminuser = "root";
44
41
};
45
42
};
46
43
47
44
services.postgresql = {
48
45
enable = true;
49
-
ensureDatabases = [ "nextcloud" ];
46
+
ensureDatabases = [ "nextcloud" ];
50
47
ensureUsers = [
51
-
{ name = "nextcloud";
52
-
ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES";
48
+
{ name = "nextcloud";
49
+
ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES";
53
50
}
54
51
];
55
52
};
56
53
57
54
# ensure that postgres is running *before* running the setup
58
-
systemd.services."nextcloud-setup" = {
59
-
requires = ["postgresql.service"];
60
-
after = ["postgresql.service"];
55
+
systemd.services."nextcloud-setup" = {
56
+
requires = ["postgresql.service"];
57
+
after = ["postgresql.service"];
61
58
};
62
59
63
60
networking.firewall.allowedTCPPorts = [ 80 443 ];
64
61
}
65
62
</programlisting>
66
-
</para>
67
-
68
-
<para>
69
-
The <literal>hostName</literal> option is used internally to configure an HTTP
70
-
server using <link xlink:href="https://php-fpm.org/"><literal>PHP-FPM</literal></link>
71
-
and <literal>nginx</literal>. The <literal>config</literal> attribute set is
72
-
used by the imperative installer and all values are written to an additional file
73
-
to ensure that changes can be applied by changing the module's options.
74
-
</para>
75
-
76
-
<para>
77
-
In case the application serves multiple domains (those are checked with
78
-
<link xlink:href="http://php.net/manual/en/reserved.variables.server.php"><literal>$_SERVER['HTTP_HOST']</literal></link>)
79
-
it's needed to add them to
80
-
<link linkend="opt-services.nextcloud.config.extraTrustedDomains"><literal>services.nextcloud.config.extraTrustedDomains</literal></link>.
81
-
</para>
82
-
83
-
<para>
84
-
Auto updates for Nextcloud apps can be enabled using
85
-
<link linkend="opt-services.nextcloud.autoUpdateApps.enable"><literal>services.nextcloud.autoUpdateApps</literal></link>.
86
-
</para>
87
-
88
-
</section>
89
-
90
-
<section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
91
-
<title>Common problems</title>
92
-
<itemizedlist>
93
-
<listitem>
94
-
<formalpara>
95
-
<title>General notes</title>
96
-
<para>
97
-
Unfortunately Nextcloud appears to be very stateful when it comes to
98
-
managing its own configuration. The config file lives in the home directory
99
-
of the <literal>nextcloud</literal> user (by default
100
-
<literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to
101
-
track several states of the application (e.g., whether installed or not).
102
-
</para>
103
-
</formalpara>
63
+
<para>
64
+
The <literal>hostName</literal> option is used internally to
65
+
configure an HTTP server using
66
+
<link xlink:href="https://php-fpm.org/"><literal>PHP-FPM</literal></link>
67
+
and <literal>nginx</literal>. The <literal>config</literal>
68
+
attribute set is used by the imperative installer and all values
69
+
are written to an additional file to ensure that changes can be
70
+
applied by changing the module's options.
71
+
</para>
104
72
<para>
105
-
All configuration parameters are also stored in
106
-
<filename>/var/lib/nextcloud/config/override.config.php</filename> which is generated by
107
-
the module and linked from the store to ensure that all values from
108
-
<filename>config.php</filename> can be modified by the module.
109
-
However <filename>config.php</filename> manages the application's state and shouldn't be
110
-
touched manually because of that.
73
+
In case the application serves multiple domains (those are checked
74
+
with
75
+
<link xlink:href="http://php.net/manual/en/reserved.variables.server.php"><literal>$_SERVER['HTTP_HOST']</literal></link>)
76
+
it's needed to add them to
77
+
<link linkend="opt-services.nextcloud.config.extraTrustedDomains"><literal>services.nextcloud.config.extraTrustedDomains</literal></link>.
111
78
</para>
112
-
<warning>
113
-
<para>Don't delete <filename>config.php</filename>! This file
114
-
tracks the application's state and a deletion can cause unwanted
115
-
side-effects!</para>
116
-
</warning>
117
-
118
-
<warning>
119
-
<para>Don't rerun <literal>nextcloud-occ
120
-
maintenance:install</literal>! This command tries to install the application
121
-
and can cause unwanted side-effects!</para>
122
-
</warning>
123
-
</listitem>
124
-
<listitem>
125
-
<formalpara>
126
-
<title>Multiple version upgrades</title>
127
-
<para>
128
-
Nextcloud doesn't allow to move more than one major-version forward. E.g., if you're on
129
-
<literal>v16</literal>, you cannot upgrade to <literal>v18</literal>, you need to upgrade to
130
-
<literal>v17</literal> first. This is ensured automatically as long as the
131
-
<link linkend="opt-system.stateVersion">stateVersion</link> is declared properly. In that case
132
-
the oldest version available (one major behind the one from the previous NixOS
133
-
release) will be selected by default and the module will generate a warning that reminds
134
-
the user to upgrade to latest Nextcloud <emphasis>after</emphasis> that deploy.
135
-
</para>
136
-
</formalpara>
137
-
</listitem>
138
-
<listitem>
139
-
<formalpara>
140
-
<title><literal>Error: Command "upgrade" is not defined.</literal></title>
141
-
<para>
142
-
This error usually occurs if the initial installation
143
-
(<command>nextcloud-occ maintenance:install</command>) has failed. After that, the application
144
-
is not installed, but the upgrade is attempted to be executed. Further context can
145
-
be found in <link xlink:href="https://github.com/NixOS/nixpkgs/issues/111175">NixOS/nixpkgs#111175</link>.
146
-
</para>
147
-
</formalpara>
148
79
<para>
149
-
First of all, it makes sense to find out what went wrong by looking at the logs
150
-
of the installation via <command>journalctl -u nextcloud-setup</command> and try to fix
151
-
the underlying issue.
80
+
Auto updates for Nextcloud apps can be enabled using
81
+
<link linkend="opt-services.nextcloud.autoUpdateApps.enable"><literal>services.nextcloud.autoUpdateApps</literal></link>.
152
82
</para>
83
+
</section>
84
+
<section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
85
+
<title>Common problems</title>
153
86
<itemizedlist>
154
-
<listitem>
155
-
<para>
156
-
If this occurs on an <emphasis>existing</emphasis> setup, this is most likely because
157
-
the maintenance mode is active. It can be deactivated by running
158
-
<command>nextcloud-occ maintenance:mode --off</command>. It's advisable though to
159
-
check the logs first on why the maintenance mode was activated.
160
-
</para>
161
-
</listitem>
162
-
<listitem>
163
-
<warning><para>Only perform the following measures on
164
-
<emphasis>freshly installed instances!</emphasis></para></warning>
165
-
<para>
166
-
A re-run of the installer can be forced by <emphasis>deleting</emphasis>
167
-
<filename>/var/lib/nextcloud/config/config.php</filename>. This is the only time
168
-
advisable because the fresh install doesn't have any state that can be lost.
169
-
In case that doesn't help, an entire re-creation can be forced via
170
-
<command>rm -rf ~nextcloud/</command>.
171
-
</para>
172
-
</listitem>
87
+
<listitem>
88
+
<para>
89
+
<emphasis role="strong">General notes.</emphasis>
90
+
Unfortunately Nextcloud appears to be very stateful when it
91
+
comes to managing its own configuration. The config file lives
92
+
in the home directory of the <literal>nextcloud</literal> user
93
+
(by default
94
+
<literal>/var/lib/nextcloud/config/config.php</literal>) and
95
+
is also used to track several states of the application (e.g.,
96
+
whether installed or not).
97
+
</para>
98
+
<para>
99
+
All configuration parameters are also stored in
100
+
<filename>/var/lib/nextcloud/config/override.config.php</filename>
101
+
which is generated by the module and linked from the store to
102
+
ensure that all values from <filename>config.php</filename>
103
+
can be modified by the module. However
104
+
<filename>config.php</filename> manages the application's
105
+
state and shouldn't be touched manually because of that.
106
+
</para>
107
+
<warning>
108
+
<para>
109
+
Don't delete <filename>config.php</filename>! This file
110
+
tracks the application's state and a deletion can cause
111
+
unwanted side-effects!
112
+
</para>
113
+
</warning>
114
+
<warning>
115
+
<para>
116
+
Don't rerun
117
+
<literal>nextcloud-occ maintenance:install</literal>! This
118
+
command tries to install the application and can cause
119
+
unwanted side-effects!
120
+
</para>
121
+
</warning>
122
+
</listitem>
123
+
<listitem>
124
+
<para>
125
+
<emphasis role="strong">Multiple version upgrades.</emphasis>
126
+
Nextcloud doesn't allow to move more than one major-version
127
+
forward. E.g., if you're on <literal>v16</literal>, you cannot
128
+
upgrade to <literal>v18</literal>, you need to upgrade to
129
+
<literal>v17</literal> first. This is ensured automatically as
130
+
long as the
131
+
<link linkend="opt-system.stateVersion">stateVersion</link> is
132
+
declared properly. In that case the oldest version available
133
+
(one major behind the one from the previous NixOS release)
134
+
will be selected by default and the module will generate a
135
+
warning that reminds the user to upgrade to latest Nextcloud
136
+
<emphasis>after</emphasis> that deploy.
137
+
</para>
138
+
</listitem>
139
+
<listitem>
140
+
<para>
141
+
<emphasis role="strong"><literal>Error: Command "upgrade" is not defined.</literal></emphasis>
142
+
This error usually occurs if the initial installation
143
+
(<command>nextcloud-occ maintenance:install</command>) has
144
+
failed. After that, the application is not installed, but the
145
+
upgrade is attempted to be executed. Further context can be
146
+
found in
147
+
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/111175">NixOS/nixpkgs#111175</link>.
148
+
</para>
149
+
<para>
150
+
First of all, it makes sense to find out what went wrong by
151
+
looking at the logs of the installation via
152
+
<command>journalctl -u nextcloud-setup</command> and try to
153
+
fix the underlying issue.
154
+
</para>
155
+
<itemizedlist>
156
+
<listitem>
157
+
<para>
158
+
If this occurs on an <emphasis>existing</emphasis> setup,
159
+
this is most likely because the maintenance mode is
160
+
active. It can be deactivated by running
161
+
<command>nextcloud-occ maintenance:mode --off</command>.
162
+
It's advisable though to check the logs first on why the
163
+
maintenance mode was activated.
164
+
</para>
165
+
</listitem>
166
+
<listitem>
167
+
<warning>
168
+
<para>
169
+
Only perform the following measures on <emphasis>freshly
170
+
installed instances!</emphasis>
171
+
</para>
172
+
</warning>
173
+
<para>
174
+
A re-run of the installer can be forced by
175
+
<emphasis>deleting</emphasis>
176
+
<filename>/var/lib/nextcloud/config/config.php</filename>.
177
+
This is the only time advisable because the fresh install
178
+
doesn't have any state that can be lost. In case that
179
+
doesn't help, an entire re-creation can be forced via
180
+
<command>rm -rf ~nextcloud/</command>.
181
+
</para>
182
+
</listitem>
183
+
</itemizedlist>
184
+
</listitem>
185
+
<listitem>
186
+
<para>
187
+
<emphasis role="strong">Server-side encryption.</emphasis>
188
+
Nextcloud supports
189
+
<link xlink:href="https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html">server-side
190
+
encryption (SSE)</link>. This is not an end-to-end encryption,
191
+
but can be used to encrypt files that will be persisted to
192
+
external storage such as S3. Please note that this won't work
193
+
anymore when using OpenSSL 3 for PHP's openssl extension
194
+
because this is implemented using the legacy cipher RC4. If
195
+
<xref linkend="opt-system.stateVersion"></xref> is
196
+
<emphasis>above</emphasis> <literal>22.05</literal>, this is
197
+
disabled by default. To turn it on again and for further
198
+
information please refer to
199
+
<xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE"></xref>.
200
+
</para>
201
+
</listitem>
173
202
</itemizedlist>
174
-
</listitem>
175
-
<listitem>
176
-
<formalpara>
177
-
<title>Server-side encryption</title>
178
-
<para>
179
-
Nextcloud supports <link xlink:href="https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html">server-side encryption (SSE)</link>.
180
-
This is not an end-to-end encryption, but can be used to encrypt files that will be persisted
181
-
to external storage such as S3. Please note that this won't work anymore when using OpenSSL 3
182
-
for PHP's openssl extension because this is implemented using the legacy cipher RC4.
183
-
If <xref linkend="opt-system.stateVersion" /> is <emphasis>above</emphasis> <literal>22.05</literal>,
184
-
this is disabled by default. To turn it on again and for further information please refer to
185
-
<xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE" />.
186
-
</para>
187
-
</formalpara>
188
-
</listitem>
189
-
</itemizedlist>
190
-
</section>
191
-
192
-
<section xml:id="module-services-nextcloud-httpd">
193
-
<title>Using an alternative webserver as reverse-proxy (e.g. <literal>httpd</literal>)</title>
194
-
<para>
195
-
By default, <literal>nginx</literal> is used as reverse-proxy for <literal>nextcloud</literal>.
196
-
However, it's possible to use e.g. <literal>httpd</literal> by explicitly disabling
197
-
<literal>nginx</literal> using <xref linkend="opt-services.nginx.enable" /> and fixing the
198
-
settings <literal>listen.owner</literal> & <literal>listen.group</literal> in the
199
-
<link linkend="opt-services.phpfpm.pools">corresponding <literal>phpfpm</literal> pool</link>.
200
-
</para>
201
-
<para>
202
-
An exemplary configuration may look like this:
203
-
<programlisting>
203
+
</section>
204
+
<section xml:id="module-services-nextcloud-httpd">
205
+
<title>Using an alternative webserver as reverse-proxy (e.g.
206
+
<literal>httpd</literal>)</title>
207
+
<para>
208
+
By default, <literal>nginx</literal> is used as reverse-proxy for
209
+
<literal>nextcloud</literal>. However, it's possible to use e.g.
210
+
<literal>httpd</literal> by explicitly disabling
211
+
<literal>nginx</literal> using
212
+
<xref linkend="opt-services.nginx.enable"></xref> and fixing the
213
+
settings <literal>listen.owner</literal> &
214
+
<literal>listen.group</literal> in the
215
+
<link linkend="opt-services.phpfpm.pools">corresponding
216
+
<literal>phpfpm</literal> pool</link>.
217
+
</para>
218
+
<para>
219
+
An exemplary configuration may look like this:
220
+
</para>
221
+
<programlisting>
204
222
{ config, lib, pkgs, ... }: {
205
223
services.nginx.enable = false;
206
224
services.nextcloud = {
207
225
enable = true;
208
-
hostName = "localhost";
226
+
hostName = "localhost";
209
227
210
228
/* further, required options */
211
229
};
212
230
services.phpfpm.pools.nextcloud.settings = {
213
-
"listen.owner" = config.services.httpd.user;
214
-
"listen.group" = config.services.httpd.group;
231
+
"listen.owner" = config.services.httpd.user;
232
+
"listen.group" = config.services.httpd.group;
215
233
};
216
234
services.httpd = {
217
235
enable = true;
218
-
adminAddr = "webmaster@localhost";
219
-
extraModules = [ "proxy_fcgi" ];
220
-
virtualHosts."localhost" = {
236
+
adminAddr = "webmaster@localhost";
237
+
extraModules = [ "proxy_fcgi" ];
238
+
virtualHosts."localhost" = {
221
239
documentRoot = config.services.nextcloud.package;
222
240
extraConfig = ''
223
-
<Directory "${config.services.nextcloud.package}">
224
-
<FilesMatch "\.php$">
225
-
<If "-f %{REQUEST_FILENAME}">
226
-
SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
241
+
<Directory "${config.services.nextcloud.package}">
242
+
<FilesMatch "\.php$">
243
+
<If "-f %{REQUEST_FILENAME}">
244
+
SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
227
245
</If>
228
246
</FilesMatch>
229
247
<IfModule mod_rewrite.c>
···
243
261
};
244
262
}
245
263
</programlisting>
246
-
</para>
247
-
</section>
248
-
249
-
<section xml:id="installing-apps-php-extensions-nextcloud">
250
-
<title>Installing Apps and PHP extensions</title>
251
-
252
-
<para>
253
-
Nextcloud apps are installed statefully through the web interface.
254
-
255
-
Some apps may require extra PHP extensions to be installed.
256
-
This can be configured with the <xref linkend="opt-services.nextcloud.phpExtraExtensions" /> setting.
257
-
</para>
258
-
259
-
<para>
260
-
Alternatively, extra apps can also be declared with the <xref linkend="opt-services.nextcloud.extraApps" /> setting.
261
-
When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps
262
-
that are managed by Nix. If you want automatic updates it is recommended that you use web interface to install apps.
263
-
</para>
264
-
</section>
265
-
266
-
<section xml:id="module-services-nextcloud-maintainer-info">
267
-
<title>Maintainer information</title>
268
-
269
-
<para>
270
-
As stated in the previous paragraph, we must provide a clean upgrade-path for Nextcloud
271
-
since it cannot move more than one major version forward on a single upgrade. This chapter
272
-
adds some notes how Nextcloud updates should be rolled out in the future.
273
-
</para>
274
-
275
-
<para>
276
-
While minor and patch-level updates are no problem and can be done directly in the
277
-
package-expression (and should be backported to supported stable branches after that),
278
-
major-releases should be added in a new attribute (e.g. Nextcloud <literal>v19.0.0</literal>
279
-
should be available in <literal>nixpkgs</literal> as <literal>pkgs.nextcloud19</literal>).
280
-
To provide simple upgrade paths it's generally useful to backport those as well to stable
281
-
branches. As long as the package-default isn't altered, this won't break existing setups.
282
-
After that, the versioning-warning in the <literal>nextcloud</literal>-module should be
283
-
updated to make sure that the
284
-
<link linkend="opt-services.nextcloud.package">package</link>-option selects the latest version
285
-
on fresh setups.
286
-
</para>
287
-
288
-
<para>
289
-
If major-releases will be abandoned by upstream, we should check first if those are needed
290
-
in NixOS for a safe upgrade-path before removing those. In that case we should keep those
291
-
packages, but mark them as insecure in an expression like this (in
292
-
<literal><nixpkgs/pkgs/servers/nextcloud/default.nix></literal>):
293
-
<programlisting>
264
+
</section>
265
+
<section xml:id="installing-apps-php-extensions-nextcloud">
266
+
<title>Installing Apps and PHP extensions</title>
267
+
<para>
268
+
Nextcloud apps are installed statefully through the web interface.
269
+
Some apps may require extra PHP extensions to be installed. This
270
+
can be configured with the
271
+
<xref linkend="opt-services.nextcloud.phpExtraExtensions"></xref>
272
+
setting.
273
+
</para>
274
+
<para>
275
+
Alternatively, extra apps can also be declared with the
276
+
<xref linkend="opt-services.nextcloud.extraApps"></xref> setting.
277
+
When using this setting, apps can no longer be managed statefully
278
+
because this can lead to Nextcloud updating apps that are managed
279
+
by Nix. If you want automatic updates it is recommended that you
280
+
use web interface to install apps.
281
+
</para>
282
+
</section>
283
+
<section xml:id="module-services-nextcloud-maintainer-info">
284
+
<title>Maintainer information</title>
285
+
<para>
286
+
As stated in the previous paragraph, we must provide a clean
287
+
upgrade-path for Nextcloud since it cannot move more than one
288
+
major version forward on a single upgrade. This chapter adds some
289
+
notes how Nextcloud updates should be rolled out in the future.
290
+
</para>
291
+
<para>
292
+
While minor and patch-level updates are no problem and can be done
293
+
directly in the package-expression (and should be backported to
294
+
supported stable branches after that), major-releases should be
295
+
added in a new attribute (e.g. Nextcloud
296
+
<literal>v19.0.0</literal> should be available in
297
+
<literal>nixpkgs</literal> as
298
+
<literal>pkgs.nextcloud19</literal>). To provide simple upgrade
299
+
paths it's generally useful to backport those as well to stable
300
+
branches. As long as the package-default isn't altered, this won't
301
+
break existing setups. After that, the versioning-warning in the
302
+
<literal>nextcloud</literal>-module should be updated to make sure
303
+
that the
304
+
<link linkend="opt-services.nextcloud.package">package</link>-option
305
+
selects the latest version on fresh setups.
306
+
</para>
307
+
<para>
308
+
If major-releases will be abandoned by upstream, we should check
309
+
first if those are needed in NixOS for a safe upgrade-path before
310
+
removing those. In that case we should keep those packages, but
311
+
mark them as insecure in an expression like this (in
312
+
<literal><nixpkgs/pkgs/servers/nextcloud/default.nix></literal>):
313
+
</para>
314
+
<programlisting>
294
315
/* ... */
295
316
{
296
317
nextcloud17 = generic {
297
-
version = "17.0.x";
298
-
sha256 = "0000000000000000000000000000000000000000000000000000";
318
+
version = "17.0.x";
319
+
sha256 = "0000000000000000000000000000000000000000000000000000";
299
320
eol = true;
300
321
};
301
322
}
302
323
</programlisting>
303
-
</para>
304
-
305
-
<para>
306
-
Ideally we should make sure that it's possible to jump two NixOS versions forward:
307
-
i.e. the warnings and the logic in the module should guard a user to upgrade from a
308
-
Nextcloud on e.g. 19.09 to a Nextcloud on 20.09.
309
-
</para>
310
-
</section>
324
+
<para>
325
+
Ideally we should make sure that it's possible to jump two NixOS
326
+
versions forward: i.e. the warnings and the logic in the module
327
+
should guard a user to upgrade from a Nextcloud on e.g. 19.09 to a
328
+
Nextcloud on 20.09.
329
+
</para>
330
+
</section>
311
331
</chapter>