Friki 2 Installation and Configuration

This document describes the licensing terms for the Friki software, how to install it, and how to configure and tune it to your needs once it is installed.

Licensing

This is the "free" version of Friki. It is copyright (c) 2002 Frank Carver, and licensed under the GNU Public License (GPL) version 2. If you wish to use the Friki software, in whole or in part, in an application or situation incompatible with the GPL, we are willing to consider other, less-restrictive, licensing terms. Note, however, that there may be a charge for this option. Please contact us at friki@efsol.com to discuss your needs.

Installation

Have you got the latest version?

The latest version of Friki is available from http://www.efsol.com/. If you got this software or this document from another source, please check that you have the latest version.

Have you got the right build?

Friki 2 comes in three builds, so it's important to make sure you have the right one for your system and your needs.

Both "OneDotFour" and "OneDotThree" support the full "classic" Wiki markup with the addition of the common "interwiki" syntax for linking to pages on other Wikis. They should immediately be comfortable for anyone who has used the original Wiki.

Quick Installation

If you are in a hurry, Friki 2 can be installed as quickly as you can copy a file!.

You will need a working Servlet Container or Application Server which implements at least version 2.3 of the Java Servlet API. Friki 2 has been tested on Resin 2, and Tomcat 4, and sticks to the specification, so it should work on all other compliant servers. Please let me know if you find a server it won't work on, but remember to check that you are using the correct Friki build for your system first.

All you need to do is drop the file "friki.war" into the "webapps" directory of your servlet container. Most smart containers should recognize the new application automatically, but you may need to restart the container if yours gets confused. Once the container has recognized, deployed and initialized the web application (which may take a few minutes), you should be able to view a page by appending friki to the URL of your server. For example, if I have a server at http://tomcat.efsol.com/, I can access Friki at http://tomcat.efsol.com/friki, or if you have a server at http://localhost:8080/, you can access Friki at http://localhost:8080/friki. Now you can view the existing pages, search, edit and create new pages to your heart's content.

That was straightforward, wasn't it!

Warning! However, there is one thing to beware of if you run Friki this way. Any changes you make or new pages you create will be stored in the "temporary directory" provided by the servlet container as part of the servlet specification. It's the only way to make an application work "out-of-the-box" like this, but it can be a little dangerous. The servlet API specification is vague about what should happen to the contents of this "temporary directory" if you reload or modify a web application. I can't control how your container behaves in this respect, and I'd hate to see a lot of hard work and information inadvertently lost if you upgrade or reinstall later. By all means run Friki this way to check it out, and see how it works, but I strongly recommend that you configure your installed Friki to use a different, more permanent, directory for your files before you use it "for real".

Configuration and Customization

All of the following configuration and customization instructions assume you have an "expanded" installation of the Friki web application "war" file. All files mentioned are relative to this expanded directory.

Almost all servlet containers expand each web application into its own directory when it is deployed. If your server doesn't automatically expand the deployed web application you will need to expand it yourself using something like "WinZip" or "jar". You should make sure that you expand the "war" to a subdirectory of a directory monitored by the server. Typically this will be the same "webapps" directory in which you placed the "war" file, so you could for example use jar xf friki.war friki.

Before you start modifying the expanded web application, you should remove the original "war" file from the webapps directory, to ensure you don't get any conflicts. This may require stopping the server.

Some servlet containers will automatically detect a change to web.xml or other files and reload the web application after your changes. For others you will need to restart the server.

To change where pages are stored

One of the first "customizations" you should consider is where the pages are stored.

  1. Find or make a directory which is unlikely to be deleted or messed with by another user or another system process. Make sure that it is both readable and writable by the user your servlet container runs as, and that it is initially empty.

  2. In the file WEB-INF/web.xml you should see a few lines like: 

    <init-param>
  <param-name>location</param-name>
  <param-value>*TMP*</param-value>
</init-param>
    The *TMP* is a special token which tells Friki to use the container "temporary directory". Change it to the full path to your chosen directory, and save the file.

  3. To ensure this has happened, look into your chosen directory. If your changes have been "noticed" by the server, a few default page files should have been created, including FrontPage and SandBox.

