User Tools

Site Tools


tutorials:dokuwiki

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

tutorials:dokuwiki [2011/09/12 23:39]
razvan [LDAP Authentication]
tutorials:dokuwiki [2020/07/20 09:16]
Line 1: Line 1:
-= DokuWiki Installation and Configuration = 
  
-[[http://www.dokuwiki.org/dokuwiki|DokuWiki]] is one of the [[http://www.wikimatrix.org/statistic/Most+Views|most popular wiki implementations]]. I'm using it right now to write this tutorial. DokuWiki is a lightweight implementation possessing a of features which I find very useful and convenient: 
-* it is file-based (no database required); 
-* installation and configuration is a breeze, especially for a manual installation (grabbing the source code, unzip and configure); 
-* it uses a namespace-based structure, allowing for easy organization of information; 
-* its community develops a lot of useful [[http://www.dokuwiki.org/plugins|plugins]]; 
-* it is, in my opinion, very usable: the interface, the editing features, information organization, overall view are intuitive and allow for rapid editing without little loss of time. 
- 
-That being said, let's move on to the requirements and installation steps. 
-== User Requirements == 
- 
-DokuWiki is highly configurable and customizable and I'm going to define the features that are to be used by a wiki installation. These are the features I'm usually going for when doing a DokuWiki installation, such as [[http://swarm.cs.pub.ro/~razvan/dokuwiki/|this one]]: 
-* The wiki is to be installed by a non-priviliged users using their own "user directory" (such as {{{public_html}}}). 
-* The wiki is public: everyone can read its contents and only certain users may edit it, after logging in (through the use of ACLs). 
-* Create index pages for easy access to information. This is achieved with the help of the [[http://www.dokuwiki.org/plugin:indexmenu|indexmenu plugin]]. My wiki's [[http://swarm.cs.pub.ro/~razvan/dokuwiki/|start page]] or [[http://swarm.cs.pub.ro/~razvan/dokuwiki/start?do=index|index page]] are index pages deployed with the help the indexmenu plugin. 
-* The wiki will use "pretty" slash-separated URL. It will use {{{http://swarm.cs.pub.ro/~razvan/dokuwiki/tutorials/dokuwiki}}} instead of {{{http://swarm.cs.pub.ro/~razvan/dokuwiki/doku.php?id=tutorials:dokuwiki}}}. 
-* The wiki will enable [[http://www.wikicreole.org/|Creole markup]], through the use of the [[http://www.dokuwiki.org/plugin:creole|creole plugin]]. 
-* The wiki will define a {{{contrib}}} namespace that is world-writable. 
-* The wiki will define an {{{internal}}} namespace that is readable/writable only by authenticated users. 
-* The wiki enables HTTPS-access to login/logout and admin pages (but HTTP access for normal ones). 
-* The wiki enables LDAP authentication (optional - one must have access to a LDAP service). 
- 
-== Install and Upgrade Scripts == 
- 
-* Mircea Bardac and me have created a set of scripts for installation, configuration and upgrade of DokuWiki. These scripts provide solutions to most of the above [[:tutorials:dokuwiki#user_requirements]]. The scripts are part of the [[http://koala.cs.pub.ro/git/?p=admin-public.git;a=tree|admin Git repository]] storing a variety of administrative scripts. 
-* Issue the following command to get a copy of the repository<code> 
-git clone http://koala.cs.pub.ro/git/admin-public.git 
-</code> 
-* Browse to the {{{dokuwiki/}}} subfolder. Please go through the {{{README}}} file for a description of each file. 
-* Instructions below are also present in the {{{README}}} file in the {{{dokuwiki/}}} folder in the repository. 
-== Basic Installation and Configuration == 
- 
- 
-=== Using the Install Scripts === 
- 
-# Find the desired DokuWiki version for download. Use this [[http://www.splitbrain.org/projects/dokuwiki|download URL]]. 
-# Run the install {{{dw-install}}} script. It requires three arguments: 
-## the installation folder for {{{dokuwiki}}}; it must exist; ({{{~/public_html/dokuwiki2/}}} in the sample run) 
-## the DokuWiki tarball download URL; ({{{http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2009-12-25.tgz}}} - the latest stable version - in the sample run) 
-## the future DokuWiki URL. ({{{http://elf.cs.pub.ro/so/wiki2/}}} in the sample run) 
-#* Sample run:<code> 
-razvan@swarm:~/scripts/dw$ ./dw-install ~/public_html/dw-test/ http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2011-05-25a.tgz http://swarm.cs.pub.ro/~razvan/dw-test 
- 
-* Logging information to /tmp/tmp.JYCdHg2w5P. 
-* Using download link http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2011-05-25a.tgz 
-  * Downloading DokuWiki ... done. 
-* Preparing installation folder /home/razvan/public_html/dw-test/ ... done. 
-* Installing plugins 
-  * Installing plugin: Creole ... done. 
-  * Installing plugin: Google Analytics ... done. 
-  * Installing plugin: Include ... done. 
-  * Installing plugin: Index-Menu ... done. 
-  * Installing plugin: Display-Wiki-Page ...done. 
-  * Installing ggauth backend ...done. 
- 
-Installation complete. 
-1. Open in web browser: http://swarm.cs.pub.ro/~razvan/dw-test/install.php 
-2. Fill required information to complete the basic installation. 
-3. Remove /home/razvan/public_html/dw-test//install.php.bak file. 
-4. Run: 
-   ./dw-post-install /home/razvan/public_html/dw-test/ /~razvan/dw-test/ 
-</code> 
-# Open install URL (as mentioned in step 1 of the post-install message) and configure DokuWiki instance. 
-#* The web configuration interface is quite intuitive. 
-#* You will probably go for a public wiki (read access for everyone, and write access for registered users). 
-# Run the {{{dw-post-install}}} script, as mentioned in step 4 of the end message. 
-#* The `dw-post-install' script is actually responsible for two things: 
-#*# Updating the {{{$DW_ROOT/conf/local.php}}} file. That means wiki and plugin configuration. The configuration is what we commonly use. Go through file and update it according to your needs/preferences. 
-#*# Creating the {{{$DW_ROOT/.htaccess}}} file. This file is responsible with the configuration of pretty (hierarchical) URLs and HTTPS support. 
-#* Sample run:<code> 
-razvan@swarm:~/scripts/dw$ ./dw-post-install /home/razvan/public_html/dw-test/ /~razvan/dw-test/ 
- * Updating conf/local.php ... done. 
- * Updating .htaccess ... done. 
-</code> 
-# **Congratulations!** You've got a basic DokuWiki installation with pretty slash based URLs, HTTPS support login and Creole markup. 
-=== indexmenu Configuration === 
- 
-The indexmenu plugin is installed but the index pages are not yet created. As written in the {{{local.php}}} file, we will use {{{home:index}}} as the index page:<code> 
-$conf['plugin']['indexmenu']['page_index'] = 'home:index'; 
-</code> 
-At the same time we will create and index menu on the start/home page. 
- 
-You'll need to go through the following steps (mentioned in the {{{README}}} file): 
-# Type {{{home:index}}} in DokuWiki's search bar and create the page. For index display I usually add the following syntax:<code> 
-{{indexmenu>..#2|js navbar nocookie id#random}} 
-</code> 
-#* Each time you will use the {{{Index}}} button in the bottom right corner the index menu in the {{{home:index}}} page is displayed. 
-# Add an index menu to the first page in the wiki (home). Just type {{{home}}} in DokuWiki's search bar and create/edit the page. I usually fill it with something like:<code> 
-= Wiki Name = 
- 
-{{indexmenu>..#1|js navbar nocookie id#random}} 
-</code> 
-#* {{{Wiki Name}}} is the name of the wiki. It gets displayed as a heading 1 title. 
-# You can add indexes to namespaces (edit the {{{$namespace/home}}} page):<code> 
-= Namespace Name == 
- 
-{{indexmenu>.#2|js}} 
-</code> 
- 
-== Advanced Configuration == 
- 
-=== LDAP Authentication === 
- 
-* The [[http://www.dokuwiki.org/auth:ldap|official LDAP Authentication page]] contains important information regarding the configuration of LDAP authentication. 
-* The [[http://koala.cs.pub.ro/gitweb/?p=admin-public.git;a=blob;f=dokuwiki/samples/dokuwiki-ldap-auth-swarm.conf;hb=HEAD|dokuwiki/samples/dokuwiki-ldap-auth-swarm.conf]] contains a configuration sample for LDAP authentication using the LDAP service installed on the {{{swarm.cs.pub.ro}}} server:<code> 
-$conf['authtype'   = 'ldap'; 
-  
-$conf['auth']['ldap']['port'       = 636; 
-$conf['auth']['ldap']['server'     = 'ldaps://swarm.cs.pub.ro'; 
-$conf['auth']['ldap']['usertree'   = 'ou=People,dc=swarm,dc=cs,dc=pub,dc=ro'; 
-$conf['auth']['ldap']['grouptree'  = 'ou=Group,dc=swarm,dc=cs,dc=pub,dc=ro'; 
-$conf['auth']['ldap']['userfilter' = '(&(uid=%{user})(objectClass=posixAccount))'; 
-$conf['auth']['ldap']['groupfilter'] = '(&(objectClass=posixGroup)(|(gidNumber=%{gid})(memberUID=%{user})))'; 
-  
-# This is optional but may be required for your server: 
-$conf['auth']['ldap']['version'   = 3; 
- 
-# Mapping can be used to specify where the internal data is coming from.  
-$conf['auth']['ldap']['mapping']['name' = 'cn'; # Name of attribute Active Directory stores it's pretty print user name. 
-$conf['auth']['ldap']['mapping']['grps' = array('memberof' => '/CN=(.+?),/i'); 
- 
-# Optional debugging 
-$conf['auth']['ldap']['debug'     = 1; 
-</code> 
-* The {{{$conf['authtype'   = 'ldap';}}} line enables LDAP authentication. 
-* The {{{$conf['auth']['ldap']['debug'     = 1;}}} line should be commented out after the configuration is working. 
-* **IMPORTANT**: You may not have write access to the {{{local.php}}} configuration file. The solution is: 
-*# Make a copy of the {{{local.php}}} file (be it {{{local.php.bak}}}). 
-*# Delete the file {{{rm local.php}}}; it asks for confirmation -- confirm it. This works as the file is in your home folder. 
-*# Copy the backup file ({{{local.php.bak}}}) to {{{local.php}}}. 
-*# Provide access writes to the group, assuming that to be {{{www-data}}}, in order to allow web server write access from the web configuration interface: {{{chmod g+w local.php}}}. 
- 
-==== Disable Unnecessary Actions ==== 
- 
-In case you choose to use LDAP authentication, you should disable the Dokuwiki's {{{Register}}}, {{{Send password}}} and {{{Profile}}} options. This can be accomplished by two means: 
-# use the {{{$conf['disableactions'] = 'register,resendpw,profile';}}} line in {{{local.php}}}; 
-# use the DokuWiki's administrative {{{Configuration Manager}}} link (search for {{{disableactions}}}). 
-=== Split Authentication === 
- 
-The LDAP service often offers little support for group authorization inside DokuWiki. A better approach would be authenticating through LDAP and using another engine for authentication. This can be accomplished through the use of [[http://www.dokuwiki.org/auth:ggauth#split|split authentication]]. I'm using it to authenticate through LDAP and use the basic {{{user.auth.php}}} file in DokuWiki's {{{conf/}}} folder. 
- 
-The [[http://lastweekend.com.au/ggauth.5.zip|experimental authentication backends]], providing "split authentication" is deployed in the [[:tutorials:dokuwiki#install_and_upgrade_scripts | install script]]. 
- 
-In order to configure split authentication, do the following: 
-# Update the {{{local.php}}} file with configuration lines such as these:<code> 
-$conf['authtype'] = 'split'; 
- 
-$conf['auth']['split']['login_auth'] = 'ldap';  # the auth backend for authentication 
-$conf['auth']['split']['groups_auth'] = 'plain'; # the auth backend that supplies groups 
-$conf['auth']['split']['merge_groups'] = false; # should groups from login auth also be included 
-$conf['auth']['split']['use_login_auth_for_users'] = true; # Should login auth be used for supplying the list of users for usermanager 
-$conf['auth']['split']['use_login_auth_for_name'] = true; # Should login auth supply user name, or only used if groups auth provides an empty name 
-$conf['auth']['split']['use_login_auth_for_mail'] = true; # Should login auth supply email address, or only used if groups auth provides empty email. 
-</code> 
-#* I assumed the configuration lines for LDAP are already there. 
-#* In the above configuration, we are using LDAP for authentication and the {{{plain}}} engine for groups and authorization. 
-# Authorization configuration is done by editing the {{{conf/users.auth.php}}} file. Some sample lines are shown below:<code> 
-# user:MD5password:Real Name:email:groups,comma,separated 
- 
-razvan:x:x:x:admin,so 
-oana:x:x:x:so 
-ddvlad:x:x:x:so 
-dbaluta:x:x:x:so 
-apitis:x:x:x:so 
-bdrutu:x:x:x:so 
-catalinme:x:x:x:so 
-[...] 
-</code> 
-#* The {{{MD5password}}}, {{{Real Name}}} and {{{email}}} fields are provided by the LDAP authentication engine and aren't filled. 
-# You can now use the {{{Access Control List Management}}} link in the "Administration" menu for authorization: configuring access rights for users and groups. 
-== Upgrading == 
- 
-DokuWiki has a smart notification system that lets you know whether a new version of DokuWiki is available. A DokuWiki upgrade is fairly easy to accomplish. The upgrade steps are described on the [[http://www.dokuwiki.org/install:upgrade|official page]]. 
- 
-The are two scripts you may use. One is to be run by root (the {{{dw-upgrade}}} script), while the other (the {{{dw-upgrade-no-root}}} script) may be run by a non-priviliged user. Each script creates a backup copy of the current wiki installation before upgrading. 
- 
-The {{{dw-upgrade}}} script (run by {{{root}}}) is to be used when your backup needs to be web accessible. The backup uses the precises ownership information and access rights (may be owned by {{{www-data}}}) such that it would be an exact copy of the original DokuWiki installation. In order for the backup copy to be completely accesible, its {{{.htaccess}}} filesh ould probably be updated. 
- 
-The backup directory passed to the scripts should exist. This is where the actual backup is created using a name starting with {{{dokuwiki-bak}}} (such as {{{dokuwiki-bak-2011-09-12}}}). 
- 
-A sample run is shown below:<code> 
-razvan@swarm:~/scripts/dw$ ./dw-upgrade-no-root ~razvan/public_html/dw-test/ http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2011-05-25a.tgz ~razvan/public_html/backup/ 
- 
-* Logging information to /tmp/tmp.xQuZwTyfgu. 
-  * Downloading DokuWiki ... done. 
- * Backing up Dokuwiki instance to /home/razvan/public_html/backup//dokuwiki-bak-2011-09-12 ... done 
- * Upgrading Dokuwiki installation in /home/razvan/public_html/dw-test/ ... done 
-* Installing plugins 
-  * Installing plugin: Creole ... done. 
-  * Installing plugin: Google Analytics ... done. 
-  * Installing plugin: Include ... done. 
-  * Installing plugin: Index-Menu ... done. 
-  * Installing plugin: Display-Wiki-Page ...done. 
-  * Installing ggauth backend ...done. 
-</code> 
- 
-Enjoy! 
tutorials/dokuwiki.txt · Last modified: 2020/07/20 09:16 (external edit)