nixos/nextcloud: convert manual chapter to MD

3 files changed, 500 insertions, 241 deletions

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