JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cb37cdfcf7
nixpkgs/nixos/modules/services/web-apps/nextcloud.xml

172 lines
7.6 KiB
XML
Raw Normal View History

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).
2018-11-25 23:43:45 +00:00
<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>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
<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>.
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).
2018-11-25 23:43:45 +00:00
</para>
<section xml:id="module-services-nextcloud-basic-usage">
<title>Basic usage</title>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
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).
2018-11-25 23:43:45 +00:00
<para>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
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>).
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).
2018-11-25 23:43:45 +00:00
</para>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
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).
2018-11-25 23:43:45 +00:00
<para>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
A very basic configuration may look like this:
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).
2018-11-25 23:43:45 +00:00
<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";
postgresql: Move socket dir to /run/postgresql The default, which is /tmp, has a few issues associated with it: One being that it makes it easy for users on the system to spoof a PostgreSQL server if it's not running, causing applications to connect to their provided sockets instead of just failing to connect. Another one is that it makes sandboxing of PostgreSQL and other services unnecessarily difficult. This is already the case if only PrivateTmp is used in a systemd service, so in order for such a service to be able to connect to PostgreSQL, a bind mount needs to be done from /tmp to some other path, so the service can access it. This pretty much defeats the whole purpose of PrivateTmp. We regularily run into issues with this in the past already (one example would be https://github.com/NixOS/nixpkgs/pull/24317) and with the new systemd-confinement mode upcoming in https://github.com/NixOS/nixpkgs/pull/57519, it makes it even more tedious to sandbox services. I've tested this change against all the postgresql NixOS VM tests and they still succeed and I also grepped through the source tree to replace other occasions where we might have /tmp hardcoded. Luckily there were very few occasions. Signed-off-by: aszlig <aszlig@nix.build> Cc: @ocharles, @thoughtpolice, @danbst
2019-03-15 03:52:35 +00:00
<link linkend="opt-services.nextcloud.config.dbhost">dbhost</link> = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself
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).
2018-11-25 23:43:45 +00:00
<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;
nixos/nextcloud: write config to additional config file One of the main problems of the Nextcloud module is that it's currently not possible to alter e.g. database configuration after the initial setup as it's written by their imperative installer to a file. After some research[1] it turned out that it's possible to override all values with an additional config file. The documentation has been slightly updated to remain up-to-date, but the warnings should remain there as the imperative configuration is still used and may cause unwanted side-effects. Also simplified the postgresql test which uses `ensure{Databases,Users}` to configure the database. Fixes #49783 [1] https://github.com/NixOS/nixpkgs/issues/49783#issuecomment-483063922
2019-06-28 16:54:11 +01:00
<link linkend="opt-services.postgresql.ensureDatabases">ensureDatabases</link> = [ "nextcloud" ];
<link linkend="opt-services.postgresql.ensureUsers">ensureUsers</link> = [
{ name = "nextcloud";
ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES";
}
];
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).
2018-11-25 23:43:45 +00:00
};
# 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>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
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).
2018-11-25 23:43:45 +00:00
<para>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
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 by the imperative installer and all values are written to an additional file
to ensure that changes can be applied by changing the module's options.
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).
2018-11-25 23:43:45 +00:00
</para>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
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).
2018-11-25 23:43:45 +00:00
<para>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
In case the application serves multiple domains (those are checked with
<literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>)
it's needed to add them to
<literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>.
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).
2018-11-25 23:43:45 +00:00
</para>
nixos/nextcloud: write config to additional config file One of the main problems of the Nextcloud module is that it's currently not possible to alter e.g. database configuration after the initial setup as it's written by their imperative installer to a file. After some research[1] it turned out that it's possible to override all values with an additional config file. The documentation has been slightly updated to remain up-to-date, but the warnings should remain there as the imperative configuration is still used and may cause unwanted side-effects. Also simplified the postgresql test which uses `ensure{Databases,Users}` to configure the database. Fixes #49783 [1] https://github.com/NixOS/nixpkgs/issues/49783#issuecomment-483063922
2019-06-28 16:54:11 +01:00
<para>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
Auto updates for Nextcloud apps can be enabled using
<literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</link></literal>.
</para>
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).
2018-11-25 23:43:45 +00:00
</section>
<section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
<title>Pitfalls</title>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
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).
2018-11-25 23:43:45 +00:00
<para>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
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).
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).
2018-11-25 23:43:45 +00:00
</para>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
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).
2018-11-25 23:43:45 +00:00
<para>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
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.
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).
2018-11-25 23:43:45 +00:00
</para>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
nixos/nextcloud: write config to additional config file One of the main problems of the Nextcloud module is that it's currently not possible to alter e.g. database configuration after the initial setup as it's written by their imperative installer to a file. After some research[1] it turned out that it's possible to override all values with an additional config file. The documentation has been slightly updated to remain up-to-date, but the warnings should remain there as the imperative configuration is still used and may cause unwanted side-effects. Also simplified the postgresql test which uses `ensure{Databases,Users}` to configure the database. Fixes #49783 [1] https://github.com/NixOS/nixpkgs/issues/49783#issuecomment-483063922
2019-06-28 16:54:11 +01:00
<warning>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
<para>Don't delete <literal>config.php</literal>! This file
tracks the application's state and a deletion can cause unwanted
side-effects!</para>
nixos/nextcloud: write config to additional config file One of the main problems of the Nextcloud module is that it's currently not possible to alter e.g. database configuration after the initial setup as it's written by their imperative installer to a file. After some research[1] it turned out that it's possible to override all values with an additional config file. The documentation has been slightly updated to remain up-to-date, but the warnings should remain there as the imperative configuration is still used and may cause unwanted side-effects. Also simplified the postgresql test which uses `ensure{Databases,Users}` to configure the database. Fixes #49783 [1] https://github.com/NixOS/nixpkgs/issues/49783#issuecomment-483063922
2019-06-28 16:54:11 +01:00
</warning>
nixos docs: run the formatting tool (no content change) As documented in the docs themselves :-)
2019-03-22 13:44:11 +00:00
nixos/nextcloud: write config to additional config file One of the main problems of the Nextcloud module is that it's currently not possible to alter e.g. database configuration after the initial setup as it's written by their imperative installer to a file. After some research[1] it turned out that it's possible to override all values with an additional config file. The documentation has been slightly updated to remain up-to-date, but the warnings should remain there as the imperative configuration is still used and may cause unwanted side-effects. Also simplified the postgresql test which uses `ensure{Databases,Users}` to configure the database. Fixes #49783 [1] https://github.com/NixOS/nixpkgs/issues/49783#issuecomment-483063922
2019-06-28 16:54:11 +01:00
<warning>
Revert "nixos/doc: re-format" This reverts commit ea6e8775bd69e4676c623a85c39f1da540d29ad1. The new format is not an improvement.
2019-09-19 18:17:30 +01:00
<para>Don't rerun <literal>nextcloud-occ
maintenance:install</literal>! This command tries to install the application
and can cause unwanted side-effects!</para>
nixos/nextcloud: write config to additional config file One of the main problems of the Nextcloud module is that it's currently not possible to alter e.g. database configuration after the initial setup as it's written by their imperative installer to a file. After some research[1] it turned out that it's possible to override all values with an additional config file. The documentation has been slightly updated to remain up-to-date, but the warnings should remain there as the imperative configuration is still used and may cause unwanted side-effects. Also simplified the postgresql test which uses `ensure{Databases,Users}` to configure the database. Fixes #49783 [1] https://github.com/NixOS/nixpkgs/issues/49783#issuecomment-483063922
2019-06-28 16:54:11 +01:00
</warning>
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
2020-03-14 03:07:30 +00:00
<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>
nixos/nextcloud: update upgrade-path for nextcloud19 Enhance the heuristics to make sure that a user doesn't accidentally upgrade across two major versions of Nextcloud (e.g. from v17 to v19). The original idea/discussion has been documented in the nixpkgs manual[1]. This includes the following changes: * `nextcloud19` will be selected automatically when having a stateVersion greater or equal than 20.09. For existing setups, the package has to be selected manually to avoid accidental upgrades. * When using `nextcloud18` or older, a warning will be thrown which recommends upgrading to `nextcloud19`. * Added a brief paragraph about `nextcloud19` in the NixOS 19.09 release notes. * Restart `phpfpm` if the Nextcloud-package (`cfg.package`) changes[2]. [1] https://nixos.org/nixos/manual/index.html#module-services-nextcloud-maintainer-info [2] https://github.com/NixOS/nixpkgs/pull/89427#issuecomment-638885727
2020-06-03 17:57:14 +01:00
<para>
Ideally we should make sure that it's possible to jump two NixOS versions forward:
i.e. the warnings and the logic in the module should guard a user to upgrade from a
Nextcloud on e.g. 19.09 to a Nextcloud on 20.09.
</para>
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).
2018-11-25 23:43:45 +00:00
</section>
</chapter>
Reference in New Issue Copy Permalink