DEBOPS.DOKUWIKI(5)

NAME
debops.dokuwiki - Manage DokuWiki installation with Ansible

SYNOPSIS

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

DESCRIPTION

DokuWiki <https://www.dokuwiki.org/> is an easy to use, file-based wiki written in PHP5. debops.dokuwiki role installs this wiki on a specified host with nginx as a webserver (using debops.nginx). You can optionally configure multiple DokuWiki instances with shared base installation using DokuWiki vhost farm <https://www.dokuwiki.org/farms> mode.

GETTING STARTED

By default DokuWiki is installed on a separate system account "dokuwiki", in /srv/www/dokuwiki/ subdirectory and will be accessible on https://wiki.<domain>/. debops.nginx and debops.php roles are used to configure the required environment.

  Example inventory

You can install DokuWiki on a host by adding it to [debops_service_dokuwiki] group in your Ansible inventory:

[debops_service_dokuwiki]
hostname

  Example playbook

Here's an example playbook which uses debops.dokuwiki role to install DokuWiki:

---
- name: Manage DokuWiki
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_dokuwiki' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Apply keyring configuration for php environment
      ansible.builtin.import_role:
        name: 'keyring'
      vars:
        keyring__dependent_apt_keys:
          - '{{ php__keyring__dependent_apt_keys }}'
          - '{{ nginx__keyring__dependent_apt_keys }}'
      tags: [ 'role::keyring', 'skip::keyring', 'role::php', 'role::nginx' ]
    - name: Prepare php environment
      ansible.builtin.import_role:
        name: 'php'
        tasks_from: 'main_env'
      tags: [ 'role::php', 'role::php:env', 'role::logrotate' ]
  roles:
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ php__apt_preferences__dependent_list }}'
        - '{{ nginx__apt_preferences__dependent_list }}'
    - role: cron
      tags: [ 'role::cron', 'skip::cron' ]
    - role: logrotate
      tags: [ 'role::logrotate', 'skip::logrotate' ]
      logrotate__dependent_config:
        - '{{ php__logrotate__dependent_config }}'
    - role: php
      tags: [ 'role::php', 'skip::php' ]
      php__dependent_packages:
        - '{{ dokuwiki__php__dependent_packages }}'
      php__dependent_pools:
        - '{{ dokuwiki__php__dependent_pools }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ nginx__ferm__dependent_rules }}'
    - role: python
      tags: [ 'role::python', 'skip::python' ]
      python__dependent_packages3:
        - '{{ ldap__python__dependent_packages3 }}'
        - '{{ nginx__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ ldap__python__dependent_packages2 }}'
        - '{{ nginx__python__dependent_packages2 }}'
    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]
      ldap__dependent_tasks:
        - '{{ dokuwiki__ldap__dependent_tasks }}'
    - role: nginx
      tags: [ 'role::nginx', 'skip::nginx' ]
      nginx__dependent_upstreams:
        - '{{ dokuwiki__nginx__dependent_upstreams }}'
      nginx__dependent_servers:
        - '{{ dokuwiki__nginx__dependent_servers }}'
    - role: dokuwiki
      tags: [ 'role::dokuwiki', 'skip::dokuwiki' ]

  Post-install steps

When Ansible is finished, if you don't use LDAP, you need to finish the configuration by opening the https://wiki.<domain>/install.php page. There you will be able to set the name of your new wiki, superuser account and password, and other settings.

You can then login to your wiki and configure it using the administrative interface.

Some of the provided plugins, for example CodeMirror, might not be installed correctly. In that case, reinstalling them using the admin interface should be enough to correctly enable them in DokuWiki.

  LDAP support

If the LDAP environment managed by the debops.ldap role is configured on a host on which DokuWiki is installed, the debops.dokuwiki role will automatically integrate with it and configure LDAP authentication. In that case, use of the /install.php script might break the installation because the install script disables all authentication plugins apart from the authplain plugin, using the conf/plugins.local.php configuration file. You can still do it if you wish, just remember to remove the authldap entry from the mentioned file afterwards to restore LDAP support.

Alternatively, you can finish installation after logging in using an administrator account. You will have to define basic set of ACLs using the ACL manager - for example to make the whole wiki require authentication to read, you can define an ACL entry for @ALL to "None", and an ACL entry for @USER to "Upload", which will give users the broadest set of permissions without allowing normal users to delete things. The name of the wiki and license used by the wiki can be set in the Configuration Manager.

The debops.dokuwiki role by default creates a separate LDAP object (via the debops.ldap role) that contains the definition of user groups used by DokuWiki. The LDAP object will be a child of the LDAP account object used to access the LDAP directory. This configuration is meant to allow configuration of private DokuWiki instances for different groups of users in the LDAP directory. If you want to instead use the global groups defined in LDAP, you can change that by setting the dokuwiki__ldap_private_groups variable to False.

One LDAP group will be created by default - "DokuWiki Administrators". This is a groupOfNames LDAP object that grants the superuser access to the wiki to people specified using the member attribute. You can define your own additional groups in the same manner as long as they are put below the ou=Groups LDAP object used by the wiki. Inside of the DokuWiki ACL manager, these groups have to be specified with the @ prefix, for example @DokuWiki Administrators.

By default access to DokuWiki service is limited to user accounts that have the authorizedService attribute with either dokuwiki, web-public or * values. To change the requirements or give access to the service to all users, you can edit the LDAP user filter used by DokuWiki, specified in the dokuwiki__ldap_user_filter variable.

You should also read the LDAP Directory Information Tree for details about LDAP objects and directory structure configured by the debops.dokuwiki role.

AUTHOR
Maciej Delmanowski

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