nixos/nextcloud: convert manual chapter to MD

1 files changed, 261 insertions, 241 deletions

diff --git a/nixos/modules/services/web-apps/nextcloud.xml b/nixos/modules/services/web-apps/nextcloud.xml
index 434df8f0d34..7d4b074514c 100644
--- a/nixos/modules/services/web-apps/nextcloud.xml
+++ b/nixos/modules/services/web-apps/nextcloud.xml
@@ -1,229 +1,247 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="module-services-nextcloud">
- <title>Nextcloud</title>
- <para>
-  <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an open-source,
-  self-hostable cloud platform. The server setup can be automated using
-  <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. A
-  desktop client is packaged at <literal>pkgs.nextcloud-client</literal>.
- </para>
- <para>
-  The current default by NixOS is <literal>nextcloud25</literal> which is also the latest
-  major version available.
- </para>
- <section xml:id="module-services-nextcloud-basic-usage">
-  <title>Basic usage</title>
-
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-nextcloud">
+  <title>Nextcloud</title>
   <para>
-   Nextcloud is a PHP-based application which requires an HTTP server
-   (<link linkend="opt-services.nextcloud.enable"><literal>services.nextcloud</literal></link>
-   optionally supports
-   <link linkend="opt-services.nginx.enable"><literal>services.nginx</literal></link>)
-   and a database (it's recommended to use
-   <link linkend="opt-services.postgresql.enable"><literal>services.postgresql</literal></link>).
+    <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an
+    open-source, self-hostable cloud platform. The server setup can be
+    automated using
+    <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>.
+    A desktop client is packaged at
+    <literal>pkgs.nextcloud-client</literal>.
   </para>
-
   <para>
