A TWiki setup with lighttpd

6 Apr 2013

1 Set up lighttpd
2 Set up TWiki
3 Editing topics
4 References

How to set up a local TWiki with lighttpd? Recipes covering the lighttpd configuration, the TWiki setup, security aspects and some general nifty TWiki tricks.

1 Set up lighttpd

You will not be able to set up FastCGI before configuring TWiki because it involves running a script along the same lines of twiki/bin/view which requires to deal with an already configured TWiki. Therefore, we'll need to start with a regular setup. Create a lighttpd.conf file, following Andrew Pantyukhin's discussion about TWiki on Lighttpd:

server.modules += ("mod_access")
server.modules += ("mod_rewrite")
server.modules += ("mod_cgi")

server.bind = "127.0.0.1"
server.document-root = "/path/to/twiki"
server.port = 3000

mimetype.assign = (
  ".html" => "text/html",
  ".txt"  => "text/plain",
  ".css"  => "text/css",
  ".jpg"  => "image/jpeg",
  ".png"  => "image/png"
)

$HTTP["url"] !~ "^/(bin|pub)/" { url.access-deny = ( "" ) }
$HTTP["url"] =~ "^/bin/" { cgi.assign = ( ""  => "" ) }
url.rewrite-once = ( "^/($|([A-Z].*))" => "/bin/view/$1" )

Setting server.bind as shown here should make the site available only from localhost. Note that you also need to add ".css" => "text/css" in order to use the TWiki style sheets and render pages properly.

2 Set up TWiki

2.1 Install TWiki

You may want to just follow the TWiki Installation Guide. In particular, you'll need to make a copy of LocalLib.cfg into bin in which $twikiLibPath needs adjusting. You'll probably be able to skip the Apache-related notes. Protecting the configure script is also something that we do per se by virtue of server.bind = "127.0.0.1" and appropriate iptables rules.
Start the server with lighttpd -f lighttpd.conf -D.
Go to http://localhost:3000/bin/configure. The page will be on about not being able to find twiki/lib/LocalLib.cfg but that's probably fine because I suppose it's automatically going to be copied over to there from twiki/bin. Enter a sensible password – note that it'll be encrypted.

Quite a number of warnings will further be reported, but that's mainly in order to draw your attention to settings which should have been guessed right anyway.
Once you have taken care of the General Path Settings you may go to the TWiki.WebHome, then back to http://localhost:3000/bin/configure to finish configuring. There's a number of settings you may want to adjust:
1. Set SaveEnvPath, not so much for safety reasons but because lighttpd uses an empty PATH environment variable and will therefore not be able to find diff.
2. Consider unchecking EnableNewUserRegistration.
3. Choose the crypt-md5 Encoding.
4. Consider checking DisableEmail.
After the General Path Settings have been taken care of a message will suggest to make LocalLib.cfg read-only next time you go to http://localhost:3000/bin/configure.

2.2 Define the administrator

We need to define an administrator user and that's done in Main.TWikiAdminGroups as explained in Define the Administrator User(s) section of the TWiki Installation Guide. Follow the instructions in the yellow area.

2.3 Security, authentication

Our lighttpd setup should cover the security issues mentioned in the Important Server Security Settings section of the TWiki Installation Guide. You'll want to make sure authentication has been enabled, though, as explained in the Enable Authentication of Users section. Embarrassingly enough, it seems impossible to have an administrator register a user so you'll have to temporarily check Enable_Authentication_of_Users again in http://localhost:3000/bin/configure before registering on TWiki.TWikiRegistration.

It's fine to provide both your first and last name as TWiki.WikiName. Although your e-mail address is requested (and you should probably supply one that's @localhost) and although it's stated otherwise, no mail should be sent to you since we checked DisableEmail. Don't forget to uncheck Enable_Authentication_of_Users again once you're done.

2.4 Creating a web and sealing it off

Adding a new web is done in TWiki.ManagingWebs. It's usually a good idea to base it on _default. Leave it in the site map and don't hide it. Since we want this web to only be accessible to logged-in users, we need to change access control. That's documented in the Controlling access to a Web section of the TWiki Access Control documentation. You need to go to each web's TWikiPreferences topic (except for the TWiki one) in order to set ALLOWWEBVIEW, ALLOWWEBCHANGE and ALLOWWEBRENAME to whomever you want to access these webs. This will infer everyone else is denied access. Note that as soon as you do so for Main.TWikiPreferences, the whole of TWiki will be sealed off.

