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

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

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

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.

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

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,
    },
  },
}

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

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.

Name under which the service will be known.

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

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

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

Whether to manage the dependency of the abiword package.

Absolute Path to the abiword binary.

Whether to manage the dependency of the tidy package.

Absolute Path to the abiword binary.

The user and group under which etherpad will be running.

Absolute Path of the etherpad installation.

URL to the git source of etherpad.

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

Host on which the database is running.

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

Name of database to connect to.

Password to use when connecting to database.

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

Port on which etherpad will be listening.

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

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

Whether to minify the delivered JavaScript and CSS.

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

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.

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

Note: /admin always requires authentication.

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

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.

Manage etherpad's plugins.

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

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.

Manage the configuration of ep_button_link.

Manage the configuration of ep_ldapauth.

Manage the configuration of ep_mypads.

Name of your instance

The default text of a pad.

Enable/disable logging to a file.

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

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

The number of logfiles to keep after rotation.

Only log a specific category.

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

Configure pad options in settings.json.

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

Please see CONTRIBUTING.md for how to contribute patches!