inherit (config.systemd.services.nextcloud-cron.serviceConfig)
        User
        LoadCredential
        KillMode
        ;
    };
  };
}
```

Please note that the options required are subject to change. Please make sure to read the
release notes when upgrading.

## 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.

  - **Issues with file permissions / unsafe path transitions**

    {manpage}`systemd-tmpfiles(8)` makes sure that the paths for

    * configuration (including declarative config)
    * data
    * app store
    * home directory itself (usually `/var/lib/nextcloud`)

    are properly set up. However, `systemd-tmpfiles` will refuse to do so
    if it detects an unsafe path transition, i.e. creating files/directories