Making Wiki

This post is about installing TWiki on OS X. It’s a pretty technical post, and rather longer than usual, but that is the price for accurate information.

These notes were tested on versions 10.6 and 10.7.

Why?

Wikis are great places to put research notes, and to make connected networks of pages on closely related topics. If you’re writing a novel, a wiki on the subject can turn into a comprehensive encyclopaedia or world book for your story.

You can create a wiki instance for your topic in cloud services like Wikia, but the information is going to be public there. So, you might find a wiki installed on your own computer may be helpful*.

Why TWiki?

TWiki is a lightweight wiki which is nonetheless powerful and flexible. There are many options for a wiki, but for personal use TWiki** has the following benefits:

  • file-based – many other wikis use a database to store the pages, which is one more layer of complexity that I at least don’t want to deal with on a day to day basis.
  • performs well – I used to recommend Kwiki because it was trivial to setup, but it was both much slower and lacked the features of TWiki. (Kwiki doesn’t seem to be maintained any more, anyway)
  • active – TWiki has an active community, so the software is still being updated. There are lots of options for additional feature modules if you want them.

So, that’s why you might want to install a wiki. On to what you need to install TWiki in particular.

Preqrequisites

You’re going to be doing some command line stuff, and some administrator stuff. You need to know –

  1. how to access Terminal, and how to type commands accurately. Command-line commands are precise and often rely on specific punctuation.
  2. what the admin password is on your machine (what you type when you do system updates)
  3. how to use a text editor – vim and emacs are powerful but we’re not doing anything complicated here so I’ll give the key presses for nano because it’s easy to navigate. If there is another text editor you feel comfortable with then feel free to use that instead.

These notes (which I first posted on Facebook, but I can’t find them anymore there) are effectively a targetted extract from these installation notes:

The changes should only affect the local web server on your Mac, but you’ll be using sudo on the command line which is a powerful tool: be sure you are typing commands correctly.

One last caveat: check the locations and contents of things. As noted in the header, these are notes on OS X 10.6 and 10.7 – older or newer versions may have things in different locations, and obviously other OSs will have things in completely different places***.

Command Line Commands

In these instructions you’re going to be using the command line. Commands you type are presented like this –

$> cd /tmp

… which means to type “cd /tmp” and then hit return.

Instructions

  1. turn on web server
    • open System Preferences
    • select “Sharing” (last icon on the “Internet & Wireless” line)
    • make sure the “Web Sharing” checkbox is ticked.
    • let’s just check that worked:
      1. open a web browser
      2. type http://localhost in the address field
      3. you should see a page. Default may be just “It works!”.
  2. download package from twiki.org
    1. you can enter your contact details or choose to skip the form
    2. download the “tgz” bundle
    3. expectation is that it will turn up in your Downloads directory
    4. eg Downloads/TWiki-6.0.0.tgz
  3. open Terminal – it’s in /Applications/Utilities, or type Cmd+Space to bring up Spotlight search and type “terminal”
  4. unpack the Twiki bundle in a sensible place. Let’s use /tmp
    $> cd /tmp
    $> tar -zxvf ~/Downloads/TWiki-6.0.0.tgz
    You should see lots of files being unpacked onto your system.
    $> ls
    You should see a directory called “twiki”
  5. move to web server directory
    You don’t want to run Twiki from /tmp, so we’re going to put it with the web server.
    $> cd /Library/WebServer/Documents
    $> ls
    You should see a few files including “index.html.en”.
    $> sudo mv /tmp/twiki .That ‘.’ on the end of the line means “here”, the current working directory. The “sudo” command will ask for your admin password.
  6. configure Twiki
    • fix directory permissions
      $> sudo chown -R www:www twiki
    • create Twiki config file
      $> cd twiki/bin
      $> sudo cp LocalLib.cfg.txt LocalLib.cfg
      $> sudo nano LocalLib.cfg
      Look for the line which starts “$twikiLibPath” and change it to read –
      $twikiLibPath = "/Library/WebServer/Documents/twiki/lib";
      Then type Ctrl+X, Y, and hit return to confirm the filename.
  7. configure web server
    TWiki is set up, but we need to tell the web server to load TWiki when asked to.First, get the config we need.

    • visit this page:
      http://twiki.org/cgi-bin/view/TWiki/ApacheConfigGenerator
    • enter the following value in “Full file path to your twiki root directory” –
      /Library/WebServer/Documents/twiki
    • click “No PHP installed” on the “Prevent execution of attached files as PHP scripts” radio button
    • click “Update config file”
    • click “Highlight text”, then copy (Cmd+C)
    • Now, put the configuration somewhere the web server will find it.
      $> cd /etc/apache2
      $> sudo nano other/twiki.conf
      Paste the config text (Cmd+V)
      Save and exit: type Ctrl+X, Y, return.
      $> ls other
      You should see a file “twiki.conf”, amongst others.
    • Now we need to test the config, and restart the web server.$> /usr/sbin/apachectl configtest

      You may see a warning “Could not reliably determine the server’s fully qualified domain name”, but just ignore that. Fix any other errors though.

      $> sudo /usr/sbin/apachectl restart

      TWiki should now load

    • even though we’re not quite done with config, let’s test that TWiki is there. Put this address into a web browser –
      http://localhost/twiki/
      You should see “Welcome to TWiki” and some links.
  8. configure TWiki
    • in a web browser, go to: http://localhost/twiki/bin/configure
    • enter and confirm a password for administration of the TWiki
      • note: this is separate from your Mac OS password. Use something else.
    • click “next” button
    • click “next” on the following page too.
      • you may see some warnings in “General path settings” and it is worth reviewing the guesses that the TWiki installer makes, but it guesses right in my experience.
    • click “Save”
      That’s the initial config. There are still a couple of things to fix up.
    • enter the TWiki admin password you just created.
    • click on “Store settings”, which will probably have errors
      • where it says “Error: /bin/grep was not found on your path”, add “/usr” onto the front of the text field.
      • there are two of these grep paths. Don’t touch any of the other parts of the command string.
    • click next
    • click Save
    • click “go to twiki front page”
  9. setup Twiki user
    Nearly there!

    • your Twiki install is functional, but in order to create pages you need to create a Twiki user.
    • click “Register” next to the “Twiki users” control
    • fill in the form. TWiki names are usually in the form “FirstnameLastname”
    • hit Submit
    • click on your WikiName link to go to your profile page.

Now you can go ahead and start creating pages:

  • type a wiki topic into the Jump field
  • create a topic home page
  • type in wiki links for things you want to turn into new pages, then click on them in the finished page.

[*] I will be talking about sharing wikis across multiple computers in a later post.

[**] and indeed Foswiki, which I had somehow missed and which is the spiritual successor to TWiki.

[***] Linux I might be able to help with depending on the distro; for Windows you’re on your own.

Leave a Reply