Search:


Main.UbuntuPmWikiInstallation

Recent Changes
Printable View
Page History
Edit Page

PmWiki Installation on Ubuntu 7.10

PmWiki is a powerful, flexible but very minimal wiki software. PmWiki was created in PHP and stores it's contents as simple text files. This means you can very easily backup and restore your wiki-authored content without the fuss of setting up relational databases such as PostgreSQL or MySQL.

PmWiki supports a great subset of WikiMarkup, which allows very fast and easy authoring. It also allows file uploads, image insertion and login authentication.

This guide covers installing a PmWiki on an Ubuntu 7.10 machine.

What I like about PmWiki

  • No database software required - simple install, backup and upgrade.
  • Simple WikiMarkup - quick to author pages.
  • Text-file storage - easy to hack apart and automate or fix by hand. Fast.
  • Tiny distribution.
  • Minimal configuration required.
  • Lots of documentation.
  • Tons of cool ready made themes.
  • Easy styling with CSS and templates to make your own themes - match the rest of your site more easily.

Requirements

  • PmWiki requires PHP 4.1 or later, running through a PHP-capable web server such as Apache. If you have not installed Apache and PHP - follow the instructions found in the Ubuntu Apache Installation? guide first.
  • Security warning! Make sure your Apache installation has *.php files specified as a serveable file type, or else your raw PHP scripts will be downloadable by anyone! See the Ubuntu Apache Installation? guide for help on how to do this, specifically, the "Serving dynamic pages with PHP" section.
  • Your webserver will need write permission within the PmWiki directory if you want to be able to edit documents online.
  • Also, the web server must not place restrictions on file-format extensions.

Performing this task requires some command-line work, so be prepared to enter some cryptic commands into a terminal window. Don't be afraid - it's not so bad.

Download the software

Visit http://www.pmwiki.org and download the latest release of the wiki software. At the time of writing the current latest version is 2.2.0 beta 65, while the stable release is 2.1.27. I advise getting the stable release. PmWiki is available as a .tgz file and as a .zip file. Choose the tgz if you are installing on a Unix-based machine and a zip if you are installing on Windows.

Check requirements

Make sure you have a working webserver installed and running on the machine you intend to serve your Wiki. For this guide I presume you are using an Ubuntu 7.10 operating system with the Apache2 web server. This machine usually stores web pages in the following folder: 

	/var/www/

Anything placed in here is usually publicly accessible through the network. To allow your new Wiki to be browseable, it must be placed within this directory heirarchy.

Extract the archive

The file you downloaded contains all the scripts and data required to run the wiki from within a public web directory on your server computer. I placed the downloaded archive file in my home directory in a temporary location as such: 

	/home/chris/Setup/pmwiki-latest.tgz

You will extract the archive from here and then COPY the files into the public web directories later.

Browse to the /home/YOURNAME/Setup/ directory and then run the following command to unzip the archive: 

	gzip -d pmwiki-latest.tgz
  • "gzip" is the compression software (which is available on most, if not all linux systems).
  • "-d" is an options to decompress the archive named.

The .tgz file will be replaced with "pmwiki-latest.tar" which is an uncompressed "tarball" - a collection of files mashed together for easier management. We will have to "un-tar" this collection to retrieve the individual files within: 

	tar -xvf pmwiki-latest.tgz
  • "tar" is the program used to manage tarball files.
  • "-xvf" is a set of multiple options - the "x" part tells tar we want to extract files, the "v" part request verbose messages in case of errors, while the "f" part tells tar to extract from a named file, in this case "pmwiki-latest.tgz".

The tarball will be exploded into it's contituent files. These will be placed the same directory as the original .tgz archive. This might sound messy, but as per convention, most software packaged this way is placed in a top-level directory within the tarball, so you should now have only the original tarball and a folder with the same name containing all the extracted files.

Examine the wiki directory

Lets examine the contents of the wiki directory you've just extracted. Browse (using the file manager or your command console) into the /home/USERNAME/Setup/pmwiki-VERSION directory. (Replace USERNAME with your name and VERSION with whatever version of PmWiki you've acquired).

You should see the following folders and files (unless PmWiki has changed significantly since this document was written):

  • [cookbook]
  • [docs]
  • [local]
  • [pub]
  • [scripts]
  • [wikilib.d]
  • pmwiki.php
  • README.txt

Keep in mind that all these files will be copied to your web server directory later.

The file called "pmwiki.php" is the front page of the wiki. Once everything is set up, you can place a link to this page from your other website HTML pages to make it web-accessible.

