Sample Project
This is not exactly a step by step on how to install something. It is intended as a general guide to the thought process you'll go through to get something substantial installed. Although I have used a specific package for example purposes (in this case MediaWiki), it is not specific to any particular package.
Decide what you need
I know you're a hotshot programmer, with leet PHP or whatever skills. That's nice. Good for you. Resist the temptation to build something from scratch unless you just want to spend hundreds of hours on something that someone else has already done. Spend a few minutes looking to see if something already exists. I bet it does. If it's open source, you can take it and tweak it, add to it, and make it your own.
Pick which one is for you
There's probably not just one suitable project, there's probably lots of them. In the case of something common, there's probably dozens or hundreds. In some cases, like wiki engines, there's so many that it's hard to pick. Lucky for you, lots of people have this problem and there's probably some sites that review and compare the various packages. In this example, I have decided for example purposes I want a wiki. I typed "compare wikis" into Google, and the first hit I got was for WikiMatrix, which promises to "compare them all". It even has a "Wiki Choice Wizard" where you answer a few questions and it picks the right wiki engine for you. (I answered a few questions like "Is Open Source required?" and it came up with a short list of wikis. I decided to go with MediaWiki, the wiki engine that Wikipedia uses. It's a big, beefy, industrial strength, but not so friendly for newbies wiki engine. For sake of example (and because I want to learn it anyway) I picked MediaWiki. You should probably *NOT* pick MediaWiki if you just want a simple lightweight wiki engine.)
Read the instructions
Well regarded popular projects like MediaWiki have documentation. Really. Resist the temptation to just blindly Google for "install MediaWiki". Instead go to the project's web site and READ THE OFFICIAL DOCUMENTATION. If it turns out to be lame and useless, *then* go to Google and wander through thousands of lame hints. In the case of MediaWiki, on the home page is a link to installation. They have a full blown step by step installation guide. These guides can be a bit confusing. A lot of them, like this one, have two basic sections. There's a generic section, that takes you through a generic install on a non-distribution specific platform. It is good to read this quickly, just to see how much pain is involved. The second section has system specific instructions, where hopefully someone has specific instructions for your platform of choice. So for this example, I read the generic instructions, and then the Fedora instructions. Hmm, seems a bit intricate.
Make a backup
BEFORE you install something substantial, make a backup. If you are installing on a vm, make a snapshot. If you are installing on your vhost at your ISP, then back up everything with an rsync command.
# rsync -avh -e ssh porterg@hickory.he.net:/home/porterg/* . porterg@hickory.he.net's password: receiving file list ... done cron_worked logs -> /logs/porterg mbox Mail/ annon-ftp-old/ cgi-bin/ downloads/ downloads/apl.dump downloads/blue_bayou.zip downloads/mediawiki-1.14.0.tar.gz downloads/pivot_1403_full.zip <snip>
Find the pre-requisites. Install them. Make sure they work before you go any further.
So after I read the documentation (yes, I really read the documentation) it appears that the "LAMP" stack (Linux, Apache, MySQL, Perl/PHP/Python) is required. This is common for many projects. Since I my practice server is Fedora 10, I read the Fedora specific notes. I found that the helpful Fedora folks had a complete MediaWiki package named mediawiki. Imagine that. So a simple 'yum install mediawiki' installs MediaWiki and all the dependencies. I verified this by trying a yum-my install and saw that all LAMP prerequisites were installed. All you have to do after this is the post-configuration (which may prove complicated).
Since I am practicing for installing MediaWiki on my ISP, where I have to install all of this by hand without root access or yum, I will choose the hard road. Yow.
Verifying LAMP
Well, I assume you are using Linux. Okay, the 'L' is done :)
Hmm. Apache. Came stock on my Fedora test box. My ISP vhost has it already as well. Guess I don't have to mess with that much. You should verify the version number, though.
porterg@hickory:~$ apache2 <tab> <tab> apache2 apache2ctl porterg@hickory:~$ apache2ctl -v Server version: Apache/2.2.8 (Ubuntu) Server built: Jun 26 2008 07:04:49
My ISP has helpfully installed MySQL for me. All I had to do is figure out what the database name and password was. The ISP has a web page on using their MySQL with that exact info on it.
porterg@hickory:~$ mysql -u porterg -p porterg Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 10328622 Server version: 5.0.51a-3ubuntu5.4 (Ubuntu) Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql>
Well, so far so good (easy, even). My ISP hooked me up. Let's see what version of PHP is installed.
porterg@hickory:~$ php -v
PHP 5.2.4-2ubuntu5.4 with Suhosin-Patch 0.9.6.2 (cli) (built: Nov 25 2008 23:46:54)
Copyright (c) 1997-2007 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2007 Zend Technologies
with Suhosin v0.9.22, Copyright (c) 2007, by SektionEins GmbH
So the basic components of the LAMP stack appear to be installed on my vhost at my ISP. I'm going to hope that they have properly integrated and configured them for typical 'LAMP-Y' applications. Sometimes getting the LAMP components to play together is harder than getting the components themselves.
Installing
Since I'm doing the 'generic' install (not using yum), I have to make a directory under my web document root, get the package (in a tarball), and unzip the tarball into the directory.
The install docs say to use a 'short URL friendly' name like <apache document root>/w, not /wiki. Then they show you how to make an alias of /wiki to /w. They say this is better. I guess I'll go with that.
My apache document root is /home/porterg/public_html.
porterg@hickory:~/public_html$ pwd
/home/porterg/public_html
porterg@hickory:~/public_html$ mkdir w
porterg@hickory:~/public_html$ cd w
porterg@hickory:~/public_html/w$ wget http://download.wikimedia.org/mediawiki/1.14/mediawiki-1.14.0.tar.gz
--10:37:31-- http://download.wikimedia.org/mediawiki/1.14/mediawiki-1.14.0.tar.gz
=> `mediawiki-1.14.0.tar.gz'
Resolving download.wikimedia.org... 208.80.152.183, 2620:0:860:2:230:48ff:fe5a:eb1e
Connecting to download.wikimedia.org|208.80.152.183|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 10,122,254 (9.7M) [application/octet-stream]
100%[====================================>] 10,122,254 5.83M/s
10:37:33 (5.82 MB/s) - `mediawiki-1.14.0.tar.gz' saved [10122254/10122254]
porterg@hickory:~/public_html/w$ tar -xvf *gz
mediawiki-1.14.0/
mediawiki-1.14.0/README
mediawiki-1.14.0/serialized/
<snip>
porterg@hickory:~/public_html/w$ mv mediawiki-1.14.0/* .
porterg@hickory:~/public_html/w$ rm -rf mediawiki-1.14.0
So now I have the contents of the tarball in /home/porterg/public_html/w. The docs say make the config directory writable by apache.
porterg@hickory:~/public_html/w$ chmod 777 config
This is dangerous. Remember to chmod it back to something sane (755?) after the install.
Configuring
So assuming that you LAMP stack is functioning, and you have unzipped the tarball into some folder, now you have to configure the package. In the case of MediaWiki, they have made a happy web page for you to use to configure the wiki. Many packages don't do this, you have to manually configure some (many?) text config files.
So to continue with the MediaWiki example, point your browser at the wiki folder. Click on the link. Wow! This is pretty cool. The happy web page checks to see if the LAMP stack is configured. I see:
* PHP 5.2.4-2ubuntu5.4 installed
* Found database drivers for: MySQL
* PHP server API is apache2handler; ok, using pretty URLs (index.php/Page_Title)
* Have XML / Latin1-UTF-8 conversion support.
* Session save path (/var/lib/php5) appears to be valid.
* PHP's memory_limit is 128M.
* Couldn't find Turck MMCache, eAccelerator, APC or XCache; cannot use these for object caching.
* Found GNU diff3: /usr/bin/diff3.
* Found ImageMagick: /usr/bin/convert; image thumbnailing will be enabled if you enable uploads.
* Found GD graphics library built-in.
* Installation directory: /home/porterg/public_html/w
* Script URI path: /w
* Installing MediaWiki with php file extensions
* Environment checked. You can install MediaWiki.
Thanks, he.net! That was easy!
So I can see the config web page, and it seems happy. Now I have to answer some questions about name of the wiki, license, database connection details. Try to leave as many as possible default. You should have the database connection details from your ISP.
Click on the create link. Hey! It says it worked! Now it says:
Installation successful! Move the config/LocalSettings.php file to the parent directory, then follow this link to your wiki. You should change file permissions for LocalSettings.php as required to prevent other users on the server reading passwords and altering configuration data.
Yay! Okay. I moved and tweaked the file like so (also fixed the perms on the config dir):
porterg@hickory:~/public_html/w/config$ ls index.php index.php5 LocalSettings.php porterg@hickory:~/public_html/w/config$ mv LocalSettings.php .. porterg@hickory:~/public_html/w/config$ cd .. porterg@hickory:~/public_html/w$ ls -al LocalSettings.php -rw-rw-rw- 1 porterg users 4297 2009-05-03 11:16 LocalSettings.php porterg@hickory:~/public_html/w$ chmod go-rwx LocalSettings.php porterg@hickory:~/public_html/w$ ls -al LocalSettings.php -rw------- 1 porterg users 4297 2009-05-03 11:16 LocalSettings.php porterg@hickory:~/public_html/w$ ls -ald config/ drwxrwxrwx 2 porterg users 24 2009-05-03 11:21 config/ porterg@hickory:~/public_html/w$ chmod 755 config/ porterg@hickory:~/public_html/w$ ls -ald config/ drwxr-xr-x 2 porterg users 24 2009-05-03 11:21 config/
Hey! They didn't lie. It really does work!
Summary
I lucked out. My ISP must have figured that lots of customers would want MediaWiki installed, and pre-configured their servers to have all the right stuff, configured correctly. All I had to do is read the docs, make a directory, unzip the tarball into the wiki directory, and configure it using the web page based configuration tool. Your Mileage May Vary.
Installing MediaWiki From the Fedora Pre-packaged Version
Read this in case you are trying to use the (silly, broken?) Fedora mediawiki package.
