Version information
This version is compatible with:
- Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
- Puppet >= 6.0.0 < 9.0.0
- , , , ,
Start using this module
Add this module to your Puppetfile:
mod 'markt-nextcloud', '1.10.0'
Learn more about managing modules with a PuppetfileDocumentation
puppet-nextcloud
Table of Contents
Overview
A Puppet module to install and manage Nextcloud. It is highly configurable, supports Nextcloud apps, automated updates and is suited for multi-server setups.
Requirements
This module should work with all officially supported versions of Nextcloud.
The focus of this module is Nextcloud, so you should ensure that all additional components are available and ready to use:
A MySQL/MariaDB/PostgreSQL database.
A webservice like Apache or Nginx, puppetlabs/apache is recommended.
A supported version of PHP (PHP-FPM is strongly recommended). The module is capable of providing a default installation of PHP, if the optional soft dependency puppet/php is available.
A optional Redis installation can also be enabled, provided that the optional soft dependency puppet/redis is available.
Usage
Basic usage
A small number of parameters are required to setup Nextcloud:
class { 'nextcloud':
admin_password => 'suPeRseCreT',
db_password => 'secRetPasSwOrd',
version => '20.0.4',
}
If the database service is not running on the same server, then the database settings need to be adjusted:
class { 'nextcloud':
db_driver => 'mysql',
db_host => 'db.example.com',
db_name => 'nextcloud_dbname',
db_password => 'secRetPasSwOrd',
db_user => 'nextcloud_dbuser',
...
}
The folder of the Nextcloud installation is derived from three parameters: $installroot
, $symlink_name
and $datadir
. Using different folders is simple:
class { 'nextcloud':
datadir => '/opt/nextcloud-data',
installroot => '/opt',
symlink_name => 'nextcloud',
...
}
In this example the Nextcloud installation will live in /opt/nextcloud
, and this folder should be used as DocumentRoot for the webservice (and/or PHP-FPM). All user-data will be stored in /opt/nextcloud-data
. Note that $datadir
MUST NOT be a subdirectory of the installation folder.
Also note that you MUST NOT change these folders after the initial installation of Nextcloud is complete. This is unsupported and will break your installation. However, you can still manually migrate Nextcloud to different folders if you know what you are doing.
A full list of available parameters is available in REFERENCE.md.
All default values can be found in the data/
directory.
Configuring Nextcloud
All entries in $config
will be added to Nextcloud's configuration:
class { 'nextcloud':
config => {
mail_smtpmode => 'smtp',
mail_smtphost => 'mail.example.com',
mail_smtpport => 25,
memcache.local => '\OC\Memcache\APCu',
memcache.distributed => '\OC\Memcache\Redis',
memcache.locking => '\OC\Memcache\Redis',
overwrite.cli.url => 'https://nextcloud.example.com/',
overwritehost => 'nextcloud.example.com',
trusted_domains => [ 'nextcloud.example.com', 'cloud.example.com' ],
trusted_proxies => [ '10.0.0.1', '10.0.0.2' ],
},
...
}
Every option will be added by using Nextcloud's native config commands. The configuration file will NOT be replaced by this module. This menas that it is still possible to modify Nextcloud's configuration without using Puppet.
Hierarchical settings are also supported:
class { 'nextcloud':
config => {
app_paths => [
{
path => '/opt/nextcloud/apps',
url => '/apps',
writable => false
},
{
path => '/opt/nextcloud-user-apps',
url => '/user-apps',
writable => false
}
],
'redis.cluster' => {
seeds => [
'redis1.example.com:6379',
'redis2.example.com:6379',
'redis3.example.com:6379',
],
timeout => 60,
},
...
},
...
}
In case an option needs to be completely removed from the configuration, add the DELETE:
prefix:
class { 'nextcloud':
config => {
'DELETE:memcache.distributed' => '\OC\Memcache\Redis',
},
...
}
This example would remove the memcache.distributed
option from the configuration.
Note: All settings are added after performing the initial installation of Nextcloud, hence no setting in $config
will have an affect on the installation process.
Managing Apps
Nextcloud apps can be installed, removed, enabled and disabled by using the $apps
parameter:
class { 'nextcloud':
apps => {
calendar => {
ensure => present,
status => disabled,
},
contacts => {
ensure => present,
status => enabled,
},
comments => {
status => disabled,
},
photos => '',
serverinfo => {},
},
...
}
The parameter ensure
specifies whether the app should be present
(installed) or absent
(removed).
The parameter status
specifies whether the app should be disabled
or enabled
.
Both parameters can be ommitted and replaced with an empty string ''
or an empty hash {}
. In this case the default values will be used (present/enabled).
Configuring Apps
Nextcloud apps can be configured using the $app_config
parameter:
class { 'nextcloud':
apps => {
document_community => {
ensure => present,
status => enabled,
},
onlyoffice => {
ensure => present,
status => enabled,
},
},
app_config => {
onlyoffice => {
DocumentServerUrl => "https://${$facts['fqdn']}/index.php/apps/documentserver_community/",
verify_peer_off: 'true',
},
},
}
The app name should be the key in the hash and any configuration parameters for that app should be key/value pairs within.
Performing Updates
The module will automatically perform updates of Nextcloud when the value of $version
is changed. An optional post-update command can be specified, which will be executed as root:
class { 'nextcloud':
update_enabled => true,
post_update_cmd => 'systemctl restart php-fpm',
...
}
Note that the post-update command will run on all servers (up to 30 minutes after the update was installed).
Nextcloud's native upgrade command will also be utilized, but depending on the size of the installation, it may be required to increase the value of $command_timeout
. The use of the native upgrade command and the post-update command may be disabled by setting $update_enabled
to false
, which will allow to perform these steps manually at any time. Note that this does NOT prevent the automatic update, it will only skip the native upgrade and post-update commands. To completely disable all updates, the parameter $update_enabled
must be set to none
.
The old installation folder will be preserved. In theory, it should be possible to revert to the previous version if no incompatible (database) change was involved. The official Nextcloud documentation should provide more details.
However, it must be ensured that the upgrade path is supported by Nextcloud prior to attempting an update. Besides that performing a full backup periodically is strongly advised.
Multiple Servers
When using more than one server for the same Nextcloud instance, the following parameter should be set to improve overall stability:
class { 'nextcloud':
update_enabled => true,
update_host => 'main-host-fqdn.example.com',
...
}
This ensures that all critical operations are only performed on the specified host.
High Performance Backend
The module supports Nextcloud's High Performance Backend that was introduced in Nextcloud 21. To let the module install the "notify_push" app and manage this service, set $manage_hpb
to true
.
Keep in mind that you have to manually configure your webserver or reverse proxy to actually use the High Performance Backend. In case of Apache HTTPD, just add the following lines to the block used for the Nextcloud server:
ProxyPass /push/ws ws://127.0.0.1:7867/ws
ProxyPass /push/ http://127.0.0.1:7867/
ProxyPassReverse /push/ http://127.0.0.1:7867/
High Availability
The module supports highly available setups where multiple servers are used.
In this case the Nextcloud installation and data directory must be stored on a shared storage like NFS. It is crucial that all servers share these folders. Besides that a highly available instance of Redis should be used as memcache to avoid lock/session contention.
All installation and update tasks of this module use lock files to prevent concurrent execution on multiple servers.
Directory structure
When using the module with default options...
class { 'nextcloud':
datadir => '/opt/nextcloud-data',
installroot => '/opt',
symlink_name => 'nextcloud',
version => '20.0.4',
}
...the directory structure will look like this:
/
|-- opt/
| |-- nextcloud@ # symlink to the current install dir (nextcloud-20.0.4)
| |-- nextcloud-20.0.3 # install dir for a previous version (will not be purged)
| |-- nextcloud-20.0.4 # install dir for the current version
| | |-- nextcloud # default application folder (extracted from dist archive)
| | |-- config
| | |-- config.php@ # symlink to the real config.php in Nextcloud's data dir
| |-- nextcloud-data # Nextcloud's data directory
| |-- .config.php # real config.php (hidden file)
| |-- .puppet_app.lock # indicates that Puppet is currently running a app management command
| |-- .puppet_convert_filecache.done # indicates that Puppet completed the "convert filecache" command
| |-- .puppet_dist_initial_install.done # indicates that the initial install of Nextcloud is done
| |-- .puppet_missing_indices.done # indicates that Puppet completed the "missing indices" command
| |-- .puppet_update_20.0.3.done # indicates that an update to version 20.0.3 was performed
| |-- .puppet_update_20.0.4.done # indicates that an update to version 20.0.4 was performed
|-- var/
| |-- db/
| |-- nextcloud_data # contains the path to Nextcloud's data dir (used by custom fact)
| |-- nextcloud_home # contains the path to Nextcloud's install/home dir (used by custom fact)
In this example, Nextcloud was initially installed with version 20.0.3 and later updated to version 20.0.4.
The suffix .done
indicates that this file is used by the module to identify completed jobs.
The suffix .lock
indicates that this file is used by the module to identify currently running jobs.
All files that are prefixed with .puppet_
are required for proper operation of this module and must not be removed.
Reference
Classes and parameters are documented in REFERENCE.md.
Development
Contributing
Please use the GitHub issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.
Acknowledgement
This module was heavily inspired by adullact/nextcloud, which was written by Fabien Combernous. Many features would not be available without his hard work.
License
Copyright 2020 Frank Wall
Reference
Table of Contents
Classes
Public Classes
nextcloud
: Install and manage Nextcloud
Private Classes
nextcloud::app_config
: Set configuration options for Nextcloud appsnextcloud::apps
: Manage Nextcloud appsnextcloud::config
: Set configuration options for Nextcloudnextcloud::cron
: Configure background cron jobs for Nextcloudnextcloud::hpb
: Configure Nextcloud's High Performance Back-end (HPB)nextcloud::install
: Download and extract the distribution archivenextcloud::pre_install
: Pre installation tasksnextcloud::update
: Perform required tasks to update Nextcloud
Defined types
nextcloud::app_command
: Run a command for a Nextcloud appnextcloud::config_command
: Set or remove a single configuration valuenextcloud::install::distribution
: Download and extract the distribution archive
Functions
nextcloud::create_config_resources
: Create nextcloud::config_command resources from a nested hash (e.g. from hiera)
Classes
nextcloud
Install and manage Nextcloud
Parameters
The following parameters are available in the nextcloud
class.
admin_password
Data type: String
Specifies the initial password for the Nextcloud admin user.
admin_user
Data type: String
Specifies the username for the Nextcloud admin.
apps
Data type: Hash
Specifies a list of Nextcloud apps and their desired state.
app_config
Data type: Hash
A hash containing configuration options for Nextcloud apps. The hash should be in the format: { 'my_app_name' => { 'setting1' => 'xyz123', 'setting2' => 'blah', }, }
command_timeout
Data type: Integer
Specifies the time to wait for install/update/maintenance commands to complete. Keep in mind that several commands may take a few hours to complete, depending on the size of your installation.
config
Data type: Hash
A hash containing configuration options for Nextcloud.
cronjobs
Data type: Hash
Specifies a list of cron jobs that should be added when
$manage_cron
is enabled.
datadir
Data type: Stdlib::Compat::Absolute_path
Specifies the directory where Nextcloud will store user data. It MUST reside outside of Nextcloud's installation directory.
datastatefile
Data type: Stdlib::Compat::Absolute_path
A file that is required by the module to work properly. This value MUST NOT be changed, because the path is hardcoded in several places.
date_expression
Data type: String
A date command that will be used when checking if $post_update_cmd
should be executed.
db_driver
Data type: String
The database driver that Nextcloud should use.
db_host
Data type: String
The database host that Nextcloud should use.
db_name
Data type: String
The database name that Nextcloud should use.
db_password
Data type: String
The database password that Nextcloud should use.
db_user
Data type: String
The database user that Nextcloud should use.
debug
Data type: Boolean
Whether to enable additional output for debugging purposes.
hpb_app
Data type: String
Specifies the name of the HPB app to be installed.
hpb_binary
Data type: String
Specifies the relative path to the binary of the HPB app.
hpb_pidfile
Data type: Stdlib::Compat::Absolute_path
Specifies the PID file for the HPB service.
hpb_port
Data type: Integer
Specifies the port for the HPB service.
hpb_service_config_file
Data type: Stdlib::Compat::Absolute_path
Specifies the full path to the HPB service config file.
hpb_service_ensure
Data type: Enum['running', 'stopped']
Specifies the desired state of the HPB service.
hpb_service_file
Data type: Stdlib::Compat::Absolute_path
Specifies the full path to the HPB service definition / startup script.
hpb_service_mode
Data type: String
Specifies the file mode for the HPB service definition / startup script.
hpb_service_name
Data type: String
Specifies the name for the HPB service.
install_enabled
Data type: Boolean
Whether to download and extract the release distribution files, switch the symlink to the specified release. On new installs it also runs the required PHP commands to install Nextcloud. When disabled these commands need to be run manually and some features may not work as expected (not recommended).
installroot
Data type: Stdlib::Compat::Absolute_path
Specifies the base directory where Nextcloud should be installed. A new subdirectory for each version will be created.
manage_apps
Data type: Boolean
Whether to manage Nextcloud apps. They can be installed, removed, enabled or disabled.
manage_cron
Data type: Boolean
Whether to manage Nextcloud's background cron job(s).
manage_hpb
Data type: Boolean
Whehter to manage Nextcloud's notify_push app, the High Performance Back-end (HPB).
manage_php
Data type: Boolean
Whether to setup and maintain PHP (FPM/CLI) and install modules needed for Nextcloud.
manage_redis
Data type: Boolean
Whether to setup and maintain a local Redis server.
manage_symlink
Data type: Boolean
Whether to maintain a symlink for the current version of Nextcloud. This must be enabled for the module to work as expected.
mirror
Data type: Variant[Stdlib::HTTPUrl,Stdlib::HTTPSUrl]
Specifies the base URL where the distribution archive can be downloaded.
path
Data type: String
Specifies the content of the PATH environment variable when running commands.
php_extensions
Data type: Hash
Specifies a list of PHP extensions that should be installed when
$manage_php
is enabled.
post_update_cmd
Data type: String
An optional command that should be executed after performing an update.
service_provider
Data type: Enum['rc', 'systemd']
The operating system's service manager.
stat_expression
Data type: String
A stat command that will be used when checking if $post_update_cmd
should be executed.
statefile
Data type: Stdlib::Compat::Absolute_path
A file that is required by the module to work properly. This value MUST NOT be changed, because the path is hardcoded in several places.
symlink_name
Data type: String
Specifies the name of the symlink. This is considered to represent Nextcloud's home directory. It should be used as DocumentRoot and MUST NOT be changed after completing the Nextcloud installation.
system_group
Data type: String
Specifies the name of the group that is used by the webserver and/or PHP FPM. It will be used to set proper file permission for Nextcloud.
system_user
Data type: String
Specifies the name of the user that is used by the webserver and/or PHP FPM. It will be used as owner for the Nextcloud installation files and it will be used to run optional commands.
update_enabled
Data type: Variant[Boolean, Enum['none']]
Whether to run the required PHP commands to update Nextcloud. When disabled,
these commands need to be run manually and some features may not work as
expected. Note that this does NOT prevent the module from switching the
installation directory to a newer version, it just skips the execution of
Nextcloud's update commands. To completely disable all updates, the parameter
should be set to none
(not recommended).
update_host
Data type: Optional[String]
Optional parameter to specify the FQDN of the host where all critical operations should be performed. This includes operations such as the initial installation, update installations, config commands and all app commands. Limiting these operations to a single host should prevent race conditions.
Default value: undef
version
Data type: String
Specifies the version of Nextcloud that should be installed.
Defined types
nextcloud::app_command
Run a command for a Nextcloud app
Parameters
The following parameters are available in the nextcloud::app_command
defined type.
app
Data type: String
The name of the app.
Default value: $title
command
Data type: Enum['install','remove','enable','disable','install_disable','post_update']
The app command that should be executed.
nextcloud::config_command
Set or remove a single configuration value
Parameters
The following parameters are available in the nextcloud::config_command
defined type.
key
Data type: Variant[Boolean, Integer, String]
The configuration key that should be altered. If prefixed with DELETE:
then the key will be completely removed from configuration.
Default value: $title
section
Data type: Enum['app', 'system']
Specifies whether it is a system or app configuration value.
Default value: 'system'
value
Data type: Variant[Boolean, Integer, String]
The configuration value that should be set.
verify_key
Data type: Variant[Boolean, Integer, String]
The configuration key to find out whether it needs to be altered.
verify_value
Data type: Variant[Boolean, Integer, String]
The configuration verify to find out whether it needs to be altered.
nextcloud::install::distribution
Download and extract the distribution archive
Parameters
The following parameters are available in the nextcloud::install::distribution
defined type.
id
Data type: Optional[String]
An optional identifier that can be used to prevent the archive job from being executed multiple times by remembering its state. This is most useful to distinguish between an initial install and an update.
Default value: undef
Functions
nextcloud::create_config_resources
Type: Puppet Language
Create nextcloud::config_command resources from a nested hash, suitable for conveniently loading values from hiera. The key-value pairs from the hash represent config keys and values passed to nextcloud::config_command for simple values, Hash and Array values recursively # create nested sections.
nextcloud::create_config_resources(Hash[String, NotUndef] $config_hash, Array[String] $sections = [])
Create nextcloud::config_command resources from a nested hash, suitable for conveniently loading values from hiera. The key-value pairs from the hash represent config keys and values passed to nextcloud::config_command for simple values, Hash and Array values recursively # create nested sections.
Returns: Any
config_hash
Data type: Hash[String, NotUndef]
A hash of (non-hierarchical) key names mapped to values.
sections
Data type: Array[String]
The section names of the hierarchical key, will usually only be specified on recursive calls from within this function itself.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
v1.10.0 - 2023-08-01
Changed
- Update module dependencies
Fixed
- Parameter
$install_enabled
is ignored (treated as always true) (#11)
v1.9.0 - 2023-07-25
Changed
- Update module dependencies and OS support
- Update PDK to 3.0
Fixed
- Fix GitHub Actions
- Fix compatibility with puppetlabs/stdlib v9.0.0
v1.8.3 - 2022-11-05
Changed
- Run all config commands on the specified host when
$update_host
is set
v1.8.2 - 2022-11-05
Changed
- Run all app commands on the specified host when
$update_host
is set
v1.8.1 - 2022-11-05
Changed
- Change working directory for post update commands to the symlink
Fixed
- Fix error running post update commands on other hosts when
$update_host
is specified
v1.8.0 - 2022-11-05
Added
- Add new parameter
$update_host
- Add documentation for all parameters
Changed
- Only extract the Nextcloud tarball when
$install_enabled
is set totrue
Fixed
- Post update command was not run if
$update_enabled
was set tofalse
v1.7.0 - 2022-09-21
Changed
- Update OS versions and Puppet versions
- Update PDK from 1.8.0 to 2.5.0
- Fix puppet-lint offenses
v1.6.0 - 2021-03-29
Added
- Add support for Nextcloud's High Performance Backend (notify_push) (#5)
Fixed
- Do not convert boolean config values to strings when passing them to occ
v1.5.0 - 2021-02-26
Added
- Add optional post-update command
v1.4.0 - 2021-02-23
Added
- Add support for hierarchical settings (#1)
Fixed
- Properly escape passwords in shell commands (#4)
v1.3.0 - 2021-01-25
Added
- Add ability to configure Nextcloud apps (#3)
v1.2.0 - 2021-01-20
Changed
- Make the default cron job silent
v1.1.0 - 2021-01-10
This release fixes bugs that caused updates to fail.
Added
- Add custom fact
nextcloud_dist_jobs
, internally used bynextcloud::install::distribution
- Add custom fact
nextcloud_updates
, it lists all completed Nextcloud updates
Changed
- Reinstall all 3rd-party apps after performing an update of Nextcloud
- Show a client-side warning if app management was forcefully disabled
- Document folder structure
Fixed
- Fix updates by changing the workflow in
nextcloud::install::distribution
- Fix missing 3rd-party apps after performing an update of Nextcloud
- Fix execution of
occ db:convert-filecache-bigint
on initial install
v1.0.0 - 2021-01-01
Initial release
Dependencies
- puppet/archive (>= 6.0.0 < 8.0.0)
- puppetlabs/cron_core (>= 1.1.0 < 2.0.0)
- puppetlabs/stdlib (>= 7.0.0 < 10.0.0)