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
parent
40f337454d
commit
561418f996
1 changed files with 85 additions and 39 deletions
|
|
@ -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">
|
||||
|
|
|
|||
Loading…
Reference in a new issue