Episode #17 - Why you should use a Wiki

Loading the player...

About Episode - Duration: 13 minutes, Published: 2013-11-07

In this episode, I wanted to talk about why you should be using a Wiki for keeping track of internal documents, policies and procedures, as well as other information about your infrastructure, then in the latter part of the episode, we will cover how to install MediaWiki on a CentOS 6.4 box.

Download: mp4 or webm

Get notified about future content via the mailing list, follow @jweissig_ on Twitter for episode updates, or use the RSS feed.

Links, Code, and Transcript


In this episodes, I wanted to talk about why you should be using a Wiki for storing internal documentation, things like policies and procedures, tech notes, as well as other information about your infrastructure, then in the latter part of the episode, we will cover how to install MediaWiki on a CentOS 6.4 box, as well as a brief demo of how the application works.

So why is an internal wiki useful? Speaking from personal experience, before using a central wiki, I had information scattered all over the place, in my home directory, emails, shared network drives, post it nodes, and worst of all, stuck in my head, and a wiki gave me a central location, where not just me, but the entire company started to consolidate information, plus having everything in one place makes it easy to find and update documents.

I just wanted to illustrate the problem, and how using a wiki solves it. Before using a wiki, I would typically, work on a document locally, then email it out to various member of a team asking for feedback. You fairly quickly get burdened, as they each reply with an updated document, and their changes. Now it is up to me, to merge all of these things manually, and send out an updated revision, and the cycle continues, till eventually the final version goes to a shared drive, to live where no one will look at it! But, using the wiki model, I found myself publishing documents quicker, because I could write up a quick draft, send it out, and everyone else could just edit the document on-line! I think this leads to a much quicker feedback cycle, and if you ever need to find a document, the wiki has a great search function!

I should mention that I am using the term document pretty loosely here. When I talk about wiki documents, I am not talking about pages with documents attached, and referring to documents as the actual page. So, you essentially eliminate documents, and turn most things into internal wiki pages.

Rather than talk all about wikis, lets just go ahead and install MediaWiki on a CentOS 6.4 virtual machine, so that I can show you what it looks like in real life.

First, lets install the require dependencies, things like httpd, php, and mysql server, along with several supporting packages. Do not worry about copying any of these commands down, they are all listed in the episode nodes below.

yum install httpd php php-gd php-xml php-mysql mysql mysql-server

Now that we have those installed, lets start our mysql server, which will act as the database for our wiki. Since this is a fresh install of a mysql server, there was a bunch of output, letting us know that we should configure a root password. So, lets go ahead and do that. I am just going to copy this command, which basically says, use the mysqladmin command, connect as the root user, set the password, to new-password, as you can see here, I have updated it, with a longer password.

service mysqld start
/usr/bin/mysqladmin -u root password 'a4a6cb8b60695d718a902afaba4c2765'

Now that we have set the default password, lets go ahead and connect to mysql, so that we can configure a wiki database, along with a wiki user account, which the MediaWiki installer will use later.

mysql -u root -p

From here, lets just list the databases to get a lay of the land. Lets run, create database wiki. Then, lets just list the databases again, to verify. Great. Now, lets create a wiki user account, this step is not required, but I highly recommend it. This just gives us a little added security, say for example, if someone where to compromises this account, they should not be able to access other databases. So, in this command, I am saying, create user wiki at localhost and it will be identified by this password. Next, lets grant some permissions to this wiki user. This command says, grant these permissions, to the wiki database and all its tables, again to the wiki user. This allows us to give fine grained access to a specific account. Lastly, lets flush the privileges, and exit.

show databases;
create database wiki; 
show databases;

CREATE USER 'wiki'@'localhost' IDENTIFIED BY 'e1930b4927e6b6d92d120c7c1bba3421';

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES ON `wiki`.* TO 'wiki'@'localhost'; 

flush privileges;

exit

This next step is not required either, but I also highly recommend doing this if you are running your httpd and mysql servers on the same host. Basically, we are going to configure mysql to only listen for local connection and not allow any external access. This helps protect your mysql server from attacks over the network because it is not listening for any traffic.

Let me show you what I am talking about, lets run netstat -nap and pipe the output to grep LIST, we are looking for processes that are listing for connections. You can see that mysqld is listed here, and it is listening on all addresses on port 3306. We can restrict this to localhost by editing the /etc/my.cnf file. Under the mysqld section, lets add a key values pair called bind-address equals 127.0.0.1 or localhost. Next lets restart mysqld to see the updated settings. Then lets rerun the netstat -nap command to verify our changes. As you can see, the mysqld process is now listening for connection on localhost only, this means that nothing from the external network can connect.

netstat -nap | grep LIST
vi /etc/my.cnf
# add bind-address=127.0.0.1
service mysqld restart
netstat -nap | grep LIST

Lets make sure httpd and mysqld are started on boot. We can do this by running chkconfig –list mysqld and we will do the same for httpd. You will notice that in both instances they are set to be off by default. So, lets go ahead and change those, by running, chkconfig the service name, and on. Since we already started mysqld earlier to configure the database, it is already running, but lets start httpd now.

chkconfig --list mysqld
chkconfig --list httpd
chkconfig mysqld on
chkconfig httpd on
service httpd start

