User Tools

Site Tools


nupusi:dokuwiki:install

Installation

Installing DokuWiki is easy - in general it's just unpacking and setting permissions. However a detailed description for various scenarios is given here.

The first step is the same for everyone: Download the newest release from the Download Page 1).

Note: 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). For Windows and other platforms, free Ultimate Zip. It worked fine for me in unpacking dokuwiki.tgz on Windows

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

  1. 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.
  2. 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'.
  3. no access control (see Authentication Options)
  4. everybody can read, edit and contribute (see Permissionlevels)
  5. FIXME (Some of these problems (missing dirs and files) will hopefully be be fixed in a future release)

GNU/Linux or Unix Server

With Apache Web Server

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
  • 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 …)
#> chown -R nobody 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.
  • 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

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. also the Options Specified in .htaccess can sometimes cause an error. rename or delete the .htaccess file and the error will solve itself.

==== With NanoWeb Web Server ====

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!!

Mac OS X with Apache

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. Important: set
    $conf['basedir']     = '/~user/dokuwiki/';

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

Debian GNU/Linux

Official Debian Packages, provided by Matti Pöllä, can be fetched with apt from the testing and unstable sections. Homepage for this .deb is http://packages.debian.org/unstable/web/dokuwiki. To install DokuWiki, use the standard Debian procedure:

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

The package is unpacked, debconf asks a few questions, and it is set up. Invoke dokuwiki through your browser. For example, if you said the web-accessible location should be /dokuwiki, and access should be by localhost only, http://localhost/dokuwiki will bring up the start page.

Use the Debian bug tracking system to report any bugs with the package http://www.debian.org/Bugs/

– Where does debian put the data dirs?

– This might help to locate the data directories.

http://packages.debian.org/cgi-bin/search_contents.pl?searchmode=filelist&word=dokuwiki&version=unstable&arch=all

FreeBSD

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 upgrade using the ports tree, do:

#> portupgrade dokuwiki

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

Windows

With Apache

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

  • Make sure you have Apache and PHP installed 2)
  • Unpack the tarball using a tool like WinZIP or the opensource file archiver 7-Zip
  • 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.
  • Your new Wiki should be available at http://127.0.0.1/dokuwiki/doku.php

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

In the last version (2005-07-01) you have to create those directories too : data/cache, data/meta, data/locks.

With IIS

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
  • 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/
  • 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.
  • Your new Wiki should be available at http://localhost/dokuwiki/doku.php

Hosted Server with FTP access

This applies to most users of rented webspace.

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

  • Extract the tarball somewhere on your local host 3)
  • 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.
  • 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.
  • create the following empty sub-directories under data: attic, cache, locks, meta (media?)
  • Now upload everything inside the dokuwiki-YYYY-MM-DD directory to your webhost using your favourite FTP-tool
  • Depending on how your provider configured your FTP-Access DokuWiki may work already – to check it use the check option like this: http://www.example.com/dokuwiki/doku.php?do=check
  • If you had any red warnings you need to change some permissions using your FTP program
    • The option to do so is mostly called chmod and is sometimes hidden somewhere in the menubar or can be accessed via right click
  • The simplest thing is to change the permissions to rwxrwxrwx or 777 for the dokuwiki/data/ directory and all files and directories below.
  • :!: You may want to try the permissions of rwxrwx--- or 770 first – it is more secure but for most webhosters this will not work.

Development Versions

You can also check out the newest development version using darcs.

Upgrading

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).

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!; and (b) when updating configuration files, remember to use a UTF-8 editor if you're on Windows! (I use Crimson Editor). {David Ing, 2005/07/17}

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 user.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 user.auth into user.auth.php and acl.auth into acl.auth.php. If you're using Windows, remember to use an editor that saves in UTF-8 Unix format, such as Crimson Editor.
  • 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.

Example Upgrade Process

Easier/Faster upgrade method

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 not, 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 </path/to/doku.diff --dry-run

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

It Works - What Now ?

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

Multiple Wiki

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.

1)
The newest release is at the bottom
2)
The easiest way to do this is using an installer package like Uniserver, XAMPP, AppServ, EasyPHP or any other available
3)
Windows-Users can use a tool like 7-Zip
4)
if not your version is older than 2005-01-14
nupusi/dokuwiki/install.txt · Last modified: 2008/12/06 13:57 (external edit)