2.5 Internationalisation

You can turn on what is called content internationalisation to use Unicode. In a nutshell you need to browse to http://localhost:3000/bin/configure, Localisation, tick {UseLocale}, set {Site}{Locale} to en_US.utf8 and {Site}{CharSet} to utf8 as explained in Installing TWiki with Internationalisation support (I18N).

2.6 WikiWord auto-linking

If there's anything that 6 months of using TWiki intensively taught me, is that auto-linking isn't a good thing:

I use many words spelled like WikiWords which I usually don't want turned into links;
It messes up links and header when internationalisation is enabled.

You may have nonetheless been using auto-linking a lot, and now wish to hunt down where throughout your TWiki to fix it or get rid of leading !s which you won't need anymore. The TWiki.WikiWord topic formally defines what a WikiWord is and it will let you turn it into a regular expression you can use grep against:

grep --color -E '[[:upper:]]+[[:digit:][:lower:]]+[[:upper:]]+[[:alnum:]]+' *.txt

Note that the [A-Z]+[0-9a-z]+[A-Z]+[0-9A-Za-z]+ pattern doesn't work because of a bug. Since you're probably going to find matches in every single topic, you might as well use the [A-Z]\+[0-9a-z]\+[A-Z]\+[0-9A-Za-z]\+ pattern in Vim. Then, use grep to hunt down files with WikiWords prefixed with an exclamation mark.

2.7 Explicit numbering

The ExplicitNumberingPlugin is a flexible solution for displaying section numbers. Such a plugin is particularly desirable in TWiki because the default style makes it hard to tell sections from subsections. There's a lot of debugging information logged by default, which you may want to comment out.

2.8 CSS

The PatternSkin CSS Cookbook offers a description of how you can tweak the TWiki CSS e.g. to improve the looks of listings. Here's a simpler approach still:

The documentation suggests to create a new topic only for this purpose. But clearly, any existing topic will do too. All that matters is that you create an attachment of a style sheet.
Create a CSS file, e.g. called style.css as suggested.

Add to your %WEBPREFSTOPIC% a line looking like:

   * Set USERSTYLEURL = %PUBURLPATH%/%WEB%/TWikiSetup/style.css

You might even be wondering whether even attaching the style sheet to an existing topic was all that useful either, as linking it to some static contents elsewhere would probably have been possible too.

2.9 Search by relevance

There was the OrderSearchResultsMostRelevantFirst discussion about ordering search results listing the most relevant ones first – a rather useful feature. Clif Kussmaul came up with an elegantly simple an effective approach from which I got most of my inspiration:

<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%">
  <input type="text" name="query" size="32" value="%URLPARAM{"query"}%" />
  <input type="submit" class="twikiSubmit" value="Search" />
  <input type="hidden" name="table" value="1" />
  <input type="hidden" name="sortcol" value="0" />
  <input type="hidden" name="up" value="1" />
</form>
%SEARCH{ search="%URLPARAM{"query"}%" nosearch="on"
   header="| *Count*                            | *Topic*    | *Parent*    |" 
   format="| $count(.*?(%URLPARAM{"query"}%).*) | [[$topic]] | [[$parent]] |" 
}%

3 Editing topics

TWiki calls its pages topics. If, like in this particular use case, the intention is to use TWiki locally, you may want to consider editing topics directly on the filesystem, rather than using the raw or WYSIWYG editors in HTML forms. It's about editing with any editor you fancy topics which are kept as plain *.txt files under data/. True, if you do so, your changes will no longer be versioned, unless you embark upon working with *,v files with RCS too. However, is debatable whether versioning them is at all useful in a local use.

On the plus side, this approach lets you harness the full potential of your editor. It will be more comfortable too, as you will be able to open one window for editing and a browser for viewing the result, such that you'll be able to edit and see the changes side-by-side just by reloading the page without having to go back and forth all the time. And it'll be safer too, as your changes will be saved to disk immediately and you don't run the risk of losing them if something goes belly up with the server.