From 216a95454042ed8bbd87207d59f101215dd15e73 Mon Sep 17 00:00:00 2001 From: Maximilian Bosch Date: Mon, 26 Nov 2018 00:43:45 +0100 Subject: [PATCH] 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). --- nixos/modules/services/web-apps/nextcloud.nix | 2 + nixos/modules/services/web-apps/nextcloud.xml | 99 +++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 nixos/modules/services/web-apps/nextcloud.xml diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix index d0efdf88d73c..ecb1c5615d58 100644 --- a/nixos/modules/services/web-apps/nextcloud.nix +++ b/nixos/modules/services/web-apps/nextcloud.nix @@ -484,4 +484,6 @@ in { }; }) ]); + + meta.doc = ./nextcloud.xml; } diff --git a/nixos/modules/services/web-apps/nextcloud.xml b/nixos/modules/services/web-apps/nextcloud.xml new file mode 100644 index 000000000000..9600d1be7c88 --- /dev/null +++ b/nixos/modules/services/web-apps/nextcloud.xml @@ -0,0 +1,99 @@ + + Nextcloud + + + Nextcloud is an open-source, self-hostable cloud + platform. The server setup can be automated using + services.nextcloud. A desktop client is packaged + at pkgs.nextcloud-client. + + +
+ Basic usage + + Nextcloud is a PHP-based application which requires an HTTP server + (services.nextcloud optionally supports + services.nginx) and a database + (it's recommended to use services.postgresql). + + + A very basic configuration may look like this: +{ pkgs, ... }: +{ + services.nextcloud = { + enable = true; + hostName = "nextcloud.tld"; + nginx.enable = true; + config = { + dbtype = "pgsql"; + dbuser = "nextcloud"; + dbhost = "/tmp"; # nextcloud will add /.s.PGSQL.5432 by itself + dbname = "nextcloud"; + adminpassFile = "/path/to/admin-pass-file"; + adminuser = "root"; + }; + }; + + services.postgresql = { + enable = true; + initialScript = 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"]; + }; + + networking.firewall.allowedTCPPorts = [ 80 443 ]; +} + + + The options hostName and nginx.enable are used internally to configure an + HTTP server using PHP-FPM and nginx. + The config attribute set is used for the config.php which is used + for the application's configuration. + Beware: this isn't entirely pure since the config is modified by the application's runtime! + + + In case the application serves multiple hosts (those are checked with + $_SERVER['HTTP_HOST']) + those can be added using + services.nextcloud.config.extraTrustedDomains. + +
+ +
+ Pitfalls + + 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). + + + Right now changes to the services.nextcloud.config attribute set won't take effect + after the first install + (except services.nextcloud.config.extraTrustedDomains) since the actual configuration + file is generated by the NextCloud installer which also sets up critical parts such as the database + structure. + + + Warning: don't delete 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! + + + The issues are known and reported in #49783, for now it's unfortunately necessary to manually work around these issues. + +
+ +