Nextcloud

Technical documentation

Packaging

Nextcloud is packaged on the ImmaeEu infrastructure in two forms:

  • A « shared » instance, hosted on https://cloud.immae.eu , where people have an individual account on the same Nextcloud instance.

  • An « dedicated » instance, where a user is administrator of a complete instance of Nextcloud and free to manage its users. The user is responsible for the domain name of this instance.

Each instance (the shared one or each of the dedicated ones) is attached to its own php-fpm service. The shared instance is served by the main httpd service, while the dedicated instance are generally served by the production httpd service (depending on the user’s needs)

A module defined in the git repository (systems/eldiron/websites/tools/cloud/farm.nix) permits to easily instantiate a new Nextcloud. The creation of the database and the first configuration remains manual for the moment.

Loading of Nextcloud configuration uses an environment variablr NEXTCLOUD_CONFIG_DIR, pointing to a folder where a file named config.php is searched for. À cela

Loading Nextcloud configuration uses an environment variable NEXTCLOUD_CONFIG_DIR, pointing to a folder in which a file is searched (by default) config.php. To this Nextcloud (see lib/private/Config.php#readData) adds a file search *.config.php. This functionality allows us to have a file config.php that can be written by nextcloud, and files override.config.php pointing to fixed objects managed by nix. Disadvantage: when a configuration is edited in the GUI that impacts this configuration, Nextcloud will rewrite all the variables in config.php all the variables (including additional ones). The information usually contained in the original config.php is version, installed, maintenance and the keys linked to the email mail_*, usually managed by the administrator of the instance in the administration interface. Configuration variables are referenced on the Nextcloud documentation.

New instance

  • Declare the configuration in the git repository, and activate NixOS configuration:

    # (...) nixos-rebuild switch
# Variable used in the next steps
instance=someName

  • Create the database:

    CREATE USER nextcloud_$instance WITH PASSWORD 'somepassword';
CREATE DATABASE nextcloud_$instance WITH OWNER nextcloud_$instance;

  • Copy and adjust an existing configuration.

    • Modify credentials for the database

    • Do not forget to enforce 'appstoreenabled' => false,

  • Start initialization of the instance. It creates automatically an admin user « immae »:

    # This line has never been actually tested since the override.config.php was implemented in nix
nextcloud-occ-$instance maintenance:install --database=pgsql --database-name=nextcloud_$instance --database-host=/run/postgresql --database-user=nextcloud_$instance --admin-user=immae --data-dir=/var/lib/nextcloud_farm/$instance/data

  • Adjust trusted domains in the config.php file

Upgrades

Nextcloud updates must not skip versions. We also need to update to the latest supported subversion before moving on to the next one.

Before updating, make sure that the new version is compatible with the required version of PHP. This information is available in the file lib/versioncheck.php.

Apps (https://apps.nextcloud.com/) must be upgraded together with Nextcloud. They each have a separate derivation (flakes/mypackages/pkgs/webapps/nextcloud/apps). The definition of the app mentions in particular the supported Nextcloud versions, which permits to avoid forgetting some incompatibility in the way.

Nextcloud version is defined in flakes/mypackages/pkgs/webapps/nextcloud/default.nix and declared in flakes/mypackages/pkgs/webapps/default.nix. Once the apps and Nextcloud versions are up to date (see Quick process to update apps derivations for the apps), each instance can be independently upgraded by modifyin the version number associated to it. Apps forgotten in the previous step or unsupported will throw errors at that stage. php version needs to be declared in the definition of the instance.

Before the upgrade, put the instance in maintenance mode, optionally do a backup. After activation, run the upgrade and add missing indexes:

instance=librezo
nextcloud-occ-$instance maintenance:mode --on
sudo -u postgres pg_dump nextcloud_$instance > backup_$instance.sql
# (... Activate NixOS configuration)
nextcloud-occ-$instance upgrade
nextcloud-occ-$instance maintenance:mode --off
nextcloud-occ-$instance db:add-missing-indices

If the instance is back online after that, reiterate with the other version bumps.

Quick process to update apps derivations

  • For each app file, search for relevant (supported) versions on https://apps.nextcloud.com and put a dummy hash.

  • Once they are all declared, compile all the apps at once:

    nix build --keep-going ./flakes/mypackages#webapps-nextcloud_27-all

    fix all the hash mismatch and retry.

Points of attention

Version tracking

Buck tracking

CVE tracking

Access and deletion of data

  • It’s currently not easy in Nextcloud to get all the data associated to a user. In addition to files, we need to identify and extract logs (httpd and nextcloud log file) that concerns the user. All the tables of the database need to be checked too for data stored by apps.

  • User deletion goes through the commmand nextcloud-occ user:delete. This command calls a hook UserDeletedEvent that generates an event indicating to apps that they should delete user’s data. The completeness of this cleaning is thus not garanteed (depends on the app implementation), and a second look in the tables might be necessary to check that all data got deleted. Note that the foreign keys in Nextcloud database are scarce, which doesn’t help to ensure the clean deletion of data. Nextcloud must NOT be in « maintenance » mode during deletion, because apps are not active in that mode