dokuwiki

Table of Contents

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

Description

This module manages and install dokuwiki! (https://https://www.dokuwiki.org/)

Currently it is still in development. There is another dokuwiki module on the forge, but it is not being maintained and it is not forkable because no license is supplied.

This module should: install, manage (config files), secure and offer enough functionality to run dokuwiki in production.

Limitations:

• Tested and developed for Debian 9 (there are plans to support more OSses).
• By default it uses apache as a webserver, but this can be disabled.

If you are missing any features in this module, please open an issue or write a pull request.

Setup

What dokuwiki affects

By default dokuwiki affects:

• Dokuwiki directory
• Apache service and config
• PHP Config
• Dokuwiki configuration files (local, acl, users)

Beginning with dokuwiki

To install Dokuwiki declare the dokuwiki class:

class { 'dokuwiki': 
  wiki_title => 'Awesome wiki!',
}

• This will install dokuwiki with the latest tar.gz from the dokuwiki website (stable version).
• Also it will install apache and php.
• Create an apache vhost pointing the the extracted dokuwiki folder.
• Configure dokuwiki to NOT use authentication.

Usage

A beter way to use the dokuwiki is of course to secure it (enable ACLs) and not use the default completly open schema. For this you can specify the 'default_acl' option. See #references for more details on this option, but in general a more secure configuration looks like this:

 class {'dokuwiki':
   wiki_title         => 'Wiki',
   admin_user         => 'admin',
   admin_passwordhash => '$1$4fd0ad31$.cId7p1uxI4a.RcrH81On0', # Which is hashed and salted: admin
   default_acl        => 'public',
 }

It is not recommended by dokuwiki to modify the ACLs outside of the dokuwiki webinterface. So, by default this module does not overwrite any acls; it only supplies one for installation.

To create any additional users: use the dokuwiki::user defined type:

   dokuwiki::user { 'admin':
     passwordhash => '$1$4fd0ad31$.cId7p1uxI4a.RcrH81On0',
     real_name    => 'admin',
     email        => 'root@localhost',
     groups       => ['user', 'admin'],
   }

Limitations

Currently the module is in development. I only tested it on Debian, but I aim to support more versions.

Development

To help development, please make sure you use PDK for the development of new feature and create / run tests. Run the acc tests with the follow command:

pdk bundle
pdk bundle exec rake spec_prep
pdk bundle exec rspec spec/defines/user_spec.rb
pdk bundle exec rake beaker

And update the reference documentation when new options have been added:

puppet strings generate --format markdown

Reference

Table of Contents

Classes

• dokuwiki: This module manages and install dokuwiki.
• dokuwiki::config: Main configuration of dokuwiki
• dokuwiki::install: Main installation of dokuwiki
• dokuwiki::params: Default variable logic for dokuwiki
• dokuwiki::service: Configures services required by dokuwiki

Defined types

• dokuwiki::acl: Create ACL rules in the acl.auth.php configuration file
• dokuwiki::user: Creates local user in the users.auth.php file

Classes

dokuwiki

dokuwiki

This module manages and install dokuwiki.

Examples

class { 'dokuwiki':
  wiki_title => 'My awesome dokuwiki'
}

Parameters

The following parameters are available in the dokuwiki class.

wiki_title

Data type: String

The title of this wiki, will be displayed on all the pages.

admin_user

Data type: String

The username of the admin user, can be left empty if default_acl is open

Default value: $dokuwiki::params::admin_user

admin_passwordhash

Data type: String

The password hash of the admin user. To generate the hash use the mkpasswd, which is part of the whois package. Generate the password using the following command: mkpasswd -m sha-512 -s <<< YourPass

Default value: $dokuwiki::params::admin_password

admin_real_name

Data type: String

The real name of the admin user

Default value: $dokuwiki::params::admin_real_name

admin_email

Data type: String

The e-mail adres of the admin user

Default value: $dokuwiki::params::admin_email

admin_groups

Data type: Array

An array of group for the admin user.

Default value: $dokuwiki::params::admin_groups

manage_webserver

Data type: Boolean

If enabled (default), this module will also manages and installs apache

Default value: $dokuwiki::params::manage_webserver

manage_php

Data type: Boolean

If enabled (default), this module also manages and installs php

Default value: $dokuwiki::params::manage_php

enable_ssl

Data type: Boolean

If enabled, this module will enable ssl and also a redirect to port 443 from port 80

Default value: $dokuwiki::params::enable_ssl

servername

Data type: String

Default set to the fqdn fact is used for the redirect of port 80 to port 443. Make sure this name is resolve able by the clients accessing the server.

Default value: $dokuwiki::params::servername

ssl_cert

Data type: String

Defaults to the selfsigned snakeoil certificate, but can be used to change the certificate used by the apache instance

Default value: $dokuwiki::params::ssl_cert

ssl_key

Data type: String

Defaults to the selfsigned snakeoil private key, but can be used to change the privatekey used by the apache instance

Default value: $dokuwiki::params::ssl_key

ssl_chain

Data type: Optional[String]

Defaults to undef, but can be used to specify the cachain that apache will sent.

Default value: $dokuwiki::params::ssl_chain

lang

Data type: String

The language of the dokuwiki

Default value: $dokuwiki::params::lang

license

Data type: String

The default license used for all the content placed on the dokuwiki

Default value: $dokuwiki::params::license

useacl

Data type: Integer

If set to 1 the ACL module is enable and the dokuwiki will use the acl.auth.php config file

Default value: $dokuwiki::params::useacl

default_acl

Data type: Enum['public', 'open', 'closed']

Specifiy the default acl. Open means: anyone can edit, Public means: anyone can view; users can edit, Closed means: only users can view and edit

Default value: $dokuwiki::params::default_acl

replace_acl

Data type: Boolean

If set, this module will replace contents of the ACL, possibly revering changes done in the webinterface. Dokuwiki does not recommend this.

Default value: $dokuwiki::params::replace_acl

replace_local

Data type: Boolean

If set (default unset), this module will replace contents of the local.php file, possibly reverting changes done in the webinterface.

Default value: $dokuwiki::params::replace_local

replace_users_auth

Data type: Boolean

If set, this module will replace contents in the users.auth.php file, possibly reverting changes done in the webitnerface.

Default value: $dokuwiki::params::replace_users_auth

superuser

Data type: String

This variable determines which user or group defines the super admins

Default value: $dokuwiki::params::superuser

disableactions

Data type: String

This variable can be used to disable specific actions: like registering. See https://www.dokuwiki.org/config:disableactions for more information

Default value: $dokuwiki::params::disableactions

userewrite

Data type: Integer[0, 2]

The variable can be used to enable rewrites. Defaults to 0.

Default value: $dokuwiki::params::userewrite

dokuwiki::config

dokuwiki::config

Main configuration of dokuwiki

Examples

This class should not be called

dokuwiki::install

dokuwiki::install

Main installation of dokuwiki

Examples

This class should not be called

dokuwiki::params

dokuwiki::params

Default variable logic for dokuwiki

Examples

This class should not be called

dokuwiki::service

dokuwiki::service

Configures services required by dokuwiki

Examples

This class should not be called

Defined types

dokuwiki::acl

dokuwiki::acl

Create ACL rules in the acl.auth.php configuration file

Examples

dokuwiki::acl { 'acl_line':
  namespace  => '*',
  group      => '@ALL',
  permission => '8',
}

Parameters

The following parameters are available in the dokuwiki::acl defined type.

namespace

Data type: String

Specify the name for which this ACL rule applies. Use '*' to apply rule to all namespaces.

group

Data type: String

Specify the group for which this ACL rule applies. Start the group name with the '@' sign and use '*' to apply rule to all groups.

permission

Data type: Numeric

Specify the permission for this ACL rule. Possible permissions are: 1 for read, 2 edit, 4 create, 8 upload. See https://www.dokuwiki.org/acl for more information.

dokuwiki::user

dokuwiki::user

Creates local user in the users.auth.php file

Examples

dokuwiki::user { 'admin':
  passwordhash => '$1$4fd0ad31$.cId7p1uxI4a.RcrH81On0',
  real_name    => 'admin',
  email        => 'root@localhost',
  groups       => ['user', 'admin'],
}

Parameters

The following parameters are available in the dokuwiki::user defined type.

passwordhash

Data type: String

The password hash for the user. To generate the hash use the mkpasswd, which is part of the whois package. Generate the password using the following command: mkpasswd -m sha-512 -s <<< YourPass

Default value: ''

real_name

Data type: String

The real name of the user, used to display the name of the user when pages are edit or created.

Default value: ''

email

Data type: String

The e-mail address of the user.

Default value: ''

groups

Data type: Array

The groups of the user.

Default value: []

login

Data type: String

The username of the user to create, default to the $name parameter.

Default value: $name

Changelog

Release 0.3.2

Features

• None Bugfixes
• Renamed the ssl_ca to ssl_chain, as it should have been. Known Issues
• Only runs on Debian / Ubuntu
• No acceptances tests...

Release 0.3.1

Features

• Able to specify the ssl_ca option Bugfixes
• None Known Issues
• Only runs on Debian / Ubuntu

Release 0.3.0

Features

• SSL support, either selfsigned or specify the paths for cert and key
• Specify if the module should manage the local.php and users.auth.php file
• Now also manages the htaccess file
• Added userewrite option and auto provisioning of the requirements Bugfixes
• Closed default ACL was not working
• Default apache options were insecure Known Issues
• Only runs on Debian / Ubuntu

Release 0.2.1

Features

• None Bugfixes
• If more than one ACL was supplied, only the first was working. Known Issues
• Only runs on Debian / Ubuntu

Release 0.2.0

Features

• More complex installation, it basically runs the install.php file Bugfixes
• Non Known Issues
• Only runs on Debian / Ubuntu

Release 0.1.0

Features

• Initial release, simply only installs dokuwiki Bugfixes
• Non Known Issues
• Only runs on Debian / Ubuntu