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