Etherpad module for Puppet

Overview
Module Description - What the module does and why it is useful
Setup - The basics of getting started with etherpad
Usage - Configuration options and additional functionality
Reference - An under-the-hood peek at what the module is doing and how
Limitations - OS compatibility, etc.
Development - Guide for contributing to the module

Overview

This module installs and configures etherpad(-lite). It's inspired by existing etherpad modules on the Forge, but attempts to "do it right™".

Setup

What etherpad affects

This module depends on puppet-nodejs
It also depends on puppetlabs-vcsrepo, and hence git
It will setup a service using the system's preferred init
When running installDeps.sh, this module requires all the usual build tools, development packages and headers as any other (complex) npm install
When running on ubuntu OS, it will setup apt sources for nodejs with puppetlabs-apt.

Setup Requirements

This module requires a database. With no database available, it will use DirtyDB as fallback. This is not intended for production use.

For a migration from DirtyDB, please consult this blog post

On Ubuntu system, as soft dependency, you will need to ensure that puppetlabs-apt version 4.4.0 or above is installed.

Beginning with etherpad

Before to installation, a target database should exist. Please consult the documentation of puppetlabs-postgresql, or puppetlabs-mysql for how to create those.

Usage

The basic usage is:

include etherpad

note that this will use the local DirtyDB and is not recommended beyond basic testing. For production setups, use:

class { 'etherpad':
  ensure            => 'present',
  database_type     => 'mysql',
  database_name     => 'etherpad',
  database_user     => 'etherpad',
  database_password => '37h3rp4d',
  users             => {
    admin => {
      password => 's3cr3t',
      is_admin => true,
    },
    user  => {
      password => 'secret',
      is_admin => false,
    },
  },
}

Reference

etherpad

The etherpad module installs and configures etherpad. This class is the entry point for the module and the configuration point.

ensure

Ensure the presence (present, latest) or absence (absent) of etherpad. This can also be set to a specific version (or SHA1 hash). By default, we install from the branch develop, in order to cater for newer versions of Nodejs. absent will completely remove the software, its dependencies, and the users and groups.

Type	Default
String	`present`

service_name

Name under which the service will be known.

Type	Default
String	`etherpad`

service_ensure

Ensure whether the service is running or stopped. If you're passing absent to ensure, please also pass stopped to service_ensure.

Type	Default
Enum['running', 'stopped']	`running`

service_provider

Which service provider to use. By default this is taken from stdlib's $::service_provider fact. Currently only upstart and systemd are supported!

Type	Default
Optional[String]	`$::service_provider`

manage_user

Whether to manage the user & group under which etherpad will be running.

Type	Default
Boolean	`true`

manage_abiword

Whether to manage the dependency of the abiword package.

Type	Default
Boolean	`false`

abiword_path

Absolute Path to the abiword binary.

Type	Default
String	`/usr/bin/abiword`

abiword_path

Absolute Path to the abiword binary.

Type	Default
String	`/usr/bin/abiword`

user & group

The user and group under which etherpad will be running.

Type	Default
String	`etherpad`

root_dir

Absolute Path of the etherpad installation.

Type	Default
String	`/opt/etherpad`

source

URL to the git source of etherpad.

Type	Default
String	'https://github.com/ether/etherpad-lite.git'

database_type

The type of database that etherpad should use. In case of mysql or postgres, you'll also have to set the options below.

Type	Default
Enum[`dirty`, `mysql`, `sqlite`, `postgres`]	`dirty`

database_host

Host on which the database is running.

Type	Default
String	`localhost`

database_user

User (or role) to use, when connecting to the database.

Type	Default
String	`etherpad`

database_name

Name of database to connect to.

Type	Default
String	`etherpad`

database_password

Password to use when connecting to database.

Type	Default
String	`etherpad`

ip

IP on which etherpad will be listening. The default, undef, turns into null, and hence NodeJS' default of "all interfaces".

Type	Default
String	`undef`

port

Port on which etherpad will be listening.

Type	Default
Integer	`9001`

trust_proxy

This value should be set if etherpad is running behind a proxy.

Type	Default
Boolean	`false`

max_age

How long clients may use served JavaScript code (in seconds).

Type	Default
Integer	21600

minify

Whether to minify the delivered JavaScript and CSS.

Type	Default
Boolean	`true`

require_session

Users must have a session to access pads. This effectively allows only group pads to be accessed.

Type	Default
Boolean	`false`

edit_only

Users may edit pads but not create new ones. Pad creation is only via the API. This applies both to group pads and regular pads.

Type	Default
Boolean	`false`

require_authentication

This setting is used if you require authentication of all users.

Note: /admin always requires authentication.

Type	Default
Boolean	`false`

require_authorization

Require authorization by a module, or a user with is_admin set, see below.

Type	Default
Boolean	`false`

use_default_ldapauth

Merge default ldapauth options to final config of ep_ldapauth plugin. If set to 'false' it can be used to omit default searchDN and searchPWD for anonymous ldap access.

Type	Default
Boolean	`true`

plugins_list

Manage etherpad's plugins.

