Merge pull request #82353 from Ma27/nextcloud-upgrade-path

nixos/nextcloud: fix upgrade path from 19.09 to 20.03

3 files changed, 133 insertions, 8 deletions

diff --git a/nixos/doc/manual/release-notes/rl-2003.xml b/nixos/doc/manual/release-notes/rl-2003.xml
index e5351519f8d..02d05dec0a2 100644
--- a/nixos/doc/manual/release-notes/rl-2003.xml
+++ b/nixos/doc/manual/release-notes/rl-2003.xml
@@ -648,6 +648,55 @@ auth required pam_succeed_if.so uid >= 1000 quiet
        <xref linkend="opt-environment.systemPackages"/>.
      </para>
    </listitem>
+   <listitem>
+    <para>
+     <package>nextcloud</package> has been updated to <literal>v18.0.2</literal>. This means
+     that users from NixOS 19.09 can't upgrade directly since you can only move one version
+      forward and 19.09 uses <literal>v16.0.8</literal>.
+    </para>
+    <para>
+     To provide a safe upgrade-path and to circumvent similar issues in the future, the following
+     measures were taken:
+     <itemizedlist>
+      <listitem>
+       <para>
+        The <package>pkgs.nextcloud</package>-attribute has been removed and replaced with
+        versioned attributes (currently <package>pkgs.nextcloud17</package> and
+        <package>pkgs.nextcloud18</package>). With this change major-releases can be backported
+        without breaking stuff and to make upgrade-paths easier.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        Existing setups will be detected using
+        <link linkend="opt-system.stateVersion">system.stateVersion</link>: by default,
+        <package>nextcloud17</package> will be used, but will raise a warning which notes
+        that after that deploy it's recommended to update to the latest stable version
+        (<package>nextcloud18</package>) by declaring the newly introduced setting
+        <link linkend="opt-services.nextcloud.package">services.nextcloud.package</link>.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        Users with an overlay (e.g. to use <package>nextcloud</package> at version
+        <literal>v18</literal> on <literal>19.09</literal>) will get an evaluation error
+        by default. This is done to ensure that our
+        <link linkend="opt-services.nextcloud.package">package</link>-option doesn't select an
+        older version by accident. It's recommended to use <package>pkgs.nextcloud18</package>
+        or to set <link linkend="opt-services.nextcloud.package">package</link> to
+        <package>pkgs.nextcloud</package> explicitly.
+       </para>
+      </listitem>
+     </itemizedlist>
+    </para>
+    <warning>
+     <para>
+      Please note that if you're comming from <literal>19.03</literal> or older, you have
+      to manually upgrade to <literal>19.09</literal> first to upgrade your server
+      to Nextcloud v16.
+     </para>
+    </warning>
+   </listitem>
   </itemizedlist>
  </section>
 
diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix
index 912e05d6d40..087bd0e5df3 100644
--- a/nixos/modules/services/web-apps/nextcloud.nix
+++ b/nixos/modules/services/web-apps/nextcloud.nix
@@ -30,7 +30,7 @@ let
 
   occ = pkgs.writeScriptBin "nextcloud-occ" ''
     #! ${pkgs.stdenv.shell}
-    cd ${pkgs.nextcloud}
+    cd ${cfg.package}
     sudo=exec
     if [[ "$USER" != nextcloud ]]; then
       sudo='exec /run/wrappers/bin/sudo -u nextcloud --preserve-env=NEXTCLOUD_CONFIG_DIR'
@@ -42,6 +42,8 @@ let
       occ $*
   '';
 
+  inherit (config.system) stateVersion;
+
 in {
   options.services.nextcloud = {
     enable = mkEnableOption "nextcloud";
@@ -64,6 +66,11 @@ in {
       default = false;
       description = "Use https for generated links.";
     };
+    package = mkOption {
+      type = types.package;
+      description = "Which package to use for the Nextcloud instance.";
+      relatedPackages = [ "nextcloud17" "nextcloud18" ];
+    };
 
     maxUploadSize = mkOption {
       default = "512M";
@@ -309,10 +316,31 @@ in {
         }
       ];
 
-      warnings = optional (cfg.poolConfig != null) ''
-        Using config.services.nextcloud.poolConfig is deprecated and will become unsupported in a future release.
-        Please migrate your configuration to config.services.nextcloud.poolSettings.
-      '';
+      warnings = []
+        ++ (optional (cfg.poolConfig != null) ''
+          Using config.services.nextcloud.poolConfig is deprecated and will become unsupported in a future release.
+          Please migrate your configuration to config.services.nextcloud.poolSettings.
+        '')
+        ++ (optional (versionOlder cfg.package.version "18") ''
+          You're currently deploying an older version of Nextcloud. This may be needed
+          since Nextcloud doesn't allow major version upgrades across multiple versions (i.e. an
+          upgrade from 16 is possible to 17, but not to 18).
+
+          Please deploy this to your server and wait until the migration is finished. After
+          that you can deploy to the latest Nextcloud version available.
+        '');
+
+      services.nextcloud.package = with pkgs;
+        mkDefault (
+          if pkgs ? nextcloud
+            then throw ''
+              The `pkgs.nextcloud`-attribute has been removed. If it's supposed to be the default
+              nextcloud defined in an overlay, please set `services.nextcloud.package` to
+              `pkgs.nextcloud`.
+            ''
+          else if versionOlder stateVersion "20.03" then nextcloud17
+          else nextcloud18
+        );
     }
 
     { systemd.timers.nextcloud-cron = {
@@ -407,7 +435,7 @@ in {
           path = [ occ ];
           script = ''
             chmod og+x ${cfg.home}
-            ln -sf ${pkgs.nextcloud}/apps ${cfg.home}/
+            ln -sf ${cfg.package}/apps ${cfg.home}/
             mkdir -p ${cfg.home}/config ${cfg.home}/data ${cfg.home}/store-apps
             ln -sf ${overrideConfig} ${cfg.home}/config/override.config.php
 
@@ -429,7 +457,7 @@ in {
           environment.NEXTCLOUD_CONFIG_DIR = "${cfg.home}/config";
           serviceConfig.Type = "oneshot";
           serviceConfig.User = "nextcloud";
-          serviceConfig.ExecStart = "${phpPackage}/bin/php -f ${pkgs.nextcloud}/cron.php";
+          serviceConfig.ExecStart = "${phpPackage}/bin/php -f ${cfg.package}/cron.php";
         };
         nextcloud-update-plugins = mkIf cfg.autoUpdateApps.enable {
           serviceConfig.Type = "oneshot";
@@ -471,7 +499,7 @@ in {
         enable = true;
         virtualHosts = {
           ${cfg.hostName} = {
-            root = pkgs.nextcloud;
+            root = cfg.package;
             locations = {
               "= /robots.txt" = {
                 priority = 100;
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>