nixos/nextcloud: add some notes for Error: Command "upgrade" is not defined.

This error occurs if `nextcloud-occ maintenance:install` fails and the
`upgrade` command is attempted to be executed afterwards.

Due to the nature of the installer we can't do much about it, so I guess
it makes sense to add some notes about it. The other notes in the
`Pitfalls`-section are semantically a list of different topics, so I
changed that accordingly now.

Closes #111175
This commit is contained in:
Maximilian Bosch 2021-08-27 22:36:45 +02:00
parent 40f337454d
commit 561418f996
No known key found for this signature in database
GPG Key ID: 091DBF4D1FC46B8E

View File

@ -84,47 +84,93 @@
</para>
</section>
<section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
<title>Pitfalls</title>
<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.
</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>
<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>
All configuration parameters are also stored in
<literal>/var/lib/nextcloud/config/override.config.php</literal> which is generated by
the module and linked from the store to ensure that all values from <literal>config.php</literal>
can be modified by the module.
However <literal>config.php</literal> manages the application's state and shouldn't be touched
manually because of that.
</para>
<warning>
<para>Don't delete <literal>config.php</literal>! 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>
<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>
<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. 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>
</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.
</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
where this is 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>
</itemizedlist>
</section>
<section xml:id="module-services-nextcloud-httpd">