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>nextcloud21</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 <section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
88 <title>Pitfalls</title>
89
90 <para>
91 Unfortunately Nextcloud appears to be very stateful when it comes to
92 managing its own configuration. The config file lives in the home directory
93 of the <literal>nextcloud</literal> user (by default
94 <literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to
95 track several states of the application (e.g. whether installed or not).
96 </para>
97
98 <para>
99 All configuration parameters are also stored in
100 <literal>/var/lib/nextcloud/config/override.config.php</literal> which is generated by
101 the module and linked from the store to ensure that all values from <literal>config.php</literal>
102 can be modified by the module.
103 However <literal>config.php</literal> manages the application's state and shouldn't be touched
104 manually because of that.
105 </para>
106
107 <warning>
108 <para>Don't delete <literal>config.php</literal>! This file
109 tracks the application's state and a deletion can cause unwanted
110 side-effects!</para>
111 </warning>
112
113 <warning>
114 <para>Don't rerun <literal>nextcloud-occ
115 maintenance:install</literal>! This command tries to install the application
116 and can cause unwanted side-effects!</para>
117 </warning>
118
119 <para>
120 Nextcloud doesn't allow to move more than one major-version forward. If you're e.g. on
121 <literal>v16</literal>, you cannot upgrade to <literal>v18</literal>, you need to upgrade to
122 <literal>v17</literal> first. This is ensured automatically as long as the
123 <link linkend="opt-system.stateVersion">stateVersion</link> is declared properly. In that case
124 the oldest version available (one major behind the one from the previous NixOS
125 release) will be selected by default and the module will generate a warning that reminds
126 the user to upgrade to latest Nextcloud <emphasis>after</emphasis> that deploy.
127 </para>
128 </section>
129
130 <section xml:id="module-services-nextcloud-httpd">
131 <title>Using an alternative webserver as reverse-proxy (e.g. <literal>httpd</literal>)</title>
132 <para>
133 By default, <package>nginx</package> is used as reverse-proxy for <package>nextcloud</package>.
134 However, it's possible to use e.g. <package>httpd</package> by explicitly disabling
135 <package>nginx</package> using <xref linkend="opt-services.nginx.enable" /> and fixing the
136 settings <literal>listen.owner</literal> & <literal>listen.group</literal> in the
137 <link linkend="opt-services.phpfpm.pools">corresponding <literal>phpfpm</literal> pool</link>.
138 </para>
139 <para>
140 An exemplary configuration may look like this:
141<programlisting>{ config, lib, pkgs, ... }: {
142 <link linkend="opt-services.nginx.enable">services.nginx.enable</link> = false;
143 services.nextcloud = {
144 <link linkend="opt-services.nextcloud.enable">enable</link> = true;
145 <link linkend="opt-services.nextcloud.hostName">hostName</link> = "localhost";
146
147 /* further, required options */
148 };
149 <link linkend="opt-services.phpfpm.pools._name_.settings">services.phpfpm.pools.nextcloud.settings</link> = {
150 "listen.owner" = config.services.httpd.user;
151 "listen.group" = config.services.httpd.group;
152 };
153 services.httpd = {
154 <link linkend="opt-services.httpd.enable">enable</link> = true;
155 <link linkend="opt-services.httpd.adminAddr">adminAddr</link> = "webmaster@localhost";
156 <link linkend="opt-services.httpd.extraModules">extraModules</link> = [ "proxy_fcgi" ];
157 virtualHosts."localhost" = {
158 <link linkend="opt-services.httpd.virtualHosts._name_.documentRoot">documentRoot</link> = config.services.nextcloud.package;
159 <link linkend="opt-services.httpd.virtualHosts._name_.extraConfig">extraConfig</link> = ''
160 <Directory "${config.services.nextcloud.package}">
161 <FilesMatch "\.php$">
162 <If "-f %{REQUEST_FILENAME}">
163 SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
164 </If>
165 </FilesMatch>
166 <IfModule mod_rewrite.c>
167 RewriteEngine On
168 RewriteBase /
169 RewriteRule ^index\.php$ - [L]
170 RewriteCond %{REQUEST_FILENAME} !-f
171 RewriteCond %{REQUEST_FILENAME} !-d
172 RewriteRule . /index.php [L]
173 </IfModule>
174 DirectoryIndex index.php
175 Require all granted
176 Options +FollowSymLinks
177 </Directory>
178 '';
179 };
180 };
181}</programlisting>
182 </para>
183 </section>
184
185 <section xml:id="installing-apps-php-extensions-nextcloud">
186 <title>Installing Apps and PHP extensions</title>
187
188 <para>
189 Nextcloud apps are installed statefully through the web interface.
190
191 Some apps may require extra PHP extensions to be installed.
192 This can be configured with the <xref linkend="opt-services.nextcloud.phpExtraExtensions" /> setting.
193 </para>
194 </section>
195
196 <section xml:id="module-services-nextcloud-maintainer-info">
197 <title>Maintainer information</title>
198
199 <para>
200 As stated in the previous paragraph, we must provide a clean upgrade-path for Nextcloud
201 since it cannot move more than one major version forward on a single upgrade. This chapter
202 adds some notes how Nextcloud updates should be rolled out in the future.
203 </para>
204
205 <para>
206 While minor and patch-level updates are no problem and can be done directly in the
207 package-expression (and should be backported to supported stable branches after that),
208 major-releases should be added in a new attribute (e.g. Nextcloud <literal>v19.0.0</literal>
209 should be available in <literal>nixpkgs</literal> as <literal>pkgs.nextcloud19</literal>).
210 To provide simple upgrade paths it's generally useful to backport those as well to stable
211 branches. As long as the package-default isn't altered, this won't break existing setups.
212 After that, the versioning-warning in the <literal>nextcloud</literal>-module should be
213 updated to make sure that the
214 <link linkend="opt-services.nextcloud.package">package</link>-option selects the latest version
215 on fresh setups.
216 </para>
217
218 <para>
219 If major-releases will be abandoned by upstream, we should check first if those are needed
220 in NixOS for a safe upgrade-path before removing those. In that case we shold keep those
221 packages, but mark them as insecure in an expression like this (in
222 <literal><nixpkgs/pkgs/servers/nextcloud/default.nix></literal>):
223<programlisting>/* ... */
224{
225 nextcloud17 = generic {
226 version = "17.0.x";
227 sha256 = "0000000000000000000000000000000000000000000000000000";
228 eol = true;
229 };
230}</programlisting>
231 </para>
232
233 <para>
234 Ideally we should make sure that it's possible to jump two NixOS versions forward:
235 i.e. the warnings and the logic in the module should guard a user to upgrade from a
236 Nextcloud on e.g. 19.09 to a Nextcloud on 20.09.
237 </para>
238 </section>
239</chapter>