A couple of weeks ago, I had to set up a small web site for a new project
of mine. I’m sure that there are many other individuals or small
organizations with a tight budget and similar web publishing needs, so
here’s how I solved my problem.

Almost immediately, I realized that I could not know for sure how many
pages I would need or how they should be organized and interconnected.
Therefore, while I have no philosophical objections to hand-written HTML
pages, in this case, I would certainly need a content management
system (CMS).

The new web site would not need content ordered chronologically, online
fora or other (more or less interactive) “community” activities, with
the possible exception of allowing comments from casual visitors. This
made both powerful blogging systems like WordPress and full-blown
community portals like Drupal or Joomla unnecessary.

My conclusion was that I needed a wiki-style CMS. It should obviously be Linux-compatible and open source, but it should also not overload my server with yet another relational database if at all possible. After a bit of online research, I tried DokuWiki, and so far, I’m pretty pleased with the results.

DokuWiki is a simple but versatile wiki. It’s a good solution for cases like the one I just described, demanding only a web
hosting account with PHP support. In this post, I’ll explain step-by-step
how to install and start using DokuWiki. An upcoming post will provide some extra tips and an introduction to some of DokuWiki’s most
useful plugins.

Installation and configuration

DokuWiki is fairly simple to use, but first, you have to install it. Here’s how. The explanation below assumes that your wiki will be accessible from the Internet at wiki.yoursite.example.com and that $SERVER is the root directory of your Web server or of your hosting account.

  1. Download the compressed archive containing the latest version of dokuwiki into $SERVER
  2. Unpack that archive, which will create a directory called dokuwiki-version-number
  3. Make the Web server account the owner of the folder called data in the directory $SERVER/dokuwiki-version-number (and of all its subfolders)
  4. Modify the configuration of your Web server to make wiki.yoursite.example.com point to $SERVER/dokuwiki-version-number, and restart the server
  5. Point your browser to wiki.yoursite.example.com/install.php, and fill in the few necessary fields of the web forms that appear (Figure A) to perform the initial, mandatory configuration of your wiki

Figure A

Fill in the necessary fields of the web forms that appear.

That’s it! Just remove the install.php file to avoid malicious reinstallations, and you’re ready to log in as the user you defined above and start adding content.

Don’t worry, it’s much easier than it seems. Of course, the single steps may assume slightly different forms depending on how your web space is configured, what kind of access you have to it, and your underlying operating system. With root access on a Linux server via SSH, for example, step #3 above translates to typing this command in the $SERVER/dokuwiki-version-number directory:

#> chown -R apache:apache conf data

Also, step #4 above is not needed at all if the wiki address must be a subdirectory of some web domain (e.g. yoursite.example.com/wiki/) instead of an actual subdomain like wiki.yoursite.example.com/.

How does DokuWiki work?

DokuWiki is a file-based wiki. This means that it stores what you write
in plain text files, formatted with a simple markup language with rules that fit into a one-screen cheatsheet. This design choice has several interesting consequences.

The first, and probably the best, consequence for most users is that you don’t have to learn or type this language unless you want to. DokuWiki comes
with the built-in visual editor (Figure B) that lets you format
everything you need with a few clicks.

Figure B

DokuWiki comes with a built-in visual editor.

Of course, in order to use that editor, you have to create a blank page first. There are several ways to create a page — and while they all are simple, the one I prefer is to enter the title of my new page in
the search box in the top right corner, and then select Create this
page from the drop-down menu (Figure C) on the right edge of the window.

Figure C

Creating a page in DokuWiki.

The other, even more interesting consequence of choosing a file-based
wiki with plain text and simple markup is that you can generate, upload, or update its content in many ways.

If, like me, you’re already a fan of the txt2tags markup language, you can immediately create DokuWiki versions of all your writings by passing txt2tags through the “doku” target. Do that, copy and paste the result in the DokuWiki editor, and your wiki page will be ready and nicely formatted.

Dokuwiki is simple enough that, at this point, you could already profitably use it — but don’t forget…


Never, ever put something online that you care about without making sure that
it’s regularly backed up somewhere else. When it comes to DokuWiki,
its official backup page
has all the details, including links to relevant scripts and plugins,
but the critical part is pretty simple. Here’s how to quickly restore
your DokuWiki if something bad happens:

  1. Keep a copy of the original software archive that you downloaded from the web site
  2. Set up a script, cron job, or equivalent procedure that makes a daily
    copy of the folders and subfolders of your DokuWiki installation,
    which is where your pages and other content are stored:

data/pages data/meta data/media data/media_attic data/media_meta data/attic conf

If you want more details, don’t hesitate to ask for
them in the discussion thread below. Otherwise, check back next week for the second part
of this tutorial.