DEBOPS.ETHERPAD(5)

NAME
debops.etherpad - Manage Etherpad Lite using Ansible

SYNOPSIS

debops run service/etherpad [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

Etherpad <https://en.wikipedia.org/wiki/Etherpad> is a collaborative text editor usable through a web browser. Documents can be edited by multiple people in real time, shared and exported in different formats.

This role can be used to deploy and configure Etherpad Lite <https://github.com/ether/etherpad-lite>, a NodeJS version of Etherpad, on a Debian/Ubuntu host. The application can use a MariaDB or SQLite database as a storage backend, and will be configured behind a Nginx proxy as a frontend.

GETTING STARTED

  Default configuration

The role will detect presence of a MariaDB database server and use it if available. If not, a SQLite database will be automatically configured on the server. You can configure MariaDB database using the debops.mariadb_server Ansible role.

  Example inventory

To install and configure Etherpad on a host, it needs to be present in the [debops_service_etherpad] Ansible inventory group:

[debops_service_etherpad]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.etherpad role:

---
- name: Manage Etherpad service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_etherpad' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring',
              'role::nodejs', 'role::mariadb', 'role::postgresql', 'role::nginx' ]
      keyring__dependent_apt_keys:
        - '{{ nodejs__keyring__dependent_apt_keys }}'
        - '{{ mariadb__keyring__dependent_apt_keys if (etherpad__database == "mysql") else [] }}'
        - '{{ postgresql__keyring__dependent_apt_keys if (etherpad__database == "postgresql") else [] }}'
        - '{{ nginx__keyring__dependent_apt_keys }}'
    - role: etc_services
      tags: [ 'role::etc_services', 'skip::etc_services' ]
      etc_services__dependent_list:
        - '{{ etherpad__etc_services__dependent_list }}'
    - role: cron
      tags: [ 'role::cron', 'skip::cron' ]
    - role: logrotate
      tags: [ 'role::logrotate', 'skip::logrotate' ]
      logrotate__dependent_config:
        - '{{ etherpad__logrotate__dependent_config }}'
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ nginx__apt_preferences__dependent_list }}'
        - '{{ nodejs__apt_preferences__dependent_list }}'
    - role: nodejs
      tags: [ 'role::nodejs', 'skip::nodejs' ]
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ nginx__ferm__dependent_rules }}'
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::mariadb', 'role::postgresql' ]
      python__dependent_packages3:
        - '{{ postgresql__python__dependent_packages3 if etherpad__database == "postgres" else [] }}'
        - '{{ mariadb__python__dependent_packages3 if etherpad__database == "mysql" else [] }}'
        - '{{ nginx__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ postgresql__python__dependent_packages2 if etherpad__database == "postgres" else [] }}'
        - '{{ mariadb__python__dependent_packages2 if etherpad__database == "mysql" else [] }}'
        - '{{ nginx__python__dependent_packages2 }}'
    - role: mariadb
      tags: [ 'role::mariadb', 'skip::mariadb' ]
      mariadb__dependent_users:
        - '{{ etherpad__mariadb__dependent_users }}'
      mariadb__dependent_databases:
        - '{{ etherpad__mariadb__dependent_databases }}'
      when: etherpad__database == 'mysql'
    - role: postgresql
      tags: [ 'role::postgresql', 'skip::postgresql' ]
      postgresql__dependent_roles:
        - '{{ etherpad__postgresql__dependent_roles }}'
      postgresql__dependent_databases:
        - '{{ etherpad__postgresql__dependent_databases }}'
      when: etherpad__database == 'postgres'
    - role: nginx
      tags: [ 'role::nginx', 'skip::nginx' ]
      nginx__dependent_servers:
        - '{{ etherpad__nginx__dependent_servers }}'
      nginx__dependent_upstreams:
        - '{{ etherpad__nginx__dependent_upstreams }}'
    - role: etherpad
      tags: [ 'role::etherpad', 'skip::etherpad' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::etherpad
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

role::etherpad:source
    Run tasks related to install Etherpad from source.

role::etherpad:config
    Run tasks related to configuring Etherpad.

role::etherpad:plugins
    Run tasks which install the defined Etherpad plugins.

role::etherpad:api:call
    Run tasks API call tasks. Can be used for rapid API calls.

role::etherpad:api
    Same as role::etherpad:api:call but ensures that the service is running and waiting for it to start before trying.

AUTHOR
Maciej Delmanowski, Hartmut Goebel, Robin Schneider

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others