The "cookbook" folder can contain "recipes" and howto information, although the version I recieved is empty to start with.

The "docs" folder contains brief documentation and licensing information. It also contains a template configuration file used to customize your wiki - this specifies editing options, skins or theme choices and other bits. This template will be edited to your specification and copied into the "local" directory where it will be activated.

The "pub" directory contains "publicly accessible files". This is where any file uploads usually go.

The "wikilib.d" folder contains the default bundled wiki pages. I find the name of this folder a little strange - usually service or "daemon" programs recieve a name with a ".d" at the end - this usually signifies that they run quietly in the background. This could be confusing for some.

Also, your wiki pages, the content you care most about, will be stored in a folder called "wiki.d", which you have yet to create...

Copy Wiki to public web server directory

Important Note: Before you perform the following - make sure you've read the Ubuntu Apache Installation? guide. If you don't perform some steps listed there, your web server will not properly serve PHP files needed by this wiki software, and this may lead to sensitive information or data being released into the wild...

Here we go: The entire wiki package needs to be placed in a directory reachable and serveable by your web server software. As mentioned before, on Ubuntu linux this is "/var/www/".

From the /home/YOURNAME/Setup/pmwiki-VERSION folder, execute the following: 

	sudo mkdir /var/www/wiki
	sudo cp -R * /var/www/wiki/

You will have to enter your password after at least the first command, in order to authenticate your request to mess with important "system" files and folders. These commands will create a new wiki directory and then copy your extracted wiki scripts (from your current location) and data into the newly created folder. Be careful not to copy anything that you don't want publicly acessible into these folders...

Create and prepare content directories

You need to create a folder within the PmWiki web directories where your custom wiki pages will go. Create a directory called "wiki.d" in the same location as the "wikilib.d" and "pmwiki.php" files are found: 

	sudo mkdir /var/www/wiki/wiki.d

Note again that we are creating the directory in the web-accessible directory structure - where we copied the wiki files, not where we originally extracted them.

Set up permissions

You will need to set up these directories to be writable by the web server, otherwise you will not be able to edit and change wiki pages while on-line. To do this, make the permissions for the "wiki.d" directory (the one you've just created - "/var/www/wiki/wiki.d") equal to 777: 

	chmod 777 /var/www/wiki/wiki.d/

There are more secure ways of doing this (but the above method gets around cheap webhosting "PHP safe mode" setups, which can sometimes prohibitively lock down directories, making web apps unuseable) - see the offical website for more info.

If you are manipulating these files via ftp or remote shell access, rather than on an in-house webserver the procedure may be more involved. Be careful not to provide more permissions than you need - you might over-compromise the security of your machine.

Test the installation

See if you can browse the fresh wiki pages via a web browser - presuming you are setting up the wiki on a local web server machine, browse to the following URL: 

	http://localhost/wiki/pmwiki.php

Hopefully you should see some introductory PmWiki pages. The PmWiki distribution contains the entire set of help documentation within it, so you can learn all about customizing and configuring the software from your own web server. You will hopefully be able to edit your wiki pages by clicking the "edit" link found somewhere on each page. You can even edit the documentation pages mentioned above.

Initial Setup Tasks

Next up you can customize the configuration of your wiki. This is done through a file called "config.php" which must be located in the "local" subfolder of your wiki installation.

This file does not exist by default - you must create it by copying a template from the "docs/" directory and editing it to suit your needs. At a minimum you may want to specify the title of your wiki, the admin password and possibly a favoured skin/theme.

Once your wiki is copied into the web-accessible directory, the configuration template should be found at: 

	/var/www/wiki/docs/sample-config.php

Copy the template to make the true configuration file: 

	sudo cp /var/www/wiki/docs/sample-config.php /var/www/wiki/local/config.php

Then edit it to match your needs. Lines starting with '#' are comments and are ignored. Open the file in a text editor with the following command: 

	sudo gedit /var/www/wiki/local/config.php &

Within the file, the directives you most probably want to edit and uncomment are the following:

Note that paths should not have a trailing "/" character.

Hints

The PmWiki developers recommend NOT renaming the "pmwiki.php" file to anything else (such as "index.php") even though it technically is the "root" wiki file. This would make upgrading more difficuly and error prone because the system has been designed so that simply overwriting the originally distributed pmwiki files will be all that is required to upgrade, leaving actual authored wiki content within the "wiki.d", "local" and "pub" directories untouched and safe.

Create a simple redirect file or PHP include to act as a index file if required.