Now that we have httpd and mysqld sorted out, lets go ahead and download the MediaWiki software. I would normally recommend installing this via rpm, but there does not appear to be an up to date version available. I have provided the download link in the episode notes below. I am just going to copy this link, and then use wget in my terminal to download it.

wget http://download.wikimedia.org/mediawiki/1.21/mediawiki-1.21.2.tar.gz

So, now that we have it downloaded, lets move this over to /var/www/html/. Then lets go ahead and unpack it. The mediawiki directory has the incorrect owner and group so lets run chown to recursively change the ownership to the apache user and group. Then, as always, lets verify it worked.

mv mediawiki-1.21.2.tar.gz /var/www/html
cd /var/www/html
ls -l
tar xzf mediawiki-1.21.2.tar.gz
ls -l
chown -R apache:apache mediawiki-1.21.2
ln -s mediawiki-1.21.2 wiki

Now, this next step is up to your personal preference, I like to create a symbolic link from the mediawiki directory to a better known name, something like wiki. The reason why I created a symbolic is that the version information is preserved, so it is clear to anyone looking what version we are running, and if you want to upgrade, just unpack the latest one, and update the symbolic link. You will also see people using apache config files to set this redirect, but I like using this method.

One last thing before we start the MediaWiki install wizard. If you are running an iptables based firewall like me, then you will most likely need to add a rule to allow httpd traffic over port 80. We can do that by editing /etc/sysconfig/iptables, we can just copy this port 22 rules for ssh, and modify it for port 80. Then lets run service iptables restart to refresh the firewall rules. Then, lets verify the rules were updated, by running iptables -L -n again. Yup, looks like its working.

iptables -L -n
vi /etc/sysconfig/iptables
service iptables restart
iptables -L -n

Okay, now that we have all the plumbing figured out, lets fire up our web browser and connect to localhost. You will notice here, I am connected to localhost colon 8080, this is because I am using a virtual machine, but in your situation, this might be just localhost or the remote address of your server.

So, lets go ahead and navigate into our /wiki directory, which we configured using a symbolic link earlier. This looks promising, lets click the setup the wiki link. From this point on, we are working with a wizard that will help us configure the wiki. Lets go ahead and select EN as the language.

Next, we are given a run down of our environment, you would likely be prompted here if you forgot something, but since we installed all of the requirements, it says we can move forward with the install.

In this step, we are prompted to configure our database, lets just update these fields with our mysql settings from earlier. Database host, is localhost, database name, is wiki, database user, is also wiki, and then lets paste in our really long password, and then click continue.

These setting look good, I am just going to click continue.

Here we are prompted for the wiki name, and we can also specify who the admin user will be. For the wiki name, lets just call it My Wiki for now, then just fill in your details down here. If you are in a hurry, you can bypass the following steps, but let me show you what they look like.

Here we have the ability to specify various wiki options. First, you can define if this wiki will be open for everyone, think anonymous access, do people require accounts, or is it totally private. I am just going to select the Open Wiki option, but you might want something else.

Next you can define how email is handled, maybe include some additional extensions, or define a company logo, but I am going click continue to move forward with the install.

In this step it looks like the install populated the database, so lets hit continue again. Great, looks like the install was successful, we are prompted to download a file called localsettings.php, which we need to place in the /var/www/html/wiki directory. This essentially defines all of the settings which the wizard helped us define.

Lets go ahead and save this file, I am just going to change into that directory. Then lets populate the localsettings.php file. Lets just list the contents to make sure it was create. Looks like it worked. Lets head back to the browser, and click the enter your wiki link.

cat > /var/www/html/wiki/localsettings.php

Great, looks like its working. You will notice the interface looks exactly like Wikipedia, so it should be fairly easy to get used to. Lets quickly go over the common interface features, you can read, edit, and view the change history, along with search the wiki. Then over here you have your navigation links, these can be updated to better fit your company. You can also change the logo image via the localsettings.php file we just looked at.

Lets go ahead and edit the main page, lets just highlight all this text, and get rid of it. Lets create a new list with several topics that you will likely track via the wiki. Lets start with meeting minutes, then, how about project plans, and finally technical documentation, then lets save the page. It is really that easy to get going.

You can also view the change history for every page, but going to this view history tab. Down here, you will find a listing of all the changes, who made them, and when, along with a visual way to see what the changes were, lets have a look. As you can see we have the previous version on the left here, and then our new version on the right. Lets head back to the main page for a minute, so we created this listing, but none of these items go anywhere, so lets fix that by editing the page again.

We can create links by adding double brackets around text, or you can just highlight it and select this icon. Lets do that for each item, and then save the page. You will notice that the items are all in red now, this indicates that these are links, but the destination page does not exist yet. You can create the destination page, simply by clicking the link. Lets try this out for the meeting minutes page. I am just going to copy some text in here, this indicates a heading, and then down here, we have a itemized list of dates, these are some just example meeting dates, then lets save the page.

Now you can see we have out newly create meeting minutes page, with our nice heading, along with a listing of links. Lets head back to the main page again, you will see that the meeting minutes link is now in blue, and if we click it, we get out meeting minutes page.

That pretty much wraps up this episode, hopefully you will embrace using a wiki for managing your internal documentation. Especially now that you know they are so useful!