To create a new page

There is a small selection of pages supplied with Friki, but you are not limited to viewing and editing these pages. Creating new pages is very easy, and users should be encouraged do it in the normal course of using Friki..

  1. Use a web browser to navigate to a page which might make sense to contain a link to your new page. Any page will do.

  2. Edit your chosen linking page, and add a link to your new page somewhere. In most cases, all you need to do to make a link is type the name of the new page with the WordsPushedTogether.

  3. Commit the changes to the linking page, and you should see your new page link followed by a '?'. The '?' indicates a link to an unknown page.

  4. Clicking on the '?' will take you straight to an "edit" form for the new page. Replace the initial text with your own words and commit the changes. You now have a new page!

To delete a page

Sometimes you need to delete a page. In a live system, used by many people, you should think very hard before doing it, as it might easily break links on other sites. If at all possible, just remove (or move) the content of the offending page, and replace it with a note explaining what happened. I provide no way for casual Friki users to delete a page. Deleting a page is considered an admin operation.

  1. Find where the pages are stored. By default this will be the servlet container's "temporary directory". If you have changed it, it will be the directory listed in the "location" parameter as described above.

  2. Simply delete the page files you no longer need. In most cases this will be enough. If a page keeps coming back, it's probably because it is listed as one of the "initial files" required for a base installation. In this case you will need to change the initial pages as described below.

To change the default page

When you access friki without specifying the name of a page, it shows the configured "default page". As delivered, this is set to "FrontPage", which is a reasonable default for many uses, but might be inappropriate for yours.

  1. In the file WEB-INF/web.xml you should see a few lines like: 

    <init-param>
  <param-name>dflPage</param-name>
  <param-value>FrontPage</param-value>
</init-param>

  2. You may change the "FrontPage" to any valid page name. If it doesn't exist, Friki will create a fresh page for you to edit.

To change the initial pages

Whenever Friki starts up, it checks that a minimum set of basic pages are present. For the great majority of Friki installations, these will probably pose no problem, but if you need to change which pages are treated this way, you can.

It's important to note, however, that there are two types of initial pages: those that are just example content, and can easily be changed (by default these are FrontPage, PageFormatting and SandBox); and those which are used by Friki itself for logging (by default these are ReadRequests and RecentChanges). Changing the "example content" pages is simple and is described here. Changing the Friki logging pages is a bit more complicated, and should only be considered if these page names are really abhorrent. See "To change the way Friki logs pages", below.

To change the example content pages

  1. Go to the directory WEB-INF/classes. In this directory you will see several files without "file extensions" (if you are using a Windows system, make sure you have your explorer set to show, and not to hide, file extensions for this). feel free to rename or remove any of these files which are not configured as logging destinations, or add more.

  2. Edit the file WEB-INF/classes/dflPages.txt, and remove or rename any pages which you changed in step one, and match the new set of files present in the directory.

The next time Friki reinitializes, it will ensure that your real page store contains these initial pages.

To change the name of the application

I find it hard to imagine, but you may not want to offer an application called "friki" on your web site. If this is the case, you can call the application anything you like (within the limits of acceptable URL directory names).

  1. Stop your servlet container. Although there may be servers which can take an application being renamed in their stride, most can't. So I recommend stopping the servlet container just to be sure. You may also find that your servlet container maintains file locks on some of the files in the application, and won't let you change it while the server is running.

  2. Rename the expanded application directory to your chosen name. If you are still using the default "container temporary directory" for page storage, you may also need to move your pages to whatever temporary directory the server chooses for the new application name.

  3. Restart your server. Access Friki using your new application name.

To install more than one copy of Friki on the same domain

If you wish to install more than one Friki on your web site (for example, one for staff use, and one for customer use, or one for each of your product areas), you can't call both of them "friki". Follow the process described above in "to change the name of the application", but copy the directory rather than moving it. Remember to configure each Friki instance to use a different directory for page storage, or things may get very confusing!