-   A very basic configuration may look like this:
-<programlisting>
+    The current default by NixOS is <literal>nextcloud25</literal> which
+    is also the latest major version available.
+  </para>
+  <section xml:id="module-services-nextcloud-basic-usage">
+    <title>Basic usage</title>
+    <para>
+      Nextcloud is a PHP-based application which requires an HTTP server
+      (<link linkend="opt-services.nextcloud.enable"><literal>services.nextcloud</literal></link>
+      optionally supports
+      <link linkend="opt-services.nginx.enable"><literal>services.nginx</literal></link>)
+      and a database (it's recommended to use
+      <link linkend="opt-services.postgresql.enable"><literal>services.postgresql</literal></link>).
+    </para>
+    <para>
+      A very basic configuration may look like this:
+    </para>
+    <programlisting>
 { pkgs, ... }:
 {
   services.nextcloud = {
     enable = true;
-    hostName = "nextcloud.tld";
+    hostName = &quot;nextcloud.tld&quot;;
     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";
+      dbtype = &quot;pgsql&quot;;
+      dbuser = &quot;nextcloud&quot;;
+      dbhost = &quot;/run/postgresql&quot;; # nextcloud will add /.s.PGSQL.5432 by itself
+      dbname = &quot;nextcloud&quot;;
+      adminpassFile = &quot;/path/to/admin-pass-file&quot;;
+      adminuser = &quot;root&quot;;
     };
   };
 
   services.postgresql = {
     enable = true;
-    ensureDatabases = [ "nextcloud" ];
+    ensureDatabases = [ &quot;nextcloud&quot; ];
     ensureUsers = [
-     { name = "nextcloud";
-       ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES";
+     { name = &quot;nextcloud&quot;;
+       ensurePermissions.&quot;DATABASE nextcloud&quot; = &quot;ALL PRIVILEGES&quot;;
      }
     ];
   };
 
   # ensure that postgres is running *before* running the setup
-  systemd.services."nextcloud-setup" = {
-    requires = ["postgresql.service"];
-    after = ["postgresql.service"];
+  systemd.services.&quot;nextcloud-setup&quot; = {
+    requires = [&quot;postgresql.service&quot;];
+    after = [&quot;postgresql.service&quot;];
   };
 
   networking.firewall.allowedTCPPorts = [ 80 443 ];
 }
 </programlisting>
-  </para>
-
-  <para>
-   The <literal>hostName</literal> option is used internally to configure an HTTP
-   server using <link xlink:href="https://php-fpm.org/"><literal>PHP-FPM</literal></link>
-   and <literal>nginx</literal>. The <literal>config</literal> 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.
-  </para>
-
-  <para>
-   In case the application serves multiple domains (those are checked with
-   <link xlink:href="http://php.net/manual/en/reserved.variables.server.php"><literal>$_SERVER['HTTP_HOST']</literal></link>)
-   it's needed to add them to
-   <link linkend="opt-services.nextcloud.config.extraTrustedDomains"><literal>services.nextcloud.config.extraTrustedDomains</literal></link>.
-  </para>
-
-  <para>
-   Auto updates for Nextcloud apps can be enabled using
-   <link linkend="opt-services.nextcloud.autoUpdateApps.enable"><literal>services.nextcloud.autoUpdateApps</literal></link>.
-</para>
-
- </section>
-
- <section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
-  <title>Common problems</title>
-  <itemizedlist>
-   <listitem>
-    <formalpara>
-     <title>General notes</title>
-     <para>
-      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 <literal>nextcloud</literal> user (by default
-      <literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to
-      track several states of the application (e.g., whether installed or not).
-     </para>
-    </formalpara>
     <para>
-     All configuration parameters are also stored in
-     <filename>/var/lib/nextcloud/config/override.config.php</filename> which is generated by
-     the module and linked from the store to ensure that all values from
-     <filename>config.php</filename> can be modified by the module.
-     However <filename>config.php</filename> manages the application's state and shouldn't be
-     touched manually because of that.
+      The <literal>hostName</literal> option is used internally to
+      configure an HTTP server using
+      <link xlink:href="https://php-fpm.org/"><literal>PHP-FPM</literal></link>
+      and <literal>nginx</literal>. The <literal>config</literal>
+      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.
+    </para>
+    <para>
+      In case the application serves multiple domains (those are checked
+      with
+      <link xlink:href="http://php.net/manual/en/reserved.variables.server.php"><literal>$_SERVER['HTTP_HOST']</literal></link>)
+      it's needed to add them to
+      <link linkend="opt-services.nextcloud.config.extraTrustedDomains"><literal>services.nextcloud.config.extraTrustedDomains</literal></link>.
     </para>
-    <warning>
-     <para>Don't delete <filename>config.php</filename>! This file
-     tracks the application's state and a deletion can cause unwanted
-     side-effects!</para>
-    </warning>
-
-    <warning>
-     <para>Don't rerun <literal>nextcloud-occ
-     maintenance:install</literal>! This command tries to install the application
-     and can cause unwanted side-effects!</para>
-    </warning>
-   </listitem>
-   <listitem>
-    <formalpara>
-     <title>Multiple version upgrades</title>
-     <para>
-      Nextcloud doesn't allow to move more than one major-version forward. E.g., if you're on
-      <literal>v16</literal>, you cannot upgrade to <literal>v18</literal>, you need to upgrade to
-      <literal>v17</literal> first. This is ensured automatically as long as the
-      <link linkend="opt-system.stateVersion">stateVersion</link> 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 <emphasis>after</emphasis> that deploy.
-     </para>
-    </formalpara>
-   </listitem>
-   <listitem>
-    <formalpara>
-     <title><literal>Error: Command "upgrade" is not defined.</literal></title>
-     <para>
-      This error usually occurs if the initial installation
-      (<command>nextcloud-occ maintenance:install</command>) has failed. After that, the application
-      is not installed, but the upgrade is attempted to be executed. Further context can
-      be found in <link xlink:href="https://github.com/NixOS/nixpkgs/issues/111175">NixOS/nixpkgs#111175</link>.
-     </para>
-    </formalpara>
     <para>
-     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</command> and try to fix
-     the underlying issue.
+      Auto updates for Nextcloud apps can be enabled using
+      <link linkend="opt-services.nextcloud.autoUpdateApps.enable"><literal>services.nextcloud.autoUpdateApps</literal></link>.
     </para>
+  </section>
+  <section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
+    <title>Common problems</title>
     <itemizedlist>
-     <listitem>
-      <para>
-       If this occurs on an <emphasis>existing</emphasis> setup, this is most likely because
-       the maintenance mode is active. It can be deactivated by running
-       <command>nextcloud-occ maintenance:mode --off</command>. It's advisable though to
-       check the logs first on why the maintenance mode was activated.
-      </para>
-     </listitem>
-     <listitem>
-      <warning><para>Only perform the following measures on
-      <emphasis>freshly installed instances!</emphasis></para></warning>
-      <para>
-       A re-run of the installer can be forced by <emphasis>deleting</emphasis>
-       <filename>/var/lib/nextcloud/config/config.php</filename>. 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/</command>.
-      </para>
-     </listitem>
+      <listitem>
+        <para>
+          <emphasis role="strong">General notes.</emphasis>
+          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 <literal>nextcloud</literal> user
+          (by default
+          <literal>/var/lib/nextcloud/config/config.php</literal>) and
+          is also used to track several states of the application (e.g.,
+          whether installed or not).
+        </para>
+        <para>
+          All configuration parameters are also stored in
+          <filename>/var/lib/nextcloud/config/override.config.php</filename>
+          which is generated by the module and linked from the store to
+          ensure that all values from <filename>config.php</filename>
+          can be modified by the module. However
+          <filename>config.php</filename> manages the application's
+          state and shouldn't be touched manually because of that.
+        </para>
+        <warning>
+          <para>
+            Don't delete <filename>config.php</filename>! This file
+            tracks the application's state and a deletion can cause
+            unwanted side-effects!
+          </para>
+        </warning>
+        <warning>
+          <para>
+            Don't rerun
+            <literal>nextcloud-occ maintenance:install</literal>! This
+            command tries to install the application and can cause
+            unwanted side-effects!
+          </para>
+        </warning>
+      </listitem>
+      <listitem>
+        <para>
+          <emphasis role="strong">Multiple version upgrades.</emphasis>
+          Nextcloud doesn't allow to move more than one major-version
+          forward. E.g., if you're on <literal>v16</literal>, you cannot
+          upgrade to <literal>v18</literal>, you need to upgrade to
+          <literal>v17</literal> first. This is ensured automatically as
+          long as the
+          <link linkend="opt-system.stateVersion">stateVersion</link> 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
+          <emphasis>after</emphasis> that deploy.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <emphasis role="strong"><literal>Error: Command &quot;upgrade&quot; is not defined.</literal></emphasis>
+          This error usually occurs if the initial installation
+          (<command>nextcloud-occ maintenance:install</command>) has
+          failed. After that, the application is not installed, but the
+          upgrade is attempted to be executed. Further context can be
+          found in
+          <link xlink:href="https://github.com/NixOS/nixpkgs/issues/111175">NixOS/nixpkgs#111175</link>.
+        </para>
+        <para>
+          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</command> and try to
+          fix the underlying issue.
+        </para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              If this occurs on an <emphasis>existing</emphasis> setup,
+              this is most likely because the maintenance mode is
+              active. It can be deactivated by running
+              <command>nextcloud-occ maintenance:mode --off</command>.
+              It's advisable though to check the logs first on why the
+              maintenance mode was activated.
+            </para>
+          </listitem>
+          <listitem>
+            <warning>
+              <para>
+                Only perform the following measures on <emphasis>freshly
+                installed instances!</emphasis>
+              </para>
+            </warning>
+            <para>
+              A re-run of the installer can be forced by
+              <emphasis>deleting</emphasis>
+              <filename>/var/lib/nextcloud/config/config.php</filename>.
+              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/</command>.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
+      <listitem>
+        <para>
+          <emphasis role="strong">Server-side encryption.</emphasis>
+          Nextcloud supports
+          <link xlink:href="https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html">server-side
+          encryption (SSE)</link>. 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
+          <xref linkend="opt-system.stateVersion"></xref> is
+          <emphasis>above</emphasis> <literal>22.05</literal>, this is
+          disabled by default. To turn it on again and for further
+          information please refer to
+          <xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE"></xref>.
+        </para>
+      </listitem>
     </itemizedlist>
-   </listitem>
-   <listitem>
-    <formalpara>
-     <title>Server-side encryption</title>
-     <para>
-      Nextcloud supports <link xlink:href="https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html">server-side encryption (SSE)</link>.
-      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 <xref linkend="opt-system.stateVersion" /> is <emphasis>above</emphasis> <literal>22.05</literal>,
-      this is disabled by default. To turn it on again and for further information please refer to
-      <xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE" />.
-     </para>
-    </formalpara>
-   </listitem>
-  </itemizedlist>
- </section>
-
- <section xml:id="module-services-nextcloud-httpd">
-  <title>Using an alternative webserver as reverse-proxy (e.g. <literal>httpd</literal>)</title>
-  <para>
-   By default, <literal>nginx</literal> is used as reverse-proxy for <literal>nextcloud</literal>.
-   However, it's possible to use e.g. <literal>httpd</literal> by explicitly disabling
-   <literal>nginx</literal> using <xref linkend="opt-services.nginx.enable" /> and fixing the
-   settings <literal>listen.owner</literal> &amp; <literal>listen.group</literal> in the
-   <link linkend="opt-services.phpfpm.pools">corresponding <literal>phpfpm</literal> pool</link>.
-  </para>
-  <para>
-   An exemplary configuration may look like this:
-<programlisting>
+  </section>
+  <section xml:id="module-services-nextcloud-httpd">
+    <title>Using an alternative webserver as reverse-proxy (e.g.
+    <literal>httpd</literal>)</title>
+    <para>
+      By default, <literal>nginx</literal> is used as reverse-proxy for
+      <literal>nextcloud</literal>. However, it's possible to use e.g.
+      <literal>httpd</literal> by explicitly disabling
+      <literal>nginx</literal> using
+      <xref linkend="opt-services.nginx.enable"></xref> and fixing the
+      settings <literal>listen.owner</literal> &amp;
+      <literal>listen.group</literal> in the
+      <link linkend="opt-services.phpfpm.pools">corresponding
+      <literal>phpfpm</literal> pool</link>.
+    </para>
+    <para>
+      An exemplary configuration may look like this:
+    </para>
+    <programlisting>
 { config, lib, pkgs, ... }: {
   services.nginx.enable = false;
   services.nextcloud = {
     enable = true;
-    hostName = "localhost";
+    hostName = &quot;localhost&quot;;
 
     /* further, required options */
   };
   services.phpfpm.pools.nextcloud.settings = {
-    "listen.owner" = config.services.httpd.user;
-    "listen.group" = config.services.httpd.group;
+    &quot;listen.owner&quot; = config.services.httpd.user;
+    &quot;listen.group&quot; = config.services.httpd.group;
   };
   services.httpd = {
     enable = true;
-    adminAddr = "webmaster@localhost";
-    extraModules = [ "proxy_fcgi" ];
-    virtualHosts."localhost" = {
+    adminAddr = &quot;webmaster@localhost&quot;;
+    extraModules = [ &quot;proxy_fcgi&quot; ];
+    virtualHosts.&quot;localhost&quot; = {
       documentRoot = config.services.nextcloud.package;
       extraConfig = ''
-        &lt;Directory "${config.services.nextcloud.package}"&gt;
-          &lt;FilesMatch "\.php$"&gt;
-            &lt;If "-f %{REQUEST_FILENAME}"&gt;
-              SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
+        &lt;Directory &quot;${config.services.nextcloud.package}&quot;&gt;
+          &lt;FilesMatch &quot;\.php$&quot;&gt;
+            &lt;If &quot;-f %{REQUEST_FILENAME}&quot;&gt;
+              SetHandler &quot;proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/&quot;
             &lt;/If&gt;
           &lt;/FilesMatch&gt;
           &lt;IfModule mod_rewrite.c&gt;
@@ -243,69 +261,71 @@
   };
 }
 </programlisting>
-  </para>
- </section>
-
- <section xml:id="installing-apps-php-extensions-nextcloud">
-  <title>Installing Apps and PHP extensions</title>
-
-  <para>
-   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 <xref linkend="opt-services.nextcloud.phpExtraExtensions" /> setting.
-  </para>
-
-  <para>
-   Alternatively, extra apps can also be declared with the <xref linkend="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.
-  </para>
- </section>
-
- <section xml:id="module-services-nextcloud-maintainer-info">
-  <title>Maintainer information</title>
-
-  <para>
-   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.
-  </para>
-
-  <para>
-   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 <literal>v19.0.0</literal>
-   should be available in <literal>nixpkgs</literal> as <literal>pkgs.nextcloud19</literal>).
-   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 <literal>nextcloud</literal>-module should be
-   updated to make sure that the
-   <link linkend="opt-services.nextcloud.package">package</link>-option selects the latest version
-   on fresh setups.
-  </para>
-
-  <para>
-   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
-   <literal>&lt;nixpkgs/pkgs/servers/nextcloud/default.nix&gt;</literal>):
-<programlisting>
+  </section>
+  <section xml:id="installing-apps-php-extensions-nextcloud">
+    <title>Installing Apps and PHP extensions</title>
+    <para>
+      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
+      <xref linkend="opt-services.nextcloud.phpExtraExtensions"></xref>
+      setting.
+    </para>
+    <para>
+      Alternatively, extra apps can also be declared with the
+      <xref linkend="opt-services.nextcloud.extraApps"></xref> 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.
+    </para>
+  </section>
+  <section xml:id="module-services-nextcloud-maintainer-info">
+    <title>Maintainer information</title>
+    <para>
+      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.
+    </para>
+    <para>
+      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
+      <literal>v19.0.0</literal> should be available in
+      <literal>nixpkgs</literal> as
+      <literal>pkgs.nextcloud19</literal>). 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
+      <literal>nextcloud</literal>-module should be updated to make sure
+      that the
+      <link linkend="opt-services.nextcloud.package">package</link>-option
+      selects the latest version on fresh setups.
+    </para>
+    <para>
+      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
+      <literal>&lt;nixpkgs/pkgs/servers/nextcloud/default.nix&gt;</literal>):
+    </para>
+    <programlisting>
 /* ... */
 {
   nextcloud17 = generic {
-    version = "17.0.x";
-    sha256 = "0000000000000000000000000000000000000000000000000000";
+    version = &quot;17.0.x&quot;;
+    sha256 = &quot;0000000000000000000000000000000000000000000000000000&quot;;
     eol = true;
   };
 }
 </programlisting>
-  </para>
-
-  <para>
-   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.
-  </para>
- </section>
+    <para>
+      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.
+    </para>
+  </section>
 </chapter>