Type	Default
Hash[Pattern['ep_*'], Variant[Boolean, Undef]]	{}

Existing two kinds of plugins:

Simple plugins : Supported plugins that does not modify settings.json.
Advanced plugins : Supported plugins that accept configuration parameters in settings.json.

Keys in plugins_list must be default plugins name.

Values in plugins_list can be:

undef: Install any simple plugins or advanced plugins with its default configuration.
true : Install advanced plugins with provided configuration by class attributs. See beelow detailed section about each plugin.
false: Uninstall any plugins.

List of all plugins is avalable at https://static.etherpad.org/plugins.html

Plugin name	Supported
`ep_button_link`	YES
`ep_ldapauth`	YES
`ep_mypads`	YES
All simple plugins	YES

If the plugin is not supported, it will be installed but whitout configuration.

Examples :

class { 'etherpad':
  ensure            => 'present',
  database_type     => 'mysql',
  database_name     => 'etherpad',
  database_user     => 'etherpad',
  database_password => '37h3rp4d',
  users             => {
    admin => {
      password => 's3cr3t',
      is_admin => true,
    },
    user  => {
      password => 'secret',
      is_admin => false,
    },
  },
  plugins_list => {
    ep_button_link => true,
    ep_align       => undef,
    ep_ldapauth    => false,
  },
}

In this case ep_button_link will be installed with the configuration in settings.json, ep_align will be just installed and ep_ldapauth will be uninstalled.

class { 'etherpad':
  ensure               => 'present',
  database_type        => 'mysql',
  database_name        => 'etherpad',
  database_user        => 'etherpad',
  database_password    => '37h3rp4d',
  plugins_list         => {
    ep_button_link => true,
    ep_align       => undef,
    ep_mypads      => true,
  },
  mypads               => {
    searchBase      =>  'cn=users,cn=accounts,dc=example,dc=com',
    url             =>  'ldaps://ipa.example.com:636',
    bindDN          =>  'uid=binduser,cn=sysaccounts,cn=etc,dc=example,dc=com',
    bindCredentials =>  'bindpassword',
    searchFilter    =>  '(memberOf=cn=etherpad_users,cn=groups,cn=accounts,dc=example,dc=com)'
  },
  ep_local_admin_login => 'my_ep_adminuser',
  ep_local_admin_pwd   => 'my_ep_adminsecret',
}

In this case ep_button_link and ep_mypads will be installed with some configurations in settings.json, ep_align will be just installed without configuration.

button_link

Manage the configuration of ep_button_link.

Type	Default
Type	'https://www.npmjs.com/package/ep_button_link'

ldapauth

Manage the configuration of ep_ldapauth.

Type	Default
Type	'https://www.npmjs.com/package/ep_ldapauth'

mypads

Manage the configuration of ep_mypads.

Type	Default
Type	'https://www.npmjs.com/package/ep_mypads' or 'https://git.framasoft.org/framasoft/Etherpad/ep_mypads/wikis/use-ldap-authentication'

pad_title

Name of your instance

Type	Default
Optional[String]	`undef`

default_pad_text

The default text of a pad.

Type	Default
String	`Welcome to etherpad!`

logconfig_file

Enable/disable logging to a file.

Type	Default
Boolean	`false`

logconfig_file_filename

Specify the file to log to, if logconfig_file is enabled.

Type	Default
Optional[String]	`undef`

logconfig_file_max_log_size

The maximum logfile size (megabytes) before rotating the log file.

Type	Default
Optional[Integer]	`undef`

logconfig_file_backups

The number of logfiles to keep after rotation.

Type	Default
Optional[Integer]	`undef`

logconfig_file_category

Only log a specific category.

Type	Default
Optional[String]	`undef`

users

Configure users in settings.json. If both 'users' and 'ldapauth' are set only the latter one will be put into settings.json.

Type	Default
Optional[Hash]	`undef`

padoptions

Configure pad options in settings.json.

Type	Default
Struct	`noColors => false`, `showControls => true`, `showChat => true`, `showLineNumbers => true`, `useMonospaceFont => false`, `userName => false`, `userColor => false`, `rtl => false`, `alwaysShowChat => false`, `chatAndUsers => false`, `lang => en-gb`

Limitations

Currently, only upstart and systemd are supported as Service providers. More support is highly welcomed.

Development

Please see CONTRIBUTING.md for how to contribute patches!

Files

README.md

Latest commit

History

README.md

File metadata and controls

Etherpad module for Puppet

Table of Contents

Overview

Setup

What etherpad affects

Setup Requirements

Beginning with etherpad

Usage

Reference

etherpad

ensure

service_name

service_ensure

service_provider

manage_user

manage_abiword

abiword_path

abiword_path

user & group

root_dir

source

database_type

database_host

database_user

database_name

database_password

ip

port

trust_proxy

max_age

minify

require_session

edit_only

require_authentication

require_authorization

use_default_ldapauth

plugins_list

button_link

ldapauth

mypads

pad_title

default_pad_text

logconfig_file

logconfig_file_filename

logconfig_file_max_log_size

logconfig_file_backups

logconfig_file_category

users

padoptions

Limitations

Development