Installing DokuWiki is very easy - in general it’s just a matter of unpacking and setting permissions; however, detailed descriptions of various scenarios are given here.

• Step One: Download the newest release from the Download Page. This step is the same for everyone.

• Step Two: Follow the instructions pertaining to your specific platform below.

• Step Three: Look through Troubleshooting tips, which also contains additional setup notes.

This is the common scenario for installing DokuWiki in a corporate environment or on your own rootserver.

• make sure you have Apache and PHP installed (most GNU/Linux distributions come with packages for Apache and PHP) - make sure the versions are suitable for DokuWiki
• extract the tarball somewhere below your webserver documentroot eg:

#> cd /var/www
#> tar -xzvf /path/to/downloaded/dokuwiki-YYYY-MM-DD.tgz

• rename the directory if you like

#> mv dokuwiki-YYYY-MM-DD dokuwiki

• Create an empty logfile

#> touch dokuwiki/data/changes.log

• If you’re going to be using the access control (ACL) features, you need to create the users.auth.php and acl.auth.php files (just a user, TL What does TL stand for?)

#> cp dokuwiki/conf/users.auth.php.dist dokuwiki/conf/users.auth.php
#> cp dokuwiki/conf/acl.auth.php.dist dokuwiki/conf/acl.auth.php

• Set up the correct permissions
  • Usually the webserver runs as a unprivileged user eg nobody, www-data or apache
  • The webserver needs to be able to write to some files and directories (so change the chown nobody to match your configuration e.g. chown apache ...)
  • If you’re using access control, you need to change the group ownership permissions on the appropriate files and make them writeable by the web server user’s group (use group ownership, because as a user/web site admin, you’ll need to edit the files directly) - otherwise, users won’t be able to register, and you won’t be able to set ACL controls via the web interface, and you’ll get error messages; I always forget these steps when I do an install using ACL features, so that’s why I’m adding them here.
  • The group name the web server runs as is usually identical to the user name, except in the case of the “nobody/nogroup” and “wwwrun/www” combo - but check your server config just in case (just a user, TL)

#> chgrp nogroup dokuwiki/conf/users.auth.php
#> chgrp nogroup dokuwiki/conf/acl.auth.php
#> chmod 664 dokuwiki/conf/users.auth.php
#> chmod 664 dokuwiki/conf/acl.auth.php

#> chown -R nobody dokuwiki/data
#> chmod -R g=rwx dokuwiki/data 

• edit dokuwiki/conf/dokuwiki.php (see config) if you want to change anything within it. Better yet, create dokuwiki/conf/local.php containing those lines from dokuwiki.php which you want to change. This way, your changes are preserved when overwriting the dokuwiki.php with a new release. Next command can help you creating it. Delete those lines which you don’t want to change.

#> cp dokuwiki/conf/dokuwiki.php dokuwiki/conf/local.php

• finally, test if everything is set up correctly. Use the check option in a URL and pull it up into a browser: http://127.0.0.1/dokuwiki/doku.php?do=check

• if you’re using the access control features, you’ll need to set yourself up as an administrative user (either add your user account to the appropriate entry in the dokuwiki.php or local.php file, or put your account in the admin group you specified in these files), in order for the “admin” button to appear when you log in (just a user, TL)

• Occasionally chowning can be no good at all, I couldn’t chown files to another user on a server I was using, instead I chmodded my data dir.
• The options specified in .htaccess can sometimes cause an error. It gave me an ‘Internal Server Error 500’. I could not run any php code, no matter how simple. Comment out the <Files> section of .htaccess and check to be sure access to .ht* files is restricted in your httpd.conf (or other web server config) file.
• If you’re using Ubuntu (I use Ubuntu server 6.06, I don’t know about other versions), the user you should chown files and dirs to is www-data. Took me two hours to figure out what was wrong...
  • You could check the user and group your server is running as with PHP like this:

    <?php echo "<pre>User: " . exec("whoami") . "\nGroups: " . exec("groups") . "</pre>"; ?>

• If the RewriteEngine rules in .htaccess give you error 500, add RewriteBase /path where /path is the path to doku.php from your website’s URL.

Currently, DokuWiki is included in the unstable and testing distributions of Debian. To install, use the standard Debian procedure:

