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:14]
razvan [Install and Upgrade Scripts]
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. 
-== Basic Installation and Configuration == 
- 
- 
-=== Using the Install Scripts === 
- 
-These instructions are also present in the {{{README}}} file in the {{{dokuwiki/}}} folder in the repository. 
- 
-# Find the desired DokuWiki version for download. Use this [[http://www.splitbrain.org/projects/dokuwiki|download URL]]. 
-# Run the install {{{install_dokuwiki}}} 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> 
-so@elf:~/dokuwiki$ ./install_dokuwiki  ~/public_html/dokuwiki2/ http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2009-12-25.tgz http://elf.cs.pub.ro/so/wiki2/ 
-* Using download link http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2009-12-25.tgz 
-  * Downloading DokuWiki ...  done. 
-* Preparing installation folder /home/so/public_html/dokuwiki2/ ... 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. 
- 
- 
-Installation complete. 
-1. Open in web browser: http://elf.cs.pub.ro/so/wiki2/install.php 
-2. After the install procedure run: 
-   ./post_install_dokuwiki /home/so/public_html/dokuwiki2/ /so/wiki2/ 
- 
-Now you're done. 
-</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 {{{post_install_dokuwiki}}} script (as mentioned in step 2 of the post-install message). 
-#* The script creates a {{{.htaccesss}}} file in DokuWiki's installation folder and prints out other configuration options you should do. 
-#** The {{{.htaccess}}} file contains Apache2 [[http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html|mod_rewrite]] rules for pretty slash-based URLs. 
-#* Sample run:<code> 
-so@elf:~/dokuwiki$ ./post_install_dokuwiki /home/so/public_html/dokuwiki2/ /so/wiki2/ 
-Add to '/home/so/public_html/dokuwiki2/conf/local.php' the following lines 
-(use the web interface in case you don't have enough rights): 
- 
-$conf['start'] = 'home'; 
-$conf['youarehere'] = 1; 
-$conf['sneaky_index'] = 1; 
-$conf['userewrite'] = '1'; 
-$conf['securecookie'] = 0; 
-$conf['useslash'] = 1; 
-$conf['sepchar'] = '-'; 
-$conf['plugin']['creole']['precedence'] = 'creole'; 
-$conf['plugin']['indexmenu']['page_index'] = 'home:index'; 
-$conf['plugin']['indexmenu']['skip_index'] = '/(home|playground)/'; 
-$conf['plugin']['indexmenu']['skip_file'] = '/^:home:index.txt$/'; 
- 
- 
-Add to the beginning of '/home/so/public_html/dokuwiki2/.htaccess' (after 'RewriteEngine on') 
-the following lines (in case you want to enable HTTPS access to login and admin pages): 
- 
-# Switch to secure on login, profile and admin actions 
-RewriteCond %{HTTPS} !on 
-RewriteCond %{QUERY_STRING} do=(log|profile|admin) 
-RewriteRule ^(.*) https://%{HTTP_HOST}/so/wiki2/$1 [R,QSA,L] 
- 
-# Change back to non-secure on show action 
-RewriteCond %{HTTPS} on 
-RewriteCond %{QUERY_STRING} (do=show|^$) 
-RewriteCond %{REQUEST_METHOD} GET 
-RewriteRule ^(.*) http://%{HTTP_HOST}/so/wiki2/$1 [R,QSA,L] 
-</code> 
-# Add {{{local.php}}} configurations as mentioned in previous output. 
-#* The reason they are not added automatically is the current user may not have access to the {{{local.php}}} file (as it is created by the web server through the {{{www-data}}} user). 
-#* In case of no rights (the {{{www-data}}} user creates the file) use DokuWiki's web administrative interface: login, use the {{{Admin}}} button and then the {{{Configuration Settings}}} link. You should have no problem identifying the required web interface directives. 
-# Congratulations! You've got a basic DokuWiki installation with pretty slash based URLs 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 == 
-=== HTTPS Access === 
- 
-* In case you want HTTPS access, add the configuration lines mentioned in the output message of the {{{post_install_dokuwiki}}} script to the {{{.htaccess}}} file in DokuWiki's installation folder. 
-* Make sure you add them after the {{{RewriteEngine On}}} line and _before_ the other [[http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html|mod_rewrite]] lines (used for pretty URLs). 
- 
-=== 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/git/?p=admin.git;a=blob;f=dokuwiki/samples/dokuwiki-ldap-auth-swarm.conf;h=f955588a13f1ea8424d75f042cccb27ae623ace3;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. Unfortunatelly there is no web interface for LDAP authentication configuration. The simplest solution is asking the system administrator to give you access rights to that file. 
- 
-==== Disable Register Action ==== 
- 
-In case you choose to use LDAP authentication, you should disable the Dokuwiki's {{{Register}}} option, enabling users to automatically create an account for DokuWiki plain authentication. This can be accomplished by two means: 
-# use the {{{$conf['disableactions'] = 'register';}}} 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. 
- 
-In order to provide split authentication, do the following: 
-# Download the [[http://lastweekend.com.au/ggauth.4.zip|experimental authentication backends]] and unpack them in DokuWiki's installation folder (as mentioned [[http://www.dokuwiki.org/auth:ggauth#installation|here]]). 
-# 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:Razvan Deaconescu:x:admin,so 
-oana:x:Oana Baron:x:so 
-ddvlad:x:Vlad Dogaru:x:so 
-dbaluta:x:Daniel Baluta:x:so 
-apitis:x:Andrei Pitis:x:so 
-bdrutu:x:Bogdan Drutu:x:so 
-catalinme:x:Catalin Moraru:x:so 
-[...] 
-</code> 
-#* The {{{MD5password}}} and {{{email}}} fields are provided by the LDAP authentication engine and aren't filled. This may also hold true for {{{Real Name}}} but I didn't check. 
-# 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 steps below have been undertaken during an actual upgrade. 
-# Backup the previous DokuWiki folder<code> 
-$ cp -a wiki/ 2009-12-30-wiki-bak 
-</code> 
-# [[http://www.splitbrain.org/projects/dokuwiki|Download]] a new version of DokuWiki. I'm upgrading to the [[http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2009-12-25.tgz|current stable version]].<code> 
-$ wget http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2009-12-25.tgz 
-$ ls 
-2009-12-30-wiki-bak  dokuwiki-2009-12-25.tgz  lab  wiki 
-</code> 
-# Unpack the DokuWiki archive.<code> 
-$ tar xzf dokuwiki-2009-12-25.tgz 
-$ ls 
-2009-12-30-wiki-bak  dokuwiki-2009-12-25  dokuwiki-2009-12-25.tgz  lab  wiki 
-</code> 
-# Copy new files over the old wiki installation. Overwrite existing files.<code> 
-$ cp -rf dokuwiki-2009-12-25/* wiki/ 
-</code> 
-# Do a check for [[http://www.dokuwiki.org/install:upgrade#files_to_remove|files to be removed]] and remove them.<code> 
-$ rm inc/lang/ar/wordblock.txt 
-[...] 
-</code> 
-# Check permissions, especially permission on {{{data/}}} folder (web user must have write access enabled). 
-# Update plugins. I'm upgrading the [[http://www.dokuwiki.org/plugin:googleanalytics|googleanalytics]], [[http://www.dokuwiki.org/plugin:include|include]], [[http://www.dokuwiki.org/plugin:displaywikipage|displaywikipage]], [[http://www.dokuwiki.org/plugin:creole|creole]] and [[http://www.dokuwiki.org/plugin:indexmenu|indexmenu]] plugins.<code> 
-$ cd lib/plugins/ 
- 
-$ wget http://cloud.github.com/downloads/tatewake/dokuwiki-plugin-googleanalytics/googleanalytics-stable.tar.gz 
-$ tar xzf googleanalytics-stable.tar.gz 
-$ rm googleanalytics-stable.tar.gz  
- 
-$ wget http://cloud.github.com/downloads/dokufreaks/plugin-include/plugin-include.tgz 
-$ tar xzf plugin-include.tgz  
-$ rm plugin-include.tgz  
- 
-$ wget http://cloud.github.com/downloads/tatewake/dokuwiki-plugin-displaywikipage/displaywikipage-stable.tar.gz 
-$ tar xzf displaywikipage-stable.tar.gz 
-$ rm displaywikipage-stable.tar.gz  
- 
-$ wget http://www.chimeric.de/_src/plugin-creole.tgz 
-$ tar xzf plugin-creole.tgz  
-$ rm plugin-creole.tgz  
- 
-$ wget http://samuele.netsons.org/dokuwiki/media/indexmenu.zip 
-$ unzip indexmenu.zip 
-$ rm indexmenu.zip 
-</code> 
-# Clean the workplace.<code> 
-$ rm dokuwiki-2009-12-25.tgz  
-$ rm -fr dokuwiki-2009-12-25/ 
-</code> 
-# <del>Write a script for the above steps. I've been too lazy to do it myself :-)</del> Use the [[dokuwiki#upgrade_script|script below]]. 
-=== Upgrade script === 
- 
-Our [[http://koala.cs.pub.ro/git/?p=admin-public.git;a=summary|administration Git repository]] now contains [[http://koala.cs.pub.ro/git/?p=admin-public.git;a=blob;f=dokuwiki/upgrade_dokuwiki;hb=HEAD | a Dokuwiki upgrade script]]. A sample run is shown below:<code> 
-elf:~/repo-admin.git/dokuwiki# ./upgrade_dokuwiki ~srisp/public_html/dokuwiki/ ~srisp/public_html/bak/ http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2009-12-25c.tgz 
- 
- * Downloading Dokuwiki from http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2009-12-25c.tgz ... done 
- * Unpacking Dokuwiki to /tmp//dokuwiki ... done 
- * Backing up Dokuwiki instance to /home/srisp/public_html/bak//dokuwiki-bak-2010-01-22 ... done 
- * Upgrading Dokuwiki installation in /home/srisp/public_html/dokuwiki/ ... done 
- * Cleaning up temporary files ... done 
-</code> 
- 
-Enjoy! 
tutorials/dokuwiki.txt · Last modified: 2020/07/20 09:16 (external edit)