/bcacheira.dokuwiki

An ansible role to install Dokuwiki

Primary LanguageShellGNU General Public License v3.0GPL-3.0

Ansible Role: Dokuwiki

Build status for this role: Build Status

This role installs, configures, hardens and/or upgrades Dokuwiki on a server. The main focus is on provisioning Dokuwiki instances in a repeatable and secure fashion. It does not install a webserver by itself, but it can add and enable an Apache configuration file (which is included as template in the role).

Requirements

A webserver having PHP installed. For Apache, we suggest using PeterMosmans.apache2. If you prefer Nginx, please use Nginxinc.nginx.

Role Variables

/vars

Dependencies and package related variables are defined in vars/*. This includes all dependencies for dokuwiki and recommended plugins, as well as the location of all dokuwiki branches. You can select which branch to install with dokuwiki_version

Variable Comments
dokuwiki_stable_url dokuwiki_stable_url: https://download.dokuwiki.org/src/dokuwiki/dokuwiki-stable.tgz
dokuwiki_old_stable_url dokuwiki_old_stable_url: https://download.dokuwiki.org/src/dokuwiki/dokuwiki-oldstable.tgz
dokuwiki_development_url dokuwiki_development_url: http://github.com/splitbrain/dokuwiki/tarball/master

/defaults

All other available variables are listed below, along with default values. The default values are specified in default/main.yml.

Variable Comments
dokuwiki_server_name Dokuwiki ServerName Directive. dokuwiki_server_name: "localhost"
dokuwiki_base Dokuwiki base directory. dokuwiki_base: /var/www/dokuwiki
dokuwiki_savedir Dokuwiki data directory. dokuwiki_savedir: /var/www/dokuwiki/data
dokuwiki_version Version to install. dokuwiki_version: stable
dokuwiki_webserver When defined, will deploy an Nginx or Apache configuration (apache.dokuwiki.conf.j2 or nginx.dokuwiki.conf.j2), and enable the site. dokuwiki_webserver: nginx.
dokuwiki_name The 'internal' name of the dokuwiki, which is e.g. used for Nginx or Apache logfiles and the cleanup cronjob. (when dokuwiki_webserver is defined). This allows the Ansible role to be used for multiple Dokuwiki sites on the same server. Default: dokuwiki_name: dokuwiki
dokuwiki_base The local path where Dokuwiki will be installed. dokuwiki_base: /var/www/html
dokuwiki_user The user owning the Dokuwiki files. dokuwiki_user: root
dokuwiki_group The group owning the Dokuwiki files. dokuwiki_group: www-data
dokuwiki_plugins (1) List of name / source pairs, with plugins to automatically install via dokuwiki's gittool.
dokuwiki_plugins_remove (2) A list of plugins to automatically remove upon installation or upgrade.
dokuwiki_templates (3) A list of templates to automatically install.
dokuwiki_provision (4) When true, apply configuration templates to provision Dokuwiki. dokuwiki_provision: true
dokuwiki_savedir The directory where all files (content) will be stored. See Dokuwiki Security - Move Directories out of DocRoot for more info. dokuwiki_savedir: /var/www/html/data

(1) dokuwiki_plugins: The current, opinionated list of default plugins is:

dokuwiki_plugins:
  - pagelist
  - fastwiki
  - edittable
  - dw2pdf
  - bookcreator
  - tag
  - discussion
  - dropfiles
  - color
  - nspages
  - sortablejs

(2) dokuwiki_plugins_remove: The default list of plugins to remove is:

dokuwiki_plugins_remove:
  - authad
  - authldap
  - authmysql
  - authpdo
  - authpgsql
  - info
  - popularity

(3) dokuwiki_templates: A list of templates to install

dokuwiki_templates:
 - bootstrap3

(4) dokuwiki_provision: If not specified or false, Dokuwiki will be unprovisioned, a default installation. See below in the provisioning chapter which variables can be used in the configuration templates. Note that when this variable is true, it will (re-)template and overwrite the current Dokuwiki configuration.

Configuration templates

The following configuration files, located at conf/*, are templated:

Template Comments
acl.auth.php.j2 Dokuwiki ACL Config file
cleanup.sh.j2 Cron job to cleanup DokuWiki installations
local.protected.php.j2 Dokuwiki's Main Configuration File - Local Settings, protected
php-fpm.www.conf.j2 PHP FPM config file - altered to make this role php version agnostic
plugins.local.php.j2 Local plugin enable/disable settings - recommended to be used with dokuwiki_plugins_removed
users.auth.php.j2 If dokuwiki_users is defined, this file is provisioned with those local users
apache.dokuwiki.conf.j2 Apache config for dokuwiki
nginx.dokuwiki.conf.j2 Nginx config for dokuwiki

Provisioning

The following variables will be used in the configuration templates, and therefore will only be applied if dokuwiki_provision is set to true.

Template Comments
dokuwiki_title The Dokuwiki title. dokuwiki_title: "Default Dokuwiki site"
dokuwiki_opt_lang Dokuwiki's language option. dokuwiki_opt_lang: "en"
dokuwiki_opt_policy Dokuwiki's policy. 0 - Open Wiki (read, write, upload for everyone); 1 - Public Wiki (read for everyone, write and upload for registered users); 2 - Closed Wiki (read, write, upload for registered users only). dokuwiki_opt_policy: "0"
dokuwiki_opt_acl Dokuwiki ACL enable. dokuwiki_opt_acl: "1"
dokuwiki_acl_all The ACL bits for the default (@ALL) group. By default, only logged on users are allowed access (0).
dokuwiki_acl_user The ACL bits for the user (@user) group. By default, users have upload, create, edit, and read permissions (8).
dokuwiki_disableactions Which actions to disable. By default, user auto registering is disabled.
dokuwiki_local (1) A list of name / value configuration pairs to be added to the local.protected.php configuration file.
dokuwiki_users (2) A list of users
dokuwiki_opt_license (3) The content license to use. dokuwiki_opt_license: "0"

(1) dokuwiki_local: You can add additional parameters to the local.protected.php configuration file, as seen here:

dokuwiki_local:
  - name: "['passcrypt']"
    value: 'bcrypt'

This will result in adding the following string to /conf/local.protected.php:

$conf['passcrypt'] = 'bcrypt';

(2) dokuwiki_users: A list of users, containing the following name / value pairs:

- login: login
- hash: password hash
- name: full name
- email: email address
- groups: comma separated list of groups

Example:

dokuwiki_users:
- login: admin
  hash: "$2y$05$Nr3wFqH54gcdhxPK9easseLSVwLAnLTD2flYmQbAbCVIiiTU4mCjS"
  name: Administrator
  email: admin@admin
  groups: admin,user

This will result in adding the user admin to Dokuwiki, with the bcrypted password admin.

(3) dokuwiki_opt_license: The options for this are:

Dependencies

None.

Example Playbook

- hosts: all
  become: yes
  become_method: sudo
  roles:
  - role: PeterMosmans.dokuwiki
  vars:
    dokuwiki_base: /var/www/html
    dokuwiki_webserver: nginx
    dokuwiki_plugins:
      - tag
      - pagelist
    dokuwiki_plugins_remove:
      - authad
      - authldap
      - authmysql
      - authpdo
      - authpgsql
      - info
      - popularity
    dokuwiki_preconfigure: true
    dokuwiki_savedir: /var/www/html/data
    dokuwiki_template: bootstrap3
    dokuwiki_templates:
      - bootstrap3
    dokuwiki_users:
      - login: admin
        hash: "$2y$05$Nr3wFqH54gcdhxPK9easseLSVwLAnLTD2flYmQbAbCVIiiTU4mCjS"
        name: Administrator
        email: admin@admin
        groups: admin,user

This example will install Dokuwiki to /var/www/html, and use /var/www/html/data as data directory. It will install the plugins tag and pagelist, and remove the plugins authad, authldap, authmysql, authpdo, authpgsql, info and popularity. It will install and use the bootstrap3 theme, and grant the user admin with the password admin access to the wiki. Moreover, it will configure and enable the Nginx site.

License

GPLv3

Author Information

Created by Peter Mosmans. Suggestions, feedback and pull requests are always welcome.

Contributors