#> apt-get update
#> apt-get install dokuwiki

After unpacking, Debian’s configuration system debconf will ask a few questions about the preferred configuration.

Please use the Debian bug tracking system to report any bugs with the package http://www.debian.org/Bugs/. Note that to comply with the Debian policy the directory structure of DokuWiki has been reorganized. For example, the configuration files are located in /etc/dokuwiki/ .

To install dokuwiki using the FreeBSD ports tree, do the following:

#> cd /usr/ports/www/dokuwiki
#> make install clean

The default DokuWiki directory is /usr/local/www/data/dokuwiki
– Of course the directory can be changed or symbolic linked to anywhere
To configure dokuwiki copy the options from the /usr/local/www/data/dokuwiki/conf/dokuwiki.php file you want to edit to /usr/local/www/data/dokuwiki/conf/local.php.
If not done, then after a portupgrade your config will be changed to default.

To upgrade using the ports tree, do:

#> portupgrade dokuwiki

Make sure that the ports tree has been updated, or this will have no effect.

To install dokuwiki on Gentoo do

$> emerge --sync
$> emerge -a dokuwiki 

This will install dokuwiki in /var/www/localhost/htdocs/dokuwiki.

You should not forget to set up Apache (the web server) to support PHP. See http://gentoo-wiki.com/Apache_Modules_mod_php.

See the detailed HOWTO for DokuWiki on Tiger.

The HOWTO does not appear to be up-to-date (though it was helpful).

Below is what I did for Tiger (no previous DokuWiki installed):

1. Enable PHP on Mac OS X (includes starting Personal Web Sharing)
2. Downloaded dokuwiki-2005-07-13.tgz (assuming to ~/Desktop)
3. From the command line:

   $ cd ~/Desktop && tar -zxvf dokuwiki-2005-07-13.tgz
   $ mv dokuwiki-2005-07-13 ~/Sites/dokuwiki
   $ cd ~/Sites/dokuwiki
   $ touch data/changes.log
   $ sudo chown -R www data

4. If you want authorization (change useacl in conf/local.php), also from the command line:

   $ cp conf/users.auth.php.dist conf/users.auth.php
   $ sudo chown www conf/users.auth.php
   $ cp conf/acl.auth.php.dist conf/acl.auth.php
   $ sudo chown www conf/acl.auth.php

5. Important: set

   $conf['basedir']     = '/~user/dokuwiki/';

   in conf/local.php; autodetection does not work!

## in 10.4.3 client running the built in apache, but with site at /Library/Webserver/Documents (to mimic server) adding ‘basedir’ actually breaks it.

## The third-party Apache2 package runs as ‘nobody’, not ‘www’ – change your chown command accordingly

I got through installing Lighttpd, php5-fastcgi and DokuWiki, and it’s all working, but it required some rewriting of the rewrite rules, if you’ll pardon the pun.

Install PHP-FastCGI from the source, or use your distribution’s packages, which will probably be much easier. Once php-fastcgi is installed, follow the directions under the “Configuration” heading here: http://trac.lighttpd.net/trac/wiki/TutorialLighttpdAndPHP. You shouldn’t have to mess with the FastCGI settings a lot unless you really want to.

These are my settings:

fastcgi.server             = ( ".php" =>
                               ( "localhost" =>
                                 (
                                   "socket" => "/tmp/php-fastcgi.socket",
                                   "bin-path" => "/usr/bin/php5-fcgi"
                                 )
                               )
                            )

Then we need to add some custom rewrite rules

url.rewrite = (                 "^/wiki/_media/(.*)\?(.*)" => "/wiki/lib/exe/fetch.php?media=$1",
                                "^/wiki/_detail/(.*)\?(.*)" => "/wiki/lib/exe/detail.php?media=$1",
                                "/(.*)\.(.*)" => "$0",
                                "/(lib)/" => "$0",
                                "$^" => "/wiki/doku.php",
                                "/wiki/(.*)\?(.*)" => "/wiki/doku.php?id=$1&$2",
                                "/wiki/(.*)" => "/wiki/doku.php?id=$1",
				)

Some explanation is in order. Lighttpd does not use per directory .htaccess files, so any directory deny must be done at a higher level. This set of rewrite rules effectively does that.

