nixpkgs/nixos/modules/services/web-apps/nextcloud.xml

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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>
    <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 = &quot;nextcloud.tld&quot;;
    config = {
      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 = [ &quot;nextcloud&quot; ];
    ensureUsers = [
     { name = &quot;nextcloud&quot;;
       ensurePermissions.&quot;DATABASE nextcloud&quot; = &quot;ALL PRIVILEGES&quot;;
     }
    ];
  };

  # ensure that postgres is running *before* running the setup
  systemd.services.&quot;nextcloud-setup&quot; = {
    requires = [&quot;postgresql.service&quot;];
    after = [&quot;postgresql.service&quot;];
  };

  networking.firewall.allowedTCPPorts = [ 80 443 ];
}
</programlisting>
    <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>
        <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" /> 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>
      </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:
    </para>
    <programlisting>
{ config, lib, pkgs, ... }: {
  services.nginx.enable = false;
  services.nextcloud = {
    enable = true;
    hostName = &quot;localhost&quot;;

    /* further, required options */
  };
  services.phpfpm.pools.nextcloud.settings = {
    &quot;listen.owner&quot; = config.services.httpd.user;
    &quot;listen.group&quot; = config.services.httpd.group;
  };
  services.httpd = {
    enable = true;
    adminAddr = &quot;webmaster@localhost&quot;;
    extraModules = [ &quot;proxy_fcgi&quot; ];
    virtualHosts.&quot;localhost&quot; = {
      documentRoot = config.services.nextcloud.package;
      extraConfig = ''
        &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;
            RewriteEngine On
            RewriteBase /
            RewriteRule ^index\.php$ - [L]
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteRule . /index.php [L]
          &lt;/IfModule&gt;
          DirectoryIndex index.php
          Require all granted
          Options +FollowSymLinks
        &lt;/Directory&gt;
      '';
    };
  };
}
</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" />
      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>):
    </para>
    <programlisting>
/* ... */
{
  nextcloud17 = generic {
    version = &quot;17.0.x&quot;;
    sha256 = &quot;0000000000000000000000000000000000000000000000000000&quot;;
    eol = true;
  };
}
</programlisting>
    <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>