cdist-contrib/type/__nextcloud/man.rst

cdist-type__nextcloud(7)
========================

NAME
----
cdist-type__nextcloud - Installs and manages a nextcloud instance


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


REQUIRED PARAMETERS
-------------------
version
    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
    <https://nextcloud.com/changelog/>`_ or from the `GitHub Releases
    <https://github.com/nextcloud/server/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.

admin-password
    The administrator password to access the nextcloud instance. Must be given
    in plain text. This parameter has no effect if nextcloud will not be
    installed.


OPTIONAL PARAMETERS
-------------------
mode
    Sets the unix file mode of the nextcloud directory. This is not inherited
    to child files or folders. Defaults to `755`.

user
    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
    parameter!**

group
    The group all files and folders of the nextcloud installation should have.
    Defaults to `www-data`. Should be changed with ``--user``.


BOOLEAN PARAMETERS
------------------
install-only
    Skips all nextcloud upgrades done by this type. Should be used when
    nextcloud upgrades are (*exclusively*) done via the built-in updater.


NEXTCLOUD CONFIG PARAMETERS
---------------------------
host
    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.

admin-user
    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.

admin-email
    The email address of the administrative user. This parameter has no effect
    if nextcloud will not be installed.

data-directory
    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.

database-type
    Sets the type of database that should be used as backend. Possible backends
    are:

    SQLite
        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.*

    MariaDB
        Use ``mysql`` as value. MariaDB and MySQL are threated the same
        way. They are the recommended database backends recommended from
        upstream.

    PostgreSQL
        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.**

database-host
    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.

database-name
    The name of the database to connect to. Required if MariaDB or PostgreSQL
    is used.

database-user
    The username to access the database. Required if MariaDB or PostgreSQL is
    used.

database-password
    The password required to authorize the given user. Required if MariaDB or
    PostgreSQL is used.

database-prefix
    The table prefix used by nextcloud. If nothing set, nextcloud defaults to
    ``oc_``.


MESSAGES
--------
installed
    Nextcloud was successfully installed.

upgraded $old to $new
    The nextcloud version was upgraded from `$old` to `$new`.

configured
    Nextcloud configuration was changed.


ABORTS
------
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*.


EXAMPLES
--------

.. 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 mycloud.example.com

  # more extensive configuration
  __nextcloud /var/www/cloud --version 20.0.0 --admin-password "iaminsecure" \
        --host localhost --host nextcloud --host 192.168.1.67 \
        --data-directory /var/lib/nextcloud/what \
        --database-type mysql --database-host "localhost" --database-name "nextcloud" \
        --database-user "test" --database-password "not-a-good-password"


NOTES
-----
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
  <https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html>`_

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.


SEE ALSO
--------
`Nextcloud documentation <https://docs.nextcloud.com/server/latest/admin_manual/index.html>`_

:strong:`cdist-type__nextcloud_user`\ (7)


AUTHORS
-------
Matthias Stecher <matthiasstecher at gmx.de>


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