Using this technique will allow you to install as many Friki's as you want.

To alter the page style

The default page style of Friki is functional but bland. You can easily change the page style, maybe to integrate with the "look and feel" of other pages on your site, or maybe just because you don't like it.

  1. In the directory WEB-INF/classes you will find three files: view.tpl, edit.tpl and search.tpl. These are the page templates used whenever Friki generates a web page.

  2. Each template may be any valid HTML page, however you wish to generate it. If you look at the original templates you will see patterns like @CONTENT@. These show where values from the loaded page will be substituted. In general, these are pretty straightforward: @TITLE@ gets the page title (the page name split into separate words for readability); @CONTENT@ gets the page content in a form suitable for display or editing as appropriate; @page.name@ gets the raw page name. @hardlines@ gets "true" if the page contains hard line breaks, or "false" if lines are wrapped into paragraphs. Note that the ALL-CAPITALS properties are worked out when the page is displayed, but any others are stored in the page files, and can be viewed or edited using a basic text editor.

To alter the button text

You can even alter the button text for the buttons "EDIT THIS PAGE", "SEARCH", "SEARCH AGAIN", and "COMMIT CHANGES". This is slightly more complex, and has two steps.

  1. Edit the appropriate template files as described above in "altering the page style" and change the button text to whatever you want (as long as the "EDIT..", "COMMIT.." and "SEARCH.." buttons have distinguishable text.) You can even get creative with buttonless forms and javascript image links if that's your thing.

  2. Then edit the file WEB-INF/classes/buttons.txt, and update it to contain your new button text on the left side of the appropriate '='. Note that this file is in "properties" format, so you will need to escape any unusual characters (commonly whitespace, '=', etc.) by preceding them with '\' escape characters.

To change the way Friki logs pages

By default, each time anyone views or changes a page, Friki logs it. This is usually very useful, as it allows users and administrators to discover which pages are popular, and what topics are active. Like many other aspects of Friki, this behaviour is also configurable. If you don't wish Friki to log pages, or you wish to change the page that the access logs go to, you need to add a new "init-param" to override the default behaviour.

To disable logging of page reads:

  1. In the file WEB-INF/web.xml, next to the other init-params, add a few lines like: 

    <init-param>
  <param-name>logReads</param-name>
  <param-value>false</param-value>
</init-param>

To disable logging of page changes:

  1. In the file WEB-INF/web.xml, next to the other init-params, add a few lines like: 

    <init-param>
  <param-name>logWrites</param-name>
  <param-value>false</param-value>
</init-param>

To change the page used for logging of page reads:

  1. In the file WEB-INF/web.xml, next to the other init-params, add a few lines like: 

    <init-param>
  <param-name>readLogPage</param-name>
  <param-value>your new page name</param-value>
</init-param>

To change the page used for logging of page changes:

  1. In the file WEB-INF/web.xml, next to the other init-params, add a few lines like: 

    <init-param>
  <param-name>writeLogPage</param-name>
  <param-value>your new page name</param-value>
</init-param>

Once you have added any of these init parameters, I suggest you delete or rename the existing log pages. If Friki tries to log to a page which does not exist or which does not have the "content.prefix" attribute set to "<pre>" and the "content.suffix" attribute set to "</pre>" you may not get the behaviour you are expecting.

To trim long logs:

As your Friki installation becomes popular, you will notice the log pages growing ever longer. After a while they may also get irritatingly slow to load and browse.

Trimming long log pages is actually simpler than it might appear. Both the read and change logs are stored as regular Friki pages, so to trim them all you need to do is hit the "EDIT THIS PAGE" button, and delete a bunch of old lines.

To update the "interwiki" site prefix list:

As part of the build process, every time Friki is compiled the latest copy of the official intermap.txt file is downloaded and included in the application. After a while the copy with your Friki might become out of date. If this is the case you can simply edit the file WEB-INF/classes/intermap.txt yourself. Alternatively you can download the lastest version of the master list and copy it over the local file.

You will need to restart Friki after updating this file.

Version 2.0.220 Nov 2002Frank Carver