nixos/nextcloud: implement a safe upgrade-path between 19.09 and 20.03

It's impossible to move two major-versions forward when upgrading
Nextcloud. This is an issue when comming from 19.09 (using Nextcloud 16)
and trying to upgrade to 20.03 (using Nextcloud 18 by default).

This patch implements the measurements discussed in #82056 and #82353 to
improve the update process and to circumvent similar issues in the
future:

* `pkgs.nextcloud` has been removed in favor of versioned attributes
  (currently `pkgs.nextcloud17` and `pkgs.nextcloud18`). With that
  approach we can safely backport major-releases in the future to
  simplify those upgrade-paths and we can select one of the
  major-releases as default depending on the configuration (helpful to
  decide whether e.g. `pkgs.nextcloud17` or `pkgs.nextcloud18` should be
  used on 20.03 and `master` atm).

* If `system.stateVersion` is older than `20.03`, `nextcloud17` will be
  used (which is one major-release behind v16 from 19.09). When using a
  package older than the latest major-release available (currently v18),
  the evaluation will cause a warning which describes the issue and
  suggests next steps.

  To make those package-selections easier, a new option to define the
  package to be used for the service (namely
  `services.nextcloud.package`) was introduced.

* If `pkgs.nextcloud` exists (e.g. due to an overlay which was used to
  provide more recent Nextcloud versions on older NixOS-releases), an
  evaluation error will be thrown by default: this is to make sure that
  `services.nextcloud.package` doesn't use an older version by accident
  after checking the state-version. If `pkgs.nextcloud` is added
  manually, it needs to be declared explicitly in
  `services.nextcloud.package`.

* The `nixos/nextcloud`-documentation contains a
  "Maintainer information"-chapter  which describes how to roll out new
  Nextcloud releases and how to deal with old (and probably unsafe)
  versions.

Closes #82056

1 files changed, 48 insertions, 0 deletions

diff --git a/nixos/modules/services/web-apps/nextcloud.xml b/nixos/modules/services/web-apps/nextcloud.xml
index d66e0f0c299..fc454f8ba25 100644
--- a/nixos/modules/services/web-apps/nextcloud.xml
+++ b/nixos/modules/services/web-apps/nextcloud.xml
@@ -113,5 +113,53 @@
    maintenance:install</literal>! This command tries to install the application
    and can cause unwanted side-effects!</para>
   </warning>
+
+  <para>
+   Nextcloud doesn't allow to move more than one major-version forward. If you're e.g. 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>
+ </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 shold 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>/* ... */
+{
+  nextcloud17 = generic {
+    version = "17.0.x";
+    sha256 = "0000000000000000000000000000000000000000000000000000";
+    insecure = true;
+  };
+}</programlisting>
+  </para>
  </section>
 </chapter>