mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-12-06 20:44:13 +00:00
f7011c70f3
ChangeLog: https://nextcloud.com/changelog/#latest21 * Packaged 21.0.0, test-deployed it to my personal instance and tested the most basic functionality (`davfs2`-mount, {card,cal}dav sync, file management). * Bumped the default version for unstable/21.05 to `nextcloud21`. Since `nextcloud20` was added after the release of 20.09 (and thus the default on 20.09 is still `nextcloud19`), it's now needed to upgrade across two majors. This is not a problem though since it's possible to upgrade to v20 on 20.09 already and if not, the module will guard the administrator through the upgrade with eval warnings as it's the case since 20.03. * Dropped `nextcloud17` attribute and marked `nextcloud18` as EOL.
240 lines
11 KiB
XML
240 lines
11 KiB
XML
<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>
|
|
<para>
|
|
The current default by NixOS is <package>nextcloud21</package> which is also the latest
|
|
major version available.
|
|
</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";
|
|
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> = "/run/postgresql"; # 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.ensureDatabases">ensureDatabases</link> = [ "nextcloud" ];
|
|
<link linkend="opt-services.postgresql.ensureUsers">ensureUsers</link> = [
|
|
{ name = "nextcloud";
|
|
ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES";
|
|
}
|
|
];
|
|
};
|
|
|
|
# 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 <literal>hostName</literal> option is 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.
|
|
</para>
|
|
|
|
<para>
|
|
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>.
|
|
</para>
|
|
|
|
<para>
|
|
Auto updates for Nextcloud apps can be enabled using
|
|
<literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</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>
|
|
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>
|
|
</section>
|
|
|
|
<section xml:id="module-services-nextcloud-httpd">
|
|
<title>Using an alternative webserver as reverse-proxy (e.g. <literal>httpd</literal>)</title>
|
|
<para>
|
|
By default, <package>nginx</package> is used as reverse-proxy for <package>nextcloud</package>.
|
|
However, it's possible to use e.g. <package>httpd</package> by explicitly disabling
|
|
<package>nginx</package> using <xref linkend="opt-services.nginx.enable" /> and fixing the
|
|
settings <literal>listen.owner</literal> & <literal>listen.group</literal> in the
|
|
<link linkend="opt-services.phpfpm.pools">corresponding <literal>phpfpm</literal> pool</link>.
|
|
</para>
|
|
<para>
|
|
An exemplary configuration may look like this:
|
|
<programlisting>{ config, lib, pkgs, ... }: {
|
|
<link linkend="opt-services.nginx.enable">services.nginx.enable</link> = false;
|
|
services.nextcloud = {
|
|
<link linkend="opt-services.nextcloud.enable">enable</link> = true;
|
|
<link linkend="opt-services.nextcloud.hostName">hostName</link> = "localhost";
|
|
|
|
/* further, required options */
|
|
};
|
|
<link linkend="opt-services.phpfpm.pools._name_.settings">services.phpfpm.pools.nextcloud.settings</link> = {
|
|
"listen.owner" = config.services.httpd.user;
|
|
"listen.group" = config.services.httpd.group;
|
|
};
|
|
services.httpd = {
|
|
<link linkend="opt-services.httpd.enable">enable</link> = true;
|
|
<link linkend="opt-services.httpd.adminAddr">adminAddr</link> = "webmaster@localhost";
|
|
<link linkend="opt-services.httpd.extraModules">extraModules</link> = [ "proxy_fcgi" ];
|
|
virtualHosts."localhost" = {
|
|
<link linkend="opt-services.httpd.virtualHosts._name_.documentRoot">documentRoot</link> = config.services.nextcloud.package;
|
|
<link linkend="opt-services.httpd.virtualHosts._name_.extraConfig">extraConfig</link> = ''
|
|
<Directory "${config.services.nextcloud.package}">
|
|
<FilesMatch "\.php$">
|
|
<If "-f %{REQUEST_FILENAME}">
|
|
SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
|
|
</If>
|
|
</FilesMatch>
|
|
<IfModule mod_rewrite.c>
|
|
RewriteEngine On
|
|
RewriteBase /
|
|
RewriteRule ^index\.php$ - [L]
|
|
RewriteCond %{REQUEST_FILENAME} !-f
|
|
RewriteCond %{REQUEST_FILENAME} !-d
|
|
RewriteRule . /index.php [L]
|
|
</IfModule>
|
|
DirectoryIndex index.php
|
|
Require all granted
|
|
Options +FollowSymLinks
|
|
</Directory>
|
|
'';
|
|
};
|
|
};
|
|
}</programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="installing-apps-php-extensions-nextcloud">
|
|
<title>Installing Apps and PHP extensions</title>
|
|
|
|
<para>
|
|
Nextcloud apps are installed statefully through the web interface.
|
|
|
|
Some apps may require extra PHP extensions to be installed.
|
|
This can be configured with the <xref linkend="opt-services.nextcloud.phpExtraExtensions" /> setting.
|
|
</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><nixpkgs/pkgs/servers/nextcloud/default.nix></literal>):
|
|
<programlisting>/* ... */
|
|
{
|
|
nextcloud17 = generic {
|
|
version = "17.0.x";
|
|
sha256 = "0000000000000000000000000000000000000000000000000000";
|
|
eol = true;
|
|
};
|
|
}</programlisting>
|
|
</para>
|
|
|
|
<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>
|
|
</section>
|
|
</chapter>
|