nixos/nextcloud: add basic module documentation and warn about current upgrading issues

Part of #49783. NextCloud tracks in its `config.php` the application's
state which makes it hard for the module to modify configurations during
upgrades.

It will take time until the issue is properly fixed, therefore we
decided to warn about this in the manual.

This PR addresses two things:

* Adding a basic example for nextcloud. I figured it to be helpful to
  add some basic usage instructions when adding a new manual entry.
  Advanced documentation may follow later.

  For now this document actively links to the service options, so users
  are guided to the remaining options that can be helpful in certain
  cases.

* Add a warning about upgrades and manual changes in
  `/var/lib/nextcloud`. This will be fixed in the future, but it's
  definetely helpful to document the current issues in the manual (as
  proposed in https://github.com/NixOS/nixpkgs/issues/49783#issuecomment-439691127).

2 files changed, 101 insertions, 0 deletions

diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix
index d0efdf88d73c..ecb1c5615d58 100644
--- a/nixos/modules/services/web-apps/nextcloud.nix
+++ b/nixos/modules/services/web-apps/nextcloud.nix
@@ -484,4 +484,6 @@ in {
       };
     })
   ]);
+
+  meta.doc = ./nextcloud.xml;
 }
diff --git a/nixos/modules/services/web-apps/nextcloud.xml b/nixos/modules/services/web-apps/nextcloud.xml
new file mode 100644
index 000000000000..9600d1be7c88
--- /dev/null
+++ b/nixos/modules/services/web-apps/nextcloud.xml
@@ -0,0 +1,99 @@
+<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>
+
+ <section xml:id="module-services-nextcloud-basic-usage">
+  <title>Basic usage</title>
+  <para>
+   Nextcloud is a PHP-based application which requires an HTTP server
+   (<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal> optionally supports
+   <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>) and a database
+   (it's recommended to use <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>).
+  </para>
+  <para>
+    A very basic configuration may look like this:
+<programlisting>{ pkgs, ... }:
+{
+  services.nextcloud = {
+    <link linkend="opt-services.nextcloud.enable">enable</link> = true;
+    <link linkend="opt-services.nextcloud.hostName">hostName</link> = "nextcloud.tld";
+    <link linkend="opt-services.nextcloud.nginx.enable">nginx.enable</link> = true;
+    config = {
+      <link linkend="opt-services.nextcloud.config.dbtype">dbtype</link> = "pgsql";
+      <link linkend="opt-services.nextcloud.config.dbuser">dbuser</link> = "nextcloud";
+      <link linkend="opt-services.nextcloud.config.dbhost">dbhost</link> = "/tmp"; # nextcloud will add /.s.PGSQL.5432 by itself
+      <link linkend="opt-services.nextcloud.config.dbname">dbname</link> = "nextcloud";
+      <link linkend="opt-services.nextcloud.config.adminpassFile">adminpassFile</link> = "/path/to/admin-pass-file";
+      <link linkend="opt-services.nextcloud.config.adminuser">adminuser</link> = "root";
+    };
+  };
+
+  services.postgresql = {
+    <link linkend="opt-services.postgresql.enable">enable</link> = true;
+    <link linkend="opt-services.postgresql.initialScript">initialScript</link> = pkgs.writeText "psql-init" ''
+      CREATE ROLE nextcloud WITH LOGIN;
+      CREATE DATABASE nextcloud WITH OWNER nextcloud;
+    '';
+  };
+
+  # ensure that postgres is running *before* running the setup
+  systemd.services."nextcloud-setup" = {
+    requires = ["postgresql.service"];
+    after = ["postgresql.service"];
+  };
+
+  <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ];
+}</programlisting>
+  </para>
+  <para>
+   The options <literal>hostName</literal> and <literal>nginx.enable</literal> are used internally to configure an
+   HTTP server using <literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal> and <literal>nginx</literal>.
+   The <literal>config</literal> attribute set is used for the <literal>config.php</literal> which is used
+   for the application's configuration.
+   <emphasis>Beware: this isn't entirely pure since the config is modified by the application's runtime!</emphasis>
+  </para>
+  <para>
+    In case the application serves multiple hosts (those are checked with
+    <literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>)
+    those can be added using
+    <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>.
+  </para>
+ </section>
+
+ <section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
+  <title>Pitfalls</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>
+  <para>
+   Right now changes to the <literal>services.nextcloud.config</literal> attribute set won't take effect
+   after the first install
+   (except <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>) since the actual configuration
+   file is generated by the NextCloud installer which also sets up critical parts such as the database
+   structure.
+  </para>
+  <para>
+   <emphasis>Warning: don't delete <literal>config.php</literal>! This file tracks the application's state and a deletion can cause unwanted side-effects!</emphasis>
+  </para>
+  <para>
+   <emphasis>Warning: don't rerun <literal>nextcloud-occ maintenance:install</literal>! This command tries to install the application and can cause unwanted side-effects!</emphasis>
+  </para>
+  <para>
+    The issues are known and reported in <link xlink:href="https://github.com/NixOS/nixpkgs/issues/49783">#49783</link>, for now it's unfortunately necessary to manually work around these issues.
+  </para>
+ </section>
+
+</chapter>