• The first and second line allows are pretty standard rewrites.
• The third line allows requests for a file (something.ext) to go through unchanged
• The fourth line allows URL‘s that reference the listed directories to pass through. This is needed, for example, to load the CSS files from below the /lib tree. You can add more directory by making that first part “/(lib|other|dirs)/”
• The third and fourth lines are pretty standard rewrites
• The fifth line simulates an index
• The sixth line allows some of the special functions to work, like pressing the index button on a page, which goes to the URL ending in something like wiki:syntax?do=index

These are what I have so far. Feel free to make corrections to them, as I will if I find anything that isn’t working right.

This is for people who want to use DokuWiki on their Desktop-Machine

• Make sure you have Apache and PHP installed 1)
• Unpack the tarball using a tool like WinZIP, WinRAR or the opensource file archiver 7-Zip. See File extraction details below.
• move the dokuwiki-YYYY-MM-DD directory to somewhere below your new webserver documentroot eg. c:\xampp\htdocs\ and rename it to dokuwiki
• in the dokuwiki/data/ directory create a new empty file named changes.log (rightclick and select new → Textfile, then rename the file)
• edit the dokuwiki.php file in the conf directory to configure your Wiki (see config) or (better) create a new conf/local.php file containing those lines from dokuwiki.php, which you want to change. This way your changes are preserved when overwriting the dokuwiki.php with a new release.
• In the last version (2006-03-09) you will have to create the missing folder data/meta too. Users of older versions may also have to create data/cache, data/meta, data/locks. (look out for this)
• Your new Wiki should be available at http://127.0.0.1/dokuwiki/doku.php

Sometimes, you might require to create an attic/ directory under data dir. Thanks to oak to help me out with this.

This is for people who want to use DokuWiki on a Windows machine with IIS webserver (Windows 2000, Windows XP or Windows Server 2003)

• Make sure you have PHP installed. See the PHP site for installers or complete packages. PHP can run either as CGI-application or as an ISAPI extension.
• Unzip the DokuWiki archive using a tool like WinZIP or the opensource file archiver 7-Zip. See File extraction details below.
• Rename the dokuwiki-YYYY-MM-DD directory to dokuwiki and move it to
  • somewhere below your new webserver documentroot, e.g. c:\inetpub\dokuwiki
  • any other location on your machine, and make sure to setup a Virtual Directory mapping to that location
• In the dokuwiki/data/ directory create a new empty file named changes.log, and create the folders attic/, meta/, locks/ and cache/ This is no longer necessary as of version 2006-03-09 (and possibly earlier).

The above fixme note is incorrect. As of 2006/05/01 I had to create the changes.log and the meta/ folder manually. This file and folder were not included in the original .tar.gz file for dokuwiki.

I do not agree to “incorrect”. The word “This” may be understood wrong. You still have to create changes.log, but the directories are created automagically

• Edit the dokuwiki.php file in the conf directory to configure your Wiki (see config) or (better) create a new conf/local.php file containing those lines from dokuwiki.php, which you want to change. This way your changes are preserved when overwriting the dokuwiki.php with a new release.
• “Explore” to the dokuwiki/ directory and Check the properties of the data/ folder. Ensure that the Internet Guest Account (IUSR_computername) or the appropriate web server account has Folder level “Write” permissions to the data/ folder.
• Your new Wiki should be available at http://localhost/dokuwiki/doku.php

Windows-Users may need to rename the file from dokuwiki-YYYY-MM-DD.tgz to dokuwiki-YYYY-MM-DD.tar.gz to make their archive tool recognize the file format correctly (See 209).

The windows file extension is now .tar - however renaming it and using winzip works just fine.

Extraction Programs:

• Windows zipping and compression program, WinZIP
• Windows compression program, WinRAR
• Windows compression program, WinACE
• Opensource file archiver, 7-Zip
• For Windows and other platforms, free Ultimate Zip worked fine for me in unpacking dokuwiki.tgz.
• Use the amazing TotalCommander, it handles tgz and FTP perfectly.

NanoWeb is a PHP-based web server, and much lighter in its memory footprint than something like Apache. Nagios and Double Choco Latte both work fine, as does DokuWiki.

