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

nixos/nextcloud: convert manual chapter to MD

Browse Source
This commit is contained in:
pennae 2023-01-03 08:03:20 +01:00
parent 66fdc39d80
commit 42ea3f2699
3 changed files with 500 additions and 241 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

237
nixos/modules/services/web-apps/nextcloud.md Normal file
View File

@ -0,0 +1,237 @@
# Nextcloud {#module-services-nextcloud}
[Nextcloud](https://nextcloud.com/) is an open-source,
self-hostable cloud platform. The server setup can be automated using
[services.nextcloud](#opt-services.nextcloud.enable). A
desktop client is packaged at `pkgs.nextcloud-client`.
The current default by NixOS is `nextcloud25` which is also the latest
major version available.
## Basic usage {#module-services-nextcloud-basic-usage}
Nextcloud is a PHP-based application which requires an HTTP server
([`services.nextcloud`](#opt-services.nextcloud.enable)
optionally supports
[`services.nginx`](#opt-services.nginx.enable))
and a database (it's recommended to use
[`services.postgresql`](#opt-services.postgresql.enable)).
A very basic configuration may look like this:
```
{ pkgs, ... }:
{
services.nextcloud = {
enable = true;
hostName = "nextcloud.tld";
config = {
dbtype = "pgsql";
dbuser = "nextcloud";
dbhost = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself
dbname = "nextcloud";
adminpassFile = "/path/to/admin-pass-file";
adminuser = "root";
};
};
services.postgresql = {
enable = true;
ensureDatabases = [ "nextcloud" ];
ensureUsers = [
{ 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"];
};
networking.firewall.allowedTCPPorts = [ 80 443 ];
}
```
The `hostName` option is used internally to configure an HTTP
server using [`PHP-FPM`](https://php-fpm.org/)
and `nginx`. The `config` 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.
In case the application serves multiple domains (those are checked with
[`$_SERVER['HTTP_HOST']`](http://php.net/manual/en/reserved.variables.server.php))
it's needed to add them to
[`services.nextcloud.config.extraTrustedDomains`](#opt-services.nextcloud.config.extraTrustedDomains).
Auto updates for Nextcloud apps can be enabled using
[`services.nextcloud.autoUpdateApps`](#opt-services.nextcloud.autoUpdateApps.enable).
## Common problems {#module-services-nextcloud-pitfalls-during-upgrade}
- **General notes.**
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 `nextcloud` user (by default
`/var/lib/nextcloud/config/config.php`) and is also used to
track several states of the application (e.g., whether installed or not).
All configuration parameters are also stored in
{file}`/var/lib/nextcloud/config/override.config.php` which is generated by
the module and linked from the store to ensure that all values from
{file}`config.php` can be modified by the module.
However {file}`config.php` manages the application's state and shouldn't be
touched manually because of that.
::: {.warning}
Don't delete {file}`config.php`! This file
tracks the application's state and a deletion can cause unwanted
side-effects!
:::
::: {.warning}
Don't rerun `nextcloud-occ maintenance:install`!
This command tries to install the application
and can cause unwanted side-effects!
:::
- **Multiple version upgrades.**
Nextcloud doesn't allow to move more than one major-version forward. E.g., if you're on
`v16`, you cannot upgrade to `v18`, you need to upgrade to
`v17` first. This is ensured automatically as long as the
[stateVersion](#opt-system.stateVersion) 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 *after* that deploy.
- **`Error: Command "upgrade" is not defined.`**
This error usually occurs if the initial installation
({command}`nextcloud-occ maintenance:install`) has failed. After that, the application
is not installed, but the upgrade is attempted to be executed. Further context can
be found in [NixOS/nixpkgs#111175](https://github.com/NixOS/nixpkgs/issues/111175).
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` and try to fix
the underlying issue.
- If this occurs on an *existing* setup, this is most likely because
the maintenance mode is active. It can be deactivated by running
{command}`nextcloud-occ maintenance:mode --off`. It's advisable though to
check the logs first on why the maintenance mode was activated.
- ::: {.warning}
Only perform the following measures on
*freshly installed instances!*
:::
A re-run of the installer can be forced by *deleting*
{file}`/var/lib/nextcloud/config/config.php`. This is the only time
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/`.
- **Server-side encryption.**
Nextcloud supports [server-side encryption (SSE)](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html).
This is not an end-to-end encryption, but can be used to encrypt files that will be persisted
to external storage such as S3. Please note that this won't work anymore when using OpenSSL 3
for PHP's openssl extension because this is implemented using the legacy cipher RC4.
If [](#opt-system.stateVersion) is *above* `22.05`,
this is disabled by default. To turn it on again and for further information please refer to
[](#opt-services.nextcloud.enableBrokenCiphersForSSE).
## Using an alternative webserver as reverse-proxy (e.g. `httpd`) {#module-services-nextcloud-httpd}
By default, `nginx` is used as reverse-proxy for `nextcloud`.
However, it's possible to use e.g. `httpd` by explicitly disabling
`nginx` using [](#opt-services.nginx.enable) and fixing the
settings `listen.owner` & `listen.group` in the
[corresponding `phpfpm` pool](#opt-services.phpfpm.pools).
An exemplary configuration may look like this:
```
{ config, lib, pkgs, ... }: {
services.nginx.enable = false;
services.nextcloud = {
enable = true;
hostName = "localhost";
/* further, required options */
};
services.phpfpm.pools.nextcloud.settings = {
"listen.owner" = config.services.httpd.user;
"listen.group" = config.services.httpd.group;
};
services.httpd = {
enable = true;
adminAddr = "webmaster@localhost";
extraModules = [ "proxy_fcgi" ];
virtualHosts."localhost" = {
documentRoot = config.services.nextcloud.package;
extraConfig = ''
<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>
'';
};
};
}
```
## Installing Apps and PHP extensions {#installing-apps-php-extensions-nextcloud}
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 [](#opt-services.nextcloud.phpExtraExtensions) setting.
Alternatively, extra apps can also be declared with the [](#opt-services.nextcloud.extraApps) setting.
When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps
that are managed by Nix. If you want automatic updates it is recommended that you use web interface to install apps.
## Maintainer information {#module-services-nextcloud-maintainer-info}
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.
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 `v19.0.0`
should be available in `nixpkgs` as `pkgs.nextcloud19`).
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 `nextcloud`-module should be
updated to make sure that the
[package](#opt-services.nextcloud.package)-option selects the latest version
on fresh setups.
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 should keep those
packages, but mark them as insecure in an expression like this (in
`<nixpkgs/pkgs/servers/nextcloud/default.nix>`):
```
/* ... */
{
nextcloud17 = generic {
version = "17.0.x";
sha256 = "0000000000000000000000000000000000000000000000000000";
eol = true;
};
}
```
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.

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

@ -1146,5 +1146,7 @@ in {
}
]);
# Don't edit the docbook xml directly, edit the md and generate it:
# `pandoc nextcloud.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > nextcloud.xml`
meta.doc = ./nextcloud.xml;
}

502
nixos/modules/services/web-apps/nextcloud.xml
View File

@ -1,229 +1,247 @@
<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 <literal>nextcloud25</literal> which is also the latest
major version available.
</para>
<section xml:id="module-services-nextcloud-basic-usage">
<title>Basic usage</title>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-nextcloud">
<title>Nextcloud</title>
<para>
Nextcloud is a PHP-based application which requires an HTTP server
(<link linkend="opt-services.nextcloud.enable"><literal>services.nextcloud</literal></link>
optionally supports
<link linkend="opt-services.nginx.enable"><literal>services.nginx</literal></link>)
and a database (it's recommended to use
<link linkend="opt-services.postgresql.enable"><literal>services.postgresql</literal></link>).
<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>
A very basic configuration may look like this:
<programlisting>
The current default by NixOS is <literal>nextcloud25</literal> 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
(<link linkend="opt-services.nextcloud.enable"><literal>services.nextcloud</literal></link>
optionally supports
<link linkend="opt-services.nginx.enable"><literal>services.nginx</literal></link>)
and a database (it's recommended to use
<link linkend="opt-services.postgresql.enable"><literal>services.postgresql</literal></link>).
</para>
<para>
A very basic configuration may look like this:
</para>
<programlisting>
{ pkgs, ... }:
{
services.nextcloud = {
enable = true;
hostName = "nextcloud.tld";
hostName = &quot;nextcloud.tld&quot;;
config = {
dbtype = "pgsql";
dbuser = "nextcloud";
dbhost = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself
dbname = "nextcloud";
adminpassFile = "/path/to/admin-pass-file";
adminuser = "root";
dbtype = &quot;pgsql&quot;;
dbuser = &quot;nextcloud&quot;;
dbhost = &quot;/run/postgresql&quot;; # nextcloud will add /.s.PGSQL.5432 by itself
dbname = &quot;nextcloud&quot;;
adminpassFile = &quot;/path/to/admin-pass-file&quot;;
adminuser = &quot;root&quot;;
};
};
services.postgresql = {
enable = true;
ensureDatabases = [ "nextcloud" ];
ensureDatabases = [ &quot;nextcloud&quot; ];
ensureUsers = [
{ name = "nextcloud";
ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES";
{ name = &quot;nextcloud&quot;;
ensurePermissions.&quot;DATABASE nextcloud&quot; = &quot;ALL PRIVILEGES&quot;;
}
];
};
# ensure that postgres is running *before* running the setup
systemd.services."nextcloud-setup" = {
requires = ["postgresql.service"];
after = ["postgresql.service"];
systemd.services.&quot;nextcloud-setup&quot; = {
requires = [&quot;postgresql.service&quot;];
after = [&quot;postgresql.service&quot;];
};
networking.firewall.allowedTCPPorts = [ 80 443 ];
}
</programlisting>
</para>
<para>
The <literal>hostName</literal> option is used internally to configure an HTTP
server using <link xlink:href="https://php-fpm.org/"><literal>PHP-FPM</literal></link>
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
<link xlink:href="http://php.net/manual/en/reserved.variables.server.php"><literal>$_SERVER['HTTP_HOST']</literal></link>)
it's needed to add them to
<link linkend="opt-services.nextcloud.config.extraTrustedDomains"><literal>services.nextcloud.config.extraTrustedDomains</literal></link>.
</para>
<para>
Auto updates for Nextcloud apps can be enabled using
<link linkend="opt-services.nextcloud.autoUpdateApps.enable"><literal>services.nextcloud.autoUpdateApps</literal></link>.
</para>
</section>
<section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
<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.
The <literal>hostName</literal> option is used internally to
configure an HTTP server using
<link xlink:href="https://php-fpm.org/"><literal>PHP-FPM</literal></link>
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>
<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>
<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. E.g., if you're 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.
In case the application serves multiple domains (those are checked
with
<link xlink:href="http://php.net/manual/en/reserved.variables.server.php"><literal>$_SERVER['HTTP_HOST']</literal></link>)
it's needed to add them to
<link linkend="opt-services.nextcloud.config.extraTrustedDomains"><literal>services.nextcloud.config.extraTrustedDomains</literal></link>.
</para>
<para>
Auto updates for Nextcloud apps can be enabled using
<link linkend="opt-services.nextcloud.autoUpdateApps.enable"><literal>services.nextcloud.autoUpdateApps</literal></link>.
</para>
</section>
<section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
<title>Common problems</title>
<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
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>
<listitem>
<para>
<emphasis role="strong">General notes.</emphasis>
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
<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>
<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>
<para>
<emphasis role="strong">Multiple version upgrades.</emphasis>
Nextcloud doesn't allow to move more than one major-version
forward. E.g., if you're 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>
</listitem>
<listitem>
<para>
<emphasis role="strong"><literal>Error: Command &quot;upgrade&quot; is not defined.</literal></emphasis>
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>
<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 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>
<listitem>
<para>
<emphasis role="strong">Server-side encryption.</emphasis>
Nextcloud supports
<link xlink:href="https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html">server-side
encryption (SSE)</link>. This is not an end-to-end encryption,
but can be used to encrypt files that will be persisted to
external storage such as S3. Please note that this won't work
anymore when using OpenSSL 3 for PHP's openssl extension
because this is implemented using the legacy cipher RC4. If
<xref linkend="opt-system.stateVersion"></xref> is
<emphasis>above</emphasis> <literal>22.05</literal>, this is
disabled by default. To turn it on again and for further
information please refer to
<xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE"></xref>.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<formalpara>
<title>Server-side encryption</title>
<para>
Nextcloud supports <link xlink:href="https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html">server-side encryption (SSE)</link>.
This is not an end-to-end encryption, but can be used to encrypt files that will be persisted
to external storage such as S3. Please note that this won't work anymore when using OpenSSL 3
for PHP's openssl extension because this is implemented using the legacy cipher RC4.
If <xref linkend="opt-system.stateVersion" /> is <emphasis>above</emphasis> <literal>22.05</literal>,
this is disabled by default. To turn it on again and for further information please refer to
<xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE" />.
</para>
</formalpara>
</listitem>
</itemizedlist>
</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, <literal>nginx</literal> is used as reverse-proxy for <literal>nextcloud</literal>.
However, it's possible to use e.g. <literal>httpd</literal> by explicitly disabling
<literal>nginx</literal> using <xref linkend="opt-services.nginx.enable" /> and fixing the
settings <literal>listen.owner</literal> &amp; <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>
</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, <literal>nginx</literal> is used as reverse-proxy for
<literal>nextcloud</literal>. However, it's possible to use e.g.
<literal>httpd</literal> by explicitly disabling
<literal>nginx</literal> using
<xref linkend="opt-services.nginx.enable"></xref> and fixing the
settings <literal>listen.owner</literal> &amp;
<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:
</para>
<programlisting>
{ config, lib, pkgs, ... }: {
services.nginx.enable = false;
services.nextcloud = {
enable = true;
hostName = "localhost";
hostName = &quot;localhost&quot;;
/* further, required options */
};
services.phpfpm.pools.nextcloud.settings = {
"listen.owner" = config.services.httpd.user;
"listen.group" = config.services.httpd.group;
&quot;listen.owner&quot; = config.services.httpd.user;
&quot;listen.group&quot; = config.services.httpd.group;
};
services.httpd = {
enable = true;
adminAddr = "webmaster@localhost";
extraModules = [ "proxy_fcgi" ];
virtualHosts."localhost" = {
adminAddr = &quot;webmaster@localhost&quot;;
extraModules = [ &quot;proxy_fcgi&quot; ];
virtualHosts.&quot;localhost&quot; = {
documentRoot = config.services.nextcloud.package;
extraConfig = ''
&lt;Directory "${config.services.nextcloud.package}"&gt;
&lt;FilesMatch "\.php$"&gt;
&lt;If "-f %{REQUEST_FILENAME}"&gt;
SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
&lt;Directory &quot;${config.services.nextcloud.package}&quot;&gt;
&lt;FilesMatch &quot;\.php$&quot;&gt;
&lt;If &quot;-f %{REQUEST_FILENAME}&quot;&gt;
SetHandler &quot;proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/&quot;
&lt;/If&gt;
&lt;/FilesMatch&gt;
&lt;IfModule mod_rewrite.c&gt;
@ -243,69 +261,71 @@
};
}
</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>
<para>
Alternatively, extra apps can also be declared with the <xref linkend="opt-services.nextcloud.extraApps" /> setting.
When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps
that are managed by Nix. If you want automatic updates it is recommended that you use web interface to install apps.
</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 should 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>
</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"></xref>
setting.
</para>
<para>
Alternatively, extra apps can also be declared with the
<xref linkend="opt-services.nextcloud.extraApps"></xref> setting.
When using this setting, apps can no longer be managed statefully
because this can lead to Nextcloud updating apps that are managed
by Nix. If you want automatic updates it is recommended that you
use web interface to install apps.
</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 should keep those packages, but
mark them as insecure in an expression like this (in
<literal>&lt;nixpkgs/pkgs/servers/nextcloud/default.nix&gt;</literal>):
</para>
<programlisting>
/* ... */
{
nextcloud17 = generic {
version = "17.0.x";
sha256 = "0000000000000000000000000000000000000000000000000000";
version = &quot;17.0.x&quot;;
sha256 = &quot;0000000000000000000000000000000000000000000000000000&quot;;
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>
<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>