Skip to content

ULHPC/puppet-etherpad

 
 

Repository files navigation

Etherpad module for Puppet

Build Status Code Coverage Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started 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

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!

Packages

No packages published

Languages

  • Ruby 59.3%
  • Puppet 35.5%
  • Shell 4.9%
  • Pascal 0.3%