Building a Documentation Wiki

The idea here is to build a documentation wiki environment that is structured enough to handle changes to the system from both the bottom-up and top-down. Using templates and a little ingenuity, we can achieve this with mediawiki.

Pre-Requirements

First thing’s first, get a system running with mediawiki. You will also need to add theDynamic Page List (DPL) plugin, Create Box plugin, and Input Box plugin. I would also recommend adding the following to lock out anonymous editing:

$wgGroupPermissions['*']['edit'] = false;

Clean URLs

Now for clean URLs. This is entirely optional, however I highly recommend it, as it will allow you to rid the index.php segment in your URLs which will generally make it links to the system a lot more attractive. Make sure that you have mod_rewrite enabled in Apache before attempting this, and that your vhost allows rewriting.

The additions are really simple. first, look for the following entry in your LocalSettings.php file:

## The URL base path to the directory containing the wiki;
## defaults for all runtime URL paths are based off of this.
$wgScriptPath       = "";
$wgScriptExtension  = ".php";

Now make it look like this:

## The URL base path to the directory containing the wiki;
## defaults for all runtime URL paths are based off of this.
$wgScriptPath       = "";
$wgScriptExtension  = ".php";
$wgScript = "$wgScriptPath/index.php";

# short urls
$wgArticlePath = "/$1";
$wgUsePathInfo = false;

Next we need to create a .htaccess file in the root of your wiki install. Here is what I was using:

RewriteEngine On

 # Don't rewrite requests for files in MediaWiki subdirectories,
 # MediaWiki PHP files, HTTP error documents, favicon.ico, or robots.txt

 RewriteCond %{REQUEST_URI} !^/(stylesheets|images|skins|scripts)/
 RewriteCond %{REQUEST_URI} !^/(redirect|texvc|index).php
 RewriteCond %{REQUEST_URI} !^/error/(40(1|3|4)|500).html
 RewriteCond %{REQUEST_URI} !^/favicon.ico
 RewriteCond %{REQUEST_URI} !^/robots.txt

 # Rewrite http://wiki.domain.tld/article properly, this is the main rule

 RewriteRule ^(.*)$ /index.php/?title=$1 [L,QSA]

You should be good to go at that point!

Templates

Now we will move to the templating. all of this was designed to work both bottom-up (e.g. host pages effect diagrams) and top-down (e.g. Templates effect layouts of the diagrams and host pages). Below are the templates that I am currently using:

• Template:Rack Diagram
  This is the template used to generate the racks.
• Template:Blade Configuration
  This template is for blade enclosures.
• Template:VM Configuration
  

  This template is for VM Servers.

• Template:Systems Frontpage
  This template handles the front-end for the hosts/racks/etc.
• Template:KB Article
  This template is for the knowledgebase articles
• Template:KB Frontpage
  This template handles the front-end for the knowledgebase.

Feel free to customize the templates as you see fit. They have already gone through several revisions just from my own uses.

Building the Frontpage

For the frontpage, you can make something as elaborate or as simple as you would like. I highly recommend using the following code for your frontpage until you come up with something better:

{|border="0" cellspacing="5" cellpadding="5"
!bgcolor="#d5d5d5" width="400"|Knowledgebase
!bgcolor="#d5d5d5" width="400"|Systems
|-
|{{KB Frontpage}}
|{{Systems Frontpage}}
|}

Personally I started to break out everything into sections in my own document wikis, however you never will know what you need until you start playing with it. I would also recommend building the navigation menu when you know what you want. To modify the nav menu, you have to have the SysOps role in your user, then navigate to Mediawiki:Sidebar and simply change the links until you feel happy with them.

Building-out Your Server Room

First we need to come up with a system of how we are going to name the racks so that they are unique. This is critically important, as this naming scheme is key to how everything links together. I typically use 3-letter city code, followed by the rack naming scheme at that location. For example, ChiRack1, Chi101, ChiR1a are all valid examples. You just have to make sure you commit to whatever you decide now, as changing down the road is painful at best.

Alright, now depending on how creative you want to get, you can build a top-down view of your location using a wiki table, or simply list your locations. This page should be linked in from the Template:Systems Frontpage template under the horizontal line. Just add links for each location you want in here. Also note that you can always add more later. Here is a simple example…

ChiR0101	ChiR0102	ChiR0103	ChiR0104
Walkway
ChiR0201	ChiR0202	ChiR0203	ChiR0204

{|align="center" border="0" cellpadding="5" cellspacing="5"
|bgcolor="#d5d5d5"|[[ChiR0101]]
|bgcolor="#d5d5d5"|[[ChiR0102]]
|bgcolor="#d5d5d5"|[[ChiR0103]]
|bgcolor="#d5d5d5"|[[ChiR0104]]
|-
|colspan="4" align="center"|Walkway
|-
|bgcolor="#d5d5d5"|[[ChiR0201]]
|bgcolor="#d5d5d5"|[[ChiR0202]]
|bgcolor="#d5d5d5"|[[ChiR0203]]
|bgcolor="#d5d5d5"|[[ChiR0204]]
|}

Next, we need to map each rack to the rack diagram. Simply click each link and type the following into each page:

{{Rack Diagram}}

Save each page and you should have a blank rack in each page now. Your now setup for the next stage:

Adding Hosts

Now I have been developing a script to help automate some of this for linux and Sun hosts, however that will be for another time. For now lets focus on manually inputting the systems sio you understand what is happening.

To create a new host, simply enter the name of the host and click create host on the front page. You should be taken to a page with the name of the host and bunch of empty feilds. Fill out the fields the best you can, and link whenever you feel appropriate. Here is how I created the example host you saw in the screenshot at the beginning of this article:

  IP Address : 192.168.1.1
 MAC Address : 0a:0b:0c:0d:0e:0f
    HostName : {{PAGENAME}}
    Location : Chicago
 Rack Number : [[Chi0101|Rack 1 Unit 10]]
          OS : FreeBSD 7.0
 Environment : [[:Category:Production|Production]]
    Hardware : [[:Category:Dell|Dell]] PowerEdge 1950
         CPU : 4x 2.32 Ghz Intel Xeon
         RAM : 2048 MB
   Hard Disk : 30GB Seagate Barracuda
   Serial No : 123456
     Contact : [[Person1]]
 2nd Contact : [[Contact Sheet]]
{{Host Information}}
===Description===
What is the purpose of the system.  Please give a few sentences.
Feel free to also add anything else you feel the need to add here as well,
Such as applications loaded, backup system, notation about issues on the box, etc.

[[Category:System]]
[[Category:Production]]
[[Category:Dell]]
[[Category:FreeBSD]]
[[Category:Chi0101.10]]

Now I want to stress that the way that the wiki become host-aware is simply by adding categories for each location that the host exists in. For example, the category Chi0101.10 tells the wiki that this machine exists in rack Chi0101 U10. if you had a multiple U server, you would simply add more categories for those locations. There is no limit to the number of places that an item may exist. Take advantage of this for things like patch panels, which really don’t need any info and can all be tied to 1 actual page for all the racks. The following example does just that; places the patch-panel in U43 on each rack.

This is a placeholder for a Patchpanel.
[[Category:Network Equipment]]
[[Category:Chi0101.43]]
[[Category:Chi0102.43]]
[[Category:Chi0103.43]]
[[Category:Chi0104.43]]
[[Category:Chi0201.43]]
[[Category:Chi0202.43]]
[[Category:Chi0203.43]]
[[Category:Chi0204.43]]

Things to Keep in Mind

• The wiki will only be as good as you make it. Be sure to add categories for whatever you feel you may need to check on, report on, or keep track of.
• You can never over-document, just under-document