However, after following the instructions as described above for use with the Apache web server, it will be necessary to modify dokuwiki.php, as it does not automatically detect its web server location (URL).

Autodetection of an URL is not possible in all thinkable environments. Especially not when extensive URL rewriting and other forwarding mechnisms are in use. Furthermore the word “relative dir” is a bit missleading. Because dokuwiki requires an absolute pathname here. So start with a slash and end with a slash as in the example below. – Doogie - 27. May 2005

Change the line:

$conf['basedir'] = '';           //relative dir to serveroot - blank for autodetection

to something like:

$conf['basedir'] = '/dokuwiki/'; //relative dir to serveroot - blank for autodetection

Note that, for whatever reason, a trailing slash is required!!

This applies to most users of rented webspace.

A Screencast for this type of installation is available, too.

• Extract the tarball somewhere on harddisk 2)
• in the dokuwiki-YYYY-MM-DD/data directory create a new empty file named changes.log
  • Windows Users: rightclick and select new → Textfile, then rename the file.
  • Linux Users: In a terminal window, type: “touch changes.log” when in the data directory.
• edit the dokuwiki.php file in the conf directory to configure your Wiki (see config) or (better) create a new conf/local.php file containing those lines from dokuwiki.php, which you want to change. This way your changes are preserved when overwriting the dokuwiki.php with a new release.

• Now upload everything inside the dokuwiki-YYYY-MM-DD directory to your webhost using your favourite FTP-tool
• Go to http://www.example.com/dokuwiki/doku.php
• If you get the dokuwiki page, check your configuration by using the check option like this: http://www.example.com/dokuwiki/doku.php?do=check.
• Dokuwiki is now ready.

• Troubles may probably happen if your rented webspace is locking down the file permissions (which is a good thing )
• Check if your webhost have enabled ‘chmod’ command

Go to your favorite webhost configuration page example for free.fr or test CHMOD command thru your command line FTP or right clicking in Filezilla.

• You have a bunch of php warnings like this

Warning: session_start(): open(/tmp/php-ses/sess_215aaa2a389d6a10eee8c57939b486b6, O_RDWR) failed: No such file or directory (2) in /nfs/cust/6/36/44/644636/web/decuong/inc/init.php on line 53

• You should create a sessions folder in your user root directory (NOT the dokuwiki root)
• Otherwise, you could also create a /tmp directory and modify dokuwiki configuration to set this at the new session directory

1. Create a new directory tmp on /path/to/dokiwikidir (in my example is decuong/tmp)
   1. Chmod the new dir to 777
   2. Edit doku.php :

  // After the line:
  if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__)).'/');
  // Add:
  session_save_path(DOKU_INC.'tmp');

• You get : metadir does not exist or isn’t writable. Check config!
• If chmod command is enabled, the simplest thing is to change the permissions to rwxrwx— or 770 for the

dokuwiki/data/ directory and all files and directories below.

• Otherwise, create the following subdirectories in the dokuwiki/data/ : attic, cache, locks, meta, media (see also config)

• At last, you get the dokuwiki page , check your configuration by using the check option like this:

http://www.example.com/dokuwiki/doku.php?do=check.

• If you had any red warnings you may need to change some permissions using your FTP program

You can also check out the newest development version using darcs – see darcs for detailed info.

After you have followed the basic install instructions, your DokuWiki may have out of the box behaviour:

• It doesn’t work! You have to create a blank text file called “changes.log” and put it in /data with write permissions otherwise you get a “changelog does not exist or isn’t writable” error.
• The same problem occures with other directories! If you see “metadir does not exist or isn’t writable. Check config!” or “mediadir does not exist or isn’t writable. Check config!“, just create the appropriate subdirectory (media or meta) in /data. You can check other directory names by looking in ‘/inc/init.php’.
• If pages load unusually slowly 3) but don’t generate an error (unlike the previous item), this could also be caused by permission problems. Make sure the web server has sufficient access rights to all directories under /data. If you have limited access to the directory yourself (e.g. you installed DokuWiki on a hosted webserver and only have FTP access), try setting the permissions to /data and all its subdirectories to 775 or even 777. It might even be better to validate if you are suffering from php safemode, see wiki:safemodehack for more info. You also might need to configure $conf[’dmode’] = 0777; set directory creation mode
• No access control (see Authentication Options)
• Everybody can read, edit and contribute (see Permissionlevels)
• (Some of these problems (missing dirs and files, insufficient access rights) will hopefully be fixed in a future release) Proposition: put the nonexistent files and directories in the archive. It’s not possible? Or use files with one space char in them. Also, let the do=check action check for read/write access on all directories under /data.
• Blank pages? If you’ve edited a config file with .conf file extension, it needs to be saved in UTF-8 encoding, otherwise it could break your wiki, and even seems server dependent, works fine on some but not others. Resave the file with Free Crimson Editor or other UTF-8 friendly editor and upload and it should fix it if that was the cause.
• Help me. Everything above done (or tested). All the time I (xtravert[]wp.pl) see this:

Warning: include() [function.include]: Unable to access /home/s/o/s/sosml/www/lib/tpl/default/main.php in /home/s/o/s/sosml/www/inc/actions.php on line 103
Warning: include(/home/s/o/s/sosml/www/lib/tpl/default/main.php) [function.include]: failed to open stream: No such file or directory in /home/s/o/s/sosml/www/inc/actions.php on line 103
Warning: include() [function.include]: Failed opening '/home/s/o/s/sosml/www/lib/tpl/default/main.php' for inclusion (include_path='.:/usr/local/php5/lib/php') in /home/s/o/s/sosml/www/inc/actions.php on line 103

• I had a problem with Plesk 7.5.4 running on CentOS and had to go through the following steps. Files created and accessed by PHP are owned by ‘apache:apache’ but using CHOWN made no difference so I just CHMOD’d everything. This is my list of everything I needed to do beyond unzipping the tarball.

touch data/changes.log
chmod 777 data/changes.log
chmod 777 conf/acl.auth.php
chmod 777 conf/users.auth.php
mkdir data/meta
chmod 777 data
chmod 777 data/attic
chmod 777 data/cache
chmod 777 data/locks
chmod 777 data/media
chmod 777 data/meta
chmod 777 data/pages

Sergio - 13.06.2006 For shared hosting, this seems to be an essential step. Can you add information about security issues or different approaches to solve this problem? I think most of the dokuwiki users install the system on shared hosting services.

• Problems loading any template system on a shared hosting service. Any common solutions??

Before upgrading, you should always read the changelog to see if something changed you should be aware of when upgrading. To determine the version you are running, have a look in the HTML source of a Page generated by DokuWiki there should be something like <meta name=”generator” content=”DokuWiki 2005-02-06” /> 4).

Note for Windows Users: Remember to use an editor that saves in UTF-8 Unix format, such as Crimson Editor or Textpad.

The easiest way to upgrade is perform the following steps

• Move your old installation to a backup directory
• Install the new Version as described above
• Copy your changes.log and the contents of your data/ (perhaps not the wiki/ directory), attic/ and media/ directories from the backup location to the new install dir
  • As of 2005-07-01, ...
  • ... changes.log (which was in the root directory) is now in the data/ directory;
  • ... the user-created content that was in the data/ directory is now in the data/pages/ directory; and
  • ... the attic/ and media/ directories that were in the root directory are now under the data/ directory.
• Copy your old conf/local.php from the backup location to the new install dir
  • If you had originally edited .htaccess in the root directory for dokuwiki to have “nice URLs”, you should replace the overwritten file from the prior installation. (It’s a hidden file!)
• Copy your users.auth.php and acl.auth.php in conf/ if you use acl
  • These are new files for version 2005-07-13, so you’ll have to copy the contents of users.auth into users.auth.php and acl.auth into acl.auth.php.
• Try the doku.php?do=check to find out if permissions have changed. On a hosted wiki, the following error messages are evidence that you haven’t done chmod at the directory level (let alone the file level!)
  • Changelog is not writable
  • Datadir is not writable
    • This was because the data/pages/ directory was new for 2005-07-01
  • Attic is not writable
  • Mediadir is not writable
  • Cachedir is not writable

If you have made any changes on interwiki or smiley configurations or the source code itself, you will probably want to reapply them after upgrading.

When you upgrade from a version prior to 2005-02-06, you will need to convert your data to UTF8 after upgrading.

