JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

nixos/nextcloud: add basic module documentation and warn about current upgrading issues

Browse Source 
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).
This commit is contained in:
Maximilian Bosch 2018-11-26 00:43:45 +01:00
parent 21773f1d43
commit 216a954540
No known key found for this signature in database
GPG Key ID: 091DBF4D1FC46B8E
2 changed files with 101 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
nixos/modules/services/web-apps/nextcloud.nix
View File

@ -484,4 +484,6 @@ in {
};
})
]);
meta.doc = ./nextcloud.xml;
}

99
nixos/modules/services/web-apps/nextcloud.xml Normal file
View File

@ -0,0 +1,99 @@
<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>
<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>.
</para>
<section xml:id="module-services-nextcloud-basic-usage">
<title>Basic usage</title>
<para>
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>).
</para>
<para>
A very basic configuration may look like this:
<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";
<link linkend="opt-services.nextcloud.config.dbhost">dbhost</link> = "/tmp"; # nextcloud will add /.s.PGSQL.5432 by itself
<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;
<link linkend="opt-services.postgresql.initialScript">initialScript</link> = pkgs.writeText "psql-init" ''
CREATE ROLE nextcloud WITH LOGIN;
CREATE DATABASE nextcloud WITH OWNER nextcloud;
'';
};
# 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>
<para>
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 for the <literal>config.php</literal> which is used
for the application's configuration.
<emphasis>Beware: this isn't entirely pure since the config is modified by the application's runtime!</emphasis>
</para>
<para>
In case the application serves multiple hosts (those are checked with
<literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>)
those can be added using
<literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>.
</para>
</section>
<section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
<title>Pitfalls</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>
<para>
Right now changes to the <literal>services.nextcloud.config</literal> attribute set won't take effect
after the first install
(except <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>) since the actual configuration
file is generated by the NextCloud installer which also sets up critical parts such as the database
structure.
</para>
<para>
<emphasis>Warning: don't delete <literal>config.php</literal>! This file tracks the application's state and a deletion can cause unwanted side-effects!</emphasis>
</para>
<para>
<emphasis>Warning: don't rerun <literal>nextcloud-occ maintenance:install</literal>! This command tries to install the application and can cause unwanted side-effects!</emphasis>
</para>
<para>
The issues are known and reported in <link xlink:href="https://github.com/NixOS/nixpkgs/issues/49783">#49783</link>, for now it's unfortunately necessary to manually work around these issues.
</para>
</section>
</chapter>