295 lines
12 KiB

cdist-type__nextcloud - Installs and manages a nextcloud instance
This type installs, upgrades and configure a nextcloud instance. The object
id is the absolute path for the installation directory. Nextcloud will be
installed unter that directory.
The version that should be installed. If it is already installed and the
installed version lower, it will upgrade nextcloud if ``--install-only`` is
not set.
You get version numbers from the `official changelog
<>`_ or from the `GitHub Releases
<>`_ page. The type will
download the tarball over the official nextcloud website.
The type will never downgrade a nextcloud instance. Rather, it will fail,
as this is a missconfiguration. Downgrades are not recommended and
supported by upstream. Such cases can happen if the nextcloud instance was
upgraded via the built-in nextcloud installer. In such cases, it is
recommended to use the ``--install-only`` option.
The administrator password to access the nextcloud instance. Must be given
in plain text. This parameter has no effect if nextcloud will not be
Sets the unix file mode of the nextcloud directory. This is not inherited
to child files or folders. Defaults to `755`.
The user which owns the complete nextcloud directory. The php application
should be executed with this user. All nextcloud commands will be executed
with this user. This type will not create the unix user.
The type assumes the default `www-data` user, which is common on Debian
systems. **If you change this option, please do the same with the group
The group all files and folders of the nextcloud installation should have.
Defaults to `www-data`. Should be changed with ``--user``.
Skips all nextcloud upgrades done by this type. Should be used when
nextcloud upgrades are (*exclusively*) done via the built-in updater.
All hostnames where the the users can log into nextcloud. If you access
nextcloud via a hostname not given to this list, the access fails. This
parameter can be set multiple times.
The username of the administrative user which will be created while the
installation. If not set, nextcloud defaults to "admin". This parameter has
no effect if nextcloud will not be installed.
The email address of the administrative user. This parameter has no effect
if nextcloud will not be installed.
This will set or change the data directory where nextcloud will keep all
its data, including the SQLite database if any. By default, it will be
saved in the ``data`` directory below the nextcloud directory.
If this directory change, this type will move the old location to the new
one to preserve all data. This is not supported by upstream, as some apps
may not handle this.
Sets the type of database that should be used as backend. Possible backends
Use ``sqlite3`` as value. Saves everything in a database file
stored in the data directory. It is only recommended for very small
installations or test environments from upstream.
*All further database options are ignored if SQLite is selected as
database backend.*
Use ``mysql`` as value. MariaDB and MySQL are threated the same
way. They are the recommended database backends recommended from
Use ``pgsql`` as value.
**This parameter defaults to the SQLite database backend, as it is the
simplest one to setup and do not require extra parameters.**
If this parameter change, the type will migrate to the new database type.
It will not work for SQLite because the upstream migration script does not
support it. **Be aware that migrations take there time, plan at minimum
40 seconds of migration for a stock installation.**
The database host to connect to. Possible are hostnames, ip addresses or
UNIX sockets. UNIX sockets must set in the format of
``localhost:/path/to/socket``. If an non-standard port is used, set it
after the hostname or ip address seperated by an colon (``:``). If this
value is not set, nextcloud defaults to the value ``localhost``.
This type will not migrate data if the type does not change. You must do
this manually by setting the maintainer mode (to avoid data changes) and
then cloning the database to the new destination. After that, run cdist to
apply the config changes. It should automaticly remove the maintainer mode.
The name of the database to connect to. Required if MariaDB or PostgreSQL
is used.
The username to access the database. Required if MariaDB or PostgreSQL is
The password required to authorize the given user. Required if MariaDB or
PostgreSQL is used.
The table prefix used by nextcloud. If nothing set, nextcloud defaults to
Nextcloud was successfully installed.
upgraded $old to $new
The nextcloud version was upgraded from `$old` to `$new`.
Nextcloud configuration was changed.
Aborts in the following cases:
The current installed version is greather than the version that should be
installed. See the parameter description of `--version` for detailed
information. The problem can be fixed by bumping the version value to at least
the version that is currently installed or use the parameter `--install-only`.
It may abort if the data directory can not be moved correctly. Then, the
nextcloud configuration is broken and must be resolved manually: Move the data
directory to the correct location or change the configuration to point to the
old destination and retry.
It aborts if it should migrate to a SQLite database. This will be done before
the upstream migration script is executed, as it would throw the same error.
The explorers will abort if they found a valid nextcloud installation, but no
installed `php`. Currently, this is intended behaviour, because it can not
safely get the current nextcloud version, also do not get the nextcloud
configuration. For more information, see the *NOTES section*.
.. code-block:: sh
# minimal nextcloud installation with sqlite and other defaults
# please only use sqlite for minimal or test installations as recommend :)
__nextcloud /var/www/html/nextcloud --version 20.0.0 \
--admin-password "iaminsecure" \
--host localhost --host nextcloud
# installation under the webroot
__nextcloud /var/www/html/ --version 20.0.0
--admin-password "notthatsecure" --host
# more extensive configuration
__nextcloud /var/www/cloud --version 20.0.0 --admin-password "iaminsecure" \
--host localhost --host nextcloud --host \
--data-directory /var/lib/nextcloud/what \
--database-type mysql --database-host "localhost" --database-name "nextcloud" \
--database-user "test" --database-password "not-a-good-password"
This cdist type does not cover all configuration options that nextcloud offer.
If you need more configuration options for nextcloud, you are welcome to extend
this type and contribute it upstream!
- `Nextcloud configuration reference
Currently, the state of this object is always `present`. So it will always be
installed without the option to uninstall it again (`absent`). This was done
because it will not be a common demand to uninstall nextcloud again. If you
need to toggle the state, you are welcome to contirbute!
Parameters given for the admin user which will be set up at installation time
(`--admin-*` ones) are not applied if nextcloud will not be installed.
Therefor, parameter changes are not applied to the installation. Currently not
implemented - but possible - is to use the type
:strong:`cdist-type__nextcloud_user`\ (7) to do all the later work.
Database migration is only partly supported if the database will be changed to
``mysql`` or ``pgsql``, because it is supported by an upstream script. You are
welcome to extend this type for database migrations between the same database
type. For an implementation, you may use shell utilites like ``mysqldump(1)``
(be aware that this may not already be installed) or use the already installed
php code to migrate.
The type will abort if a valid nextcloud directory already exists in the
explorer execution, but no `php` exists to explore the setup. Therefor, the
manifest could not install `php` yet. This is not the case for a new
installation, as there does not exist a nextcloud directory with a valid
structure. While some code could be skipped and the other replaced with `awk`
with something like
``awk '$1 == "$OC_VersionString" {gsub(/['\'';]/, "", $3); print $3}' version.php``,
it is not handled for the following cases:
1. This case should not happen very often.
2. Maybe because of ``libapache2-mod-php`` or ``php-fpm``, `php` already
exists for the cli.
3. While the `awk` replacement for the version is just a bit worser, it would
bring stable results, while it would be more difficult to dump out the
configuration without custom `php` or the help from ``php occ``. Therefor,
it would make false assumptions like it want to install nextcloud again,
do not delete configuration options and set all available nextcloud options
that are available through this type.
If the nextcloud installation does not work and you stuck in a plaintext error
screen, try to restart your Apache WWW server first! This type will install all
php dependencies, but there are not recognised by the server-internal php
environment. This can happen after a database migration between different
database types, as it installs the database module only when it is required.
If the tarball needs to be downloaded, it will be directly downloaded into the
directory ``/tmp`` and will be unpacked to the destination for an installation
or to the same directory but prefixed with a dot for an update. It will
download it into the temp directory because it does not find a better location.
In legacy, it was downloaded to the parent directory, but this may not the best
location as the installation dir can be everywhere.
This type does not garantee to always show the maintenance mode screen because
nextcloud does not show it in every case:
1. For fresh installations, the maintenance mode can not be set.
2. While upgrades starting at version 20, the user is promted to execute the
update manually via the webinterface instead of the maintenance screen.
It is recommended to show an own maintanance screen via the webserver if this
is critical for you.
`Nextcloud documentation <>`_
:strong:`cdist-type__nextcloud_user`\ (7)
Matthias Stecher <matthiasstecher at>
Copyright \(C) 2020 Matthias Stecher. You can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.