If you encounter some inconsistencies in DokuWikis behaviour after upgrading, you should delete the cache files in data/.cache/ and media/.cache/. You should make sure your browser hasn’t cached an old stylesheet, too.

Some reminders! I tried to upgrade from 2005-05-17 to 2005-07-13, and had problems with plain ACL. This has been discussed at http://wiki.splitbrain.org/wiki:discussion:acl?s=users%5C.auth#user_registration_-_can_t_register . I was in the process of reverted to 2005-05-13, and decided to give another try, which appears to have been successful. Two hints: (a) when transferring files over to the updated program directory, make sure that the chmod is set to 777 for all of them, or they won’t be editable! (In the Windows world, that means clearing the ReadOnly flag on files and folders. You may also need to make sure the right people/groups have read/write/full access in both Explorer and IIS —DGM2, 2006-03-02); and (b) when updating configuration files, remember to use a UTF-8 editor if you’re on Windows! (Such as Crimson Editor or Textpad.). {David Ing, 2005/07/17}

Example Upgrade Process

This method is not official - i (redeeman, visitor) just thought it would be nice to present this method of upgrade, which i just have used myself to upgrade from 2005-07-01 to 2005-07-13.

the thing i do, is to use diff, a command to generate a patch, this should be present on almost any unix system, however, it is probably also possible to find a win32 version on google.

now all we do to create the patch is to unpack the two different versions, so we get the dirs: “dokuwiki-2005-07-01” and “dokuwiki-2005-07-13” (this is the version change i did, your upgrade might be from/to different versions). now all we need to do is issue the diff command, and create the patch:

diff -Naur dokuwiki-2005-07-01 dokuwiki-2005-07-13 > doku.diff

now we have the patch, this is essentially only the differences between the two directories (e.g it knows nowthing of your pages, which is good) and you should be able to patch up, without it interfering with anything. however, you should note, that it might have changes in the conf/ dir in files you have edited, in which case you should do a backup of the file, copy the file from the version you already have, so the patch will work, and then when the patch is applied redo your changes, however this is only the case if changes to the dokuwiki standard php file is in an upgrade.

To check which files the patch will affect, you can run with –dry-run.. just cd into the dir where dokuwiki is installed, and run:

patch -p1 --dry-run </path/to/doku.diff 

then if you accept it :) just run it like this, without –dry-run:

patch -p1 </path/to/doku.diff

Example of everything needed for this

Here is what you may want to do when everything is up and working.

• Check the security page for hotfixes
• Consider enabling modrewrite
• Choose a license for your content – edit the footer.html inside the dokuwiki/lib/tpl/default folder to represent the appropriate license:
  • Creative Commons Attribution-NonCommerciaǒl-ShareAlike License V2.5 (included by default)
  • GNU Free Documentation License
• If using Apache, enable URL rewriting in .htaccess and set the appropriate config file option.
• Change the style.css to your own ideas
• Enter a few words how and where you use DokuWiki in the userpage
• subscribe to DokuWiki at freshmeat.net to stay informed of updates and get a mail whenever a security problem is encountered.

The topic of multi-wiki, or wiki farms, comes up briefly in freelists.org archives, in this thread, this thread, and this one. In the last one, Andi describes changes he made so $conf[’title’] can be used to establish different cookies for separate installations.

Note that namespaces could be used to separate content in a single installation. And multiple installation means each one will need its own upgrade. It is not the same as multiple instances sharing common code. Package upgrades, like Debian’s, will not handle multiple installations. But for some this is a price worth paying. Here is an approach that worked with the GNU/Linux installation using Apache. It can probably be adapted to the other situations:

1. Do the regular installation, and test it.
2. Create conf/local.php with the title line and any other lines you want to tailor.
3. Copy the folder “dokuwiki” and give it a name suggesting its content.
4. Set $conf[’title’] in local.php of new folder, to title and differentiate the installation.
5. If the new folder is named “newwiki,” bring up http://localhost/newwiki.

Do the first two steps once and repeat the last three to make multiple installations.

Another way to make it multi-wiki by whoo5) :

add follow line:

@ini_set("session.cookie_path", DOKU_BASE);

to init.php(inc\init.php) line 44. just follow
line 43:

 @ini_set('arg_separator.output', '&');

the make any copy as your wish. it’s that simple

.