Setting up Swiki

Swiki is a wiki written in the Squeak SmallTalk dialect. It’s easy to install, easy to maintain, and a great tool for maintaining documentation.

Documentation is a fact of life we have to deal with whether we like it or not. The word covers capturing valuable information and retrieving it in a timely manner. Any time I’m working on a book, an article, or a lecture I’m supposed to give, I need a place to store the information I find. The same goes for computers and networks I have to administer; one needs to document instead of memorizing. The person who introduced me to Unix always told me, “It’s not about knowing things by heart, but knowing where to find the information you need.”

One way to achieve this goal is to use a wiki to store and retrieve information> Wikis also enable more than one person to access and create documentation.

The Swiki software consists of three parts: a SmallTalk runtime, a Web server, and the software written in SmallTalk, stored in an image file called squeak.image. SmallTalk has no concept of programs; every application is a set of objects that are part of the base system, which in turn is just another bunch of objects. The latter bunch of objects is what you get when you install Squeak, the basic image containing every object required to make Squeak work. To execute the image, you use a runtime system called the Squeak VM. When you write a program in Squeak, you simply add objects to the image, which become part of the base image. To distribute the program, you can simply write out the differences between the base image and the image containing the added objects and distribute them. Another option is to strip out all objects not needed for the application and distribute the resulting image. All this means that a Swiki is self-contained. It does not require anything else to be installed on the computer, except an operating system and window manager.

Installing Swiki

Get the binary for your platform of choice from the Swiki site, move it to the directory where you want it to live, and extract the archive with tar -xvzf OneOfTheseDays-linux.tar.gz.

The result is a directory called ComSwiki, and most of the installation is now done. Let’s start the Swiki for the first time. Change into the ComSwiki directory and start the image:


cd ComSwiki
./squeak squeak.image


That’s it — the Swiki is up and running, almost. What you see is a running SmallTalk environment with the ComSwiki Launcher at the top. The tree buttons are pretty much self-explanatory. The port button allows you to set the port that Swiki will listen on; available ports are 80, 8000, 8080, and 8888. Once you’ve set the port, the start server button will start Swiki, and the save & exit button will save the settings you’re using and terminate the running Swiki.

I’ll use port 8888 for examples in this article. Start the Swiki and use a Web browser to connect to the Swiki at http://127.0.0.1:8888. Take your time, and play a little with the “refs” wiki that’s included with Swiki.

Configuration

After you’ve had some time to get used to Swiki, go ahead and create a new wiki. Creating a wiki is a series of simple steps. First, you’ll probably want to change the default username and password for Swiki. We need to log in to the admin interface of the Swiki at http://127.0.0.1:8888/admin. Connecting to this address results in an username/password dialog from the browser. The username is “admin” and the password is “password” — who would have thought of that? The Swiki was reachable from the outside world from the moment you started it, so you should change the password right away. Click on the button with the word Security beneath it to change the password. You’ll see the old username and password combo in the text box to the bottom right; change it to something suitable for you.

After that’s out of the way, create a new Swiki by clicking on the button with the word Create beneath it. We’ll try to keep this one simple (feel free to experiment later, though). Give it a name, set the parent to refs, and click “create new Swiki.” You may need to scroll down a bit, depending on your screen size.

You are greeted with a new page with the title Setup for the <name> Swiki. Leave the settings in the Inheritance section as they are, but change the Addressability section. Visible should be set to false, searchable should be set to false, and accessible should remain set on the default, true. Logging should be set to none. Click on update setup and your Swiki is ready. Click on the Go There button, next to Security, to work with your Swiki.

Using your Swiki

You should see a Web page with the name of your Swiki, and the sentence “Congratulations! This is a new Swiki.” The toolbar above the title is where you do all your wiki work. Let’s look at what the different toolbar items do.

• View is inactive because you are viewing the page right now, but otherwise it would take you to the page to view it.
• Edit allows you to modify the content of the page.
• Attach allows you to attach a file to the page.
• History lets you see the history of changes to this page.
• Home is inactive because you’re already on the first page of your Swiki.
• Changes shows the changes made to your Swiki.
• Search will take you to a search page for the Swiki.
• Help takes you to Swiki help pages for working with your Swiki.

Let’s modify the page and add a new page to our Swiki. Click on edit, and replace the sentence “Congratulations! This is a new Swiki.” with the following:

!My pile of Information
The Menu:
- *Interesting Links*
- *Unstructured*

Then click on the save button below the edit box. The exclamation mark denotes a heading, the hyphen denotes an unordered list, and a string enclosed in asterisks denotes a link. If the string http:// is absent from a link, then the link is considered internal and the Swiki displays a button to create the new page. There are two buttons on the modified page, one next to Interesting Links: and one next to Unstructured:. Click on the button next to Interesting Links: and a new page with the title Interesting Links will be created and put into edit mode for you.

Now that you know how to create a list of links, create some:


!OSTG
- *http://www.newsforge.com*
- *http://www.linux.com*
- *http://slashdot.org*


Click on save again and test your links. The markup is fairly simple, though not exactly like other wiki markup. The exclamation point creates a heading, while the dash tells Swiki to count an item as an element in a list. To insert a link to another site, use the asterisks to set off the URL. If you want the link to have a title, use a greater-than symbol (>) to separate the title and URL, like this: *Linux.com>http://linux.com/*. If you’re not sure of the markup, don’t worry — there’s a key at the bottom of the edit screen with common markup, and you can click on help -> Editing Rules from the Swiki toolbar to get the full scoop on Swiki markup.

Maintenance

Since the Swiki is up and running, it will eventually be filled with information you don’t want to lose. Every Swiki is stored in a directory inside ComSwiki/swiki/ with the name you gave your Swiki. You can back up your Swiki in several ways:

1. Copy the directory containing your Swiki — the one inside ComSwiki/swiki/ — to a safe location. I copied mine from my Linux box (where I created it) to my Mac, launched the Swiki on that machine, and was able to work with the Swiki again. The Swiki on the Linux box and the one copied to my Mac went out of sync, obviously.
2. Since the Swiki is self-contained, store the complete ComSwiki directory in a safe place or on a tape. If something goes south in a really bad way, all you need is a computer with the same OS to work with your Swiki again.
3. To render the contents of your Swiki to HTML, go to this address in your browser: http://127.0.0.1:8888/name_of_your_Swiki/render. A dialog requesting username and password shows up; use admin and password, and Swiki will generate HTML from your wiki. The files are stored in ComSwiki/swiki/name_of_your_Swiki/rendered/.

Option three requires a bit of explanation. First, why admin:password instead of the username and password combo we set as we started? Because every Swiki is able to use a different username and password for local administration. This combo is set from the AdminTool (http://127.0.0.1:8888/admin) by using the Settings button in the section Local Administration. Furthermore, you should test the results after Swiki generates the HTML — things may not be rendered the way you’d expect.

Conclusion

Using a Swiki for storing documentation and finding the information again is a quick and simple process. It usually takes me about five minutes, provided I have already downloaded the archives, to set up a working Swiki to cater my needs.

A Swiki can be used by more than one person at a time — if it is accessible from the network — so the documentation it contains is available to all persons involved, provided they have access to a Web browser. And last but not least: Using a Swiki is fun.

Erik M. Keller is the author of the “Unix/Linux Survival Guide” published by Charles River Media. He is a freelance consultant, and he writes for the German technology-blog Technovelty.de.