Appendix B. Installing Mahara
This book is aimed at Mahara users, rather than Mahara administrators. However, a new user may wish to install a Mahara instance in order to experiment. Also, lots of people like to install Mahara on their own Linux machines or on a web server of their own in order to organize their own personal learning data.
This section is for those of you who have some knowledge of web applications and servers or feel like you could have a good go at installing Mahara. We don't give full explanations of each technical term we use, as we assume some prior knowledge.
Many of the instructions in this chapter mirror the advice contained in the Mahara wiki on installing the software. See http://wiki.Mahara.org/System_Administrator%27s_Guide/Installing_Mahara. You can also see a shorter list of instructions on installing a development environment here at https://wiki.mahara.org/index.php/Developer_Area/Developer_Environment.
We recommend you have a read through these instructions as well as this chapter before attempting an install.
Don't worry, we will keep it as simple as possible...
Before you can install Mahara, you will need to have access to a Linux server. It may be that you run Linux on a laptop or desktop at home or that your company or institution has its own Linux servers, in which case, great! If not, there are many hosting services available on the internet, which will enable you to access a Linux server, and therefore, install and run Mahara.
It is important to choose a host that will allow you to set up the environment ready for Mahara — giving you, for example, the ability to manage your own PHP configuration and to add the required PHP extensions. It is really much better if you have access to your own virtual server or dedicated host — you have more control and are less likely to bump into issues later on.
It is important that you get a server to which you have root access. It is also important that you set your server up with the following features:
Database: Mahara must have a database to work. The databases supported are PostgreSQL Version 8.3 or later and MySQL Version 5 or later. The Mahara developers recommend that you use PostgreSQL if possible but, for most installations, MySQL will work just as well.
PHP: Mahara requires PHP Version 5.3 or later.
Web server: The preferred web server is Apache - 2.0 or greater.
PHP extensions:
Compulsory extensions:
gd, json, curl, libxml, SimpleXML, session, pgsql or mysqli, openssl or xmlrpc (for networking support), mbstring, mime_magic or fileinfo, zip, and unzip utilities.
Optional extension:
imagick
Recommended extensions:
zlib, zip, and bz2
Again, ask your resident IT expert about the features listed above if you don't understand what they mean.
Note
A quick way to install some of the software listed in the preceding section is to use the apt-get install command, if you are using the Ubuntu/Debian Linux Systems. See http://www.debian.org/doc/manuals/apt-howto/ to find out more.
What about installation on other operating systems?
The Mahara developers clearly state that they don't test their system with any other operating systems, including Solaris, Mac, and BSD. Again, that isn't to say that Mahara won't work on these systems, it is just best if you play it safe and choose to run your Mahara on the system that it was built for — Linux.
Before you can install Mahara, you will need to have access to a Linux server. It may be that you run Linux on a laptop or desktop at home or that your company or institution has its own Linux servers, in which case, great! If not, there are many hosting services available on the internet, which will enable you to access a Linux server, and therefore, install and run Mahara.
It is important to choose a host that will allow you to set up the environment ready for Mahara — giving you, for example, the ability to manage your own PHP configuration and to add the required PHP extensions. It is really much better if you have access to your own virtual server or dedicated host — you have more control and are less likely to bump into issues later on.
It is important that you get a server to which you have root access. It is also important that you set your server up with the following features:
Database: Mahara must have a database to work. The databases supported are PostgreSQL Version 8.3 or later and MySQL Version 5 or later. The Mahara developers recommend that you use PostgreSQL if possible but, for most installations, MySQL will work just as well.
PHP: Mahara requires PHP Version 5.3 or later.
Web server: The preferred web server is Apache - 2.0 or greater.
PHP extensions:
Compulsory extensions:
gd, json, curl, libxml, SimpleXML, session, pgsql or mysqli, openssl or xmlrpc (for networking support), mbstring, mime_magic or fileinfo, zip, and unzip utilities.
Optional extension:
imagick
Recommended extensions:
zlib, zip, and bz2
Again, ask your resident IT expert about the features listed above if you don't understand what they mean.
Note
A quick way to install some of the software listed in the preceding section is to use the apt-get install command, if you are using the Ubuntu/Debian Linux Systems. See http://www.debian.org/doc/manuals/apt-howto/ to find out more.
What about installation on other operating systems?
The Mahara developers clearly state that they don't test their system with any other operating systems, including Solaris, Mac, and BSD. Again, that isn't to say that Mahara won't work on these systems, it is just best if you play it safe and choose to run your Mahara on the system that it was built for — Linux.
It's time for action. Let's start by seeing how easy it is for you to get a copy of Mahara for yourselves, and the best part is... it's free!
Time for action — downloading Mahara
You're going to start the installation process by downloading your own copy of the Mahara code:
1. Go to the Mahara page on launchpad — https://launchpad.net/mahara. You will see a web page that lists the most recent series of Mahara. On the right of the screen is a box that shows the very latest stable version. Choose to download the code in a format you prefer. We recommend that you use the .tar.gz type as it is faster to download than .zip:
2. You may be asked if you would like to open or save the file. Select Save File and click on OK.
3. That's all there is to it. Go to the folder where you downloaded the package. In there, you should see your newly downloaded Mahara package.
You have just taken your first step on the road to installing Mahara. You have seen the website you have to go to for downloading the most recent version and learned how to download the package in a format you prefer.
Note
Mahara code versioning
Mahara versioning works on a major/minor version system. Major versions represent a number of big changes to the code with the introduction of new features and sometimes reworking of existing ones. These are numbered 1.3.0, 1.4.0, 1.5.0, and so on. Minor versions are usually important bug fixes or security updates, and are numbered 1.5.1, 1.5.2, 1.5.3, and so on, in relation to the current major version. When a new version is ready for testing, there is usually an alpha, beta, and release candidate release — these aren't stable and shouldn't be used on a production site. You can find out more about Mahara releases here at https://wiki.mahara.org/index.php/Developer_Area/Release_Policy.
We always recommend that for a production site, you choose the latest stable release of any Mahara series as it will contain bug and security fixes.
Release candidates aren't production-ready, but they are useful for testing out a new version of Mahara on a test server. You could even try upgrading to a release candidate on a development server (make sure you have a backup of the database and Mahara data files first). Release candidates are specifically released to get feedback from users, so that as many bugs as possible can be found and fixed before the next stable version. If you find any problems with the release candidate or the upgrade, you should let the Mahara developers know about them.
Note
Version support
Mahara only supports the two latest major software releases. So, for example, if the current version is 1.5, only 1.4 and 1.5 will be supported. If you are running a major version before this, you really should update to the next major version otherwise you won't be keeping up with the latest (crucial) security updates. Plus the fact — you're missing out on lots of exciting new features!
The best way of installing and administering your Mahara is to use the command line.
You will be doing a lot of the things in this area, assuming that you have Secure Shell Access to your server through the terminal command line.
If you have a Linux or a Mac computer, you can use the terminal on your machine to SSH into your Linux web server. Windows users can achieve the same functionality by downloading a free terminal client called PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html.
Speak to your resident IT expert for more information on how to use the terminal or see http://www.tuxfiles.org/Linuxhelp/cli.html for an introduction to the Linux command line.
For now, let's just learn how to get the content of your downloaded package into the correct place on your server.
Time for action — creating your Mahara file structure
You're now going to extract the content of the code, which you downloaded in the preceding Time for action downloading Mahara section, to the right place on your web server:
1. Copy the mahara-1.5.1.tar.gz (or whichever version you downloaded) package into your home directory on your web server. If you are copying the file to the server from your own computer, you can do this by using the scp command (on Linux or Mac):
2. Unpack the contents of the Mahara package on the Linux Server. On the terminal, you can do this using the tar command:
3. You will now see a new folder called Mahara-1.5.1, you will need to rename this to public. To do this on the terminal, you can use the mv command:
4. That's it! The Mahara code is now in place.
You just learned where to copy the Mahara package on your server and how to extract its contents.
A lot of the information created in your Mahara will be stored in a database. Mahara offers support for both PostgreSQL and MySQL databases. However, we prefer to use PostgreSQL. If you are interested, see http://Mahara.org/interaction/forum/topic.php?id=302 for a discussion on why PostgreSQL is preferred to MySQL.
The way you create your database will depend on who you have chosen to host your Mahara. Sometimes, your web host will provide a graphical user interface to access your server database. Your web host may not even allow PostgreSQL, in which case MySQL is the way to go for you.
For smaller Mahara installations, we prefer to use something like phpPgAdmin, which is a software that allows you to manage PostgreSQL databases over the Internet. See http://phppgadmin.sourceforge.net for more information on setting up phPgAdmin on your server.
Also, see, http://www.phpmyadmin.net/ for phpMyAdmin, which works in a very similar way to phpPgAdmin, but operates on a MySQL database.
Time for action — creating the Mahara database
Let's get on with creating a PostgreSQL database, using your phpPgAdmin panel:
1. Open up your phpPgAdmin panel from your Internet browser and log in. The username is hopefully postgres. Contact your admin if you are unsure of the database password or how to locate the phyPgAdmin panel:
2. On the front page, there is a link that invites you to create a database, click on Create database there. On the resulting screen, give your database a relevant name such as mysite_mahara. It is important that you select the UTF8 collation from the drop-down box. Finally, click on Create:
3. If you want to, you could also add a new user for your database. Use phpPgAdmin to create a new user and assign them permissions for the database you just created.
4. That's it, you're done!
You just created the database for your Mahara installation, using the Open Source phyPgAdmin tool available for Linux.
Another way to create the database on your server is to use the database command-line tool.
Have a go hero — using the command line to create your database
Using the command line is a much more elegant way to create the database, and quicker, once you get the hang of it. Why not have a go at creating the database by using the command line? For instructions on how to do this refer to the database section of the Mahara installation guide at http://wiki.Mahara.org/System_Administrator%27s_Guide/Installing_Mahara.
Setting up the data directory
Most of the data that is created in your Mahara is stored in the database. However, all the files that are uploaded by your users, such as their personal photos or documents, need to be stored at a separate place. This is where the data directory comes in.
The data directory is simply a folder that holds all of the stuff belonging to your users. Everything is kept safe by the data directory being outside of the home directory. This set up also makes it easy for you to migrate your Mahara to another server at some point in the future. If you're interested in migrating your site to another server, see https://wiki.mahara.org/index.php/Developer_Area/Developer_Environment#Copying_a_local_install_to_another.
Note
The data directory is often referred to as dataroot.
Time for action — setting up the data directory
Let's see how easy it is to set up your data directory:
1. Make the data directory outside of the public folder of your home directory. Create the directory using the mkdir command and call it uploaddir:
Note
It doesn't really matter what you decide to call your dataroot directory, but try and choose a name that is relevant to what the directory is doing. The name suggested by Mahara and most commonly used is uploaddir, but other names such as maharadata would be just as good.
2. Set the permissions on this folder, using the chmod command:
3. Change the user of the new directory to be the same as your server, using the chown command. The user is usually apache or www-data:
4. And that's all there is to it, you now have a place where Mahara can put all of the stuff belonging to your users.
You just created your data directory and made sure that it was in a safe place in your home directory outside of the htdocs directory. Then you changed the permissions, users, and groups for the directory to make it easy for Mahara to put things in and to delete things.
Let's take a quick look at the file structure that you have just created for your Mahara installation:
So far, you have downloaded and put the Mahara files into place on your server, and seen how to create the database and dataroot needed to store all the Mahara information.
Time for action — creating the config.php file
Now, you have to hold Mahara's hand by letting it know how it can access the database and how to find the dataroot. To do this, you use an important file called config.php:
1. In the htdocs folder of your Mahara site, you will find a file called config-dist.php. Use the nano command in your terminal to start editing the config-dist.php file:
2. Now, you will see the file open on the command line. Use the down arrow key on your keyboard to scroll down the page until you get to a section called database connection details. In the following example, the user is using MySQL5 rather than postgreSQL. Fill in the information so that it matches the details you used to set up your own database including your own database name (dbname), database user (dbuser), and database password (dbpass):
3. Next, continue scrolling down the file until you reach a line that starts with $cfg->dataroot. Here, you must fill in the full path from the server root directory to the data directory that you created earlier in this chapter.
4. Now, have a look further down the file, you should see an option to add an e-mail contact. This e-mail address gets displayed if a form is suspected of being spam as a place of contact for those who stumble upon this. Fill in a relevant e-mail address.
5. Finally, you should add a password salt to your config file. This is a text string that helps to make user authentication more secure. Add a line similar to the following, but containing your own secret phrase:
6. Congratulations, you've now finished editing the configuration file. Save it by pressing Ctrl + X on your keyboard (still within the nano editor). When asked, if you would like to rename the file, type Y for yes and name the file config.php. This will also save the file.
What you just did was very important. You let Mahara know where the database is and the user and password needed to access it. You also let it know the location of the dataroot directory as well as set a password salt.
Now that you've done all the hard work, it's time to let the Mahara installer do its magic. The main job that the installer does is to add new tables to the database that you created earlier.
Time for action — running the installer
Let's see how to start the installer:
1. The Mahara installer is started when you navigate to wwwroot (location where you have installed Mahara) in your Internet browser. For example, visit http://mysite.tdm.info.
2. The first page you see in the installer invites you to read the GNU General Public License. Click on Install Mahara at the bottom of the page to continue.
Note
If you don't see the GNU information screen, it is likely that you have done something wrong. Mahara will typically give you a message at this point explaining what the problem is. You can then have a look over at mahara.org for some help with fixing your problem.
3. The next page is where all the important work is being done. You will see each component being installed in the database. If everything goes well, the information section on the right-hand side should have a green tick for each component. When the installation has finished, click on continue at the bottom of the page.
4. And that's all there is to it! You will now see the home page of your very own Mahara.
You just ran the Mahara installer, which added all the necessary tables and data to your Mahara database.
The last step — setting up a cron process
Before you can be let loose on your Mahara, there is one last thing that you must remember to do to complete the installation — set up a cron job. If, like me, when I installed Mahara for the first time, you are thinking, "What on earth is a cron job?", don't worry, it is relatively simple.
The cron job is a process that simply enables a number of tasks to be performed regularly, typically every 10 minutes. This is useful for updating RSS feeds, among other things. The easiest way to add a cron process on a Debian or Ubuntu Linux Server is to add a new entry in a file called crontab by using the following command:
This will open up the default cron file for editing. Add a line similar to the following:
Stars in the above example simply mean any value. If you are interested, see http://www.adminschoice.com/crontab-quick-reference for more information on crontab files. Also have a look at the Mahara information on using cron at https://wiki.mahara.org/index.php/System_Administrator's_Guide/Cron_Job. That's it, you're all done with the installation, so you can log in and start using your new software!
Mahara partners can help you with ongoing support, if you need that little bit of extra help.
What is a Mahara Partner and what can they do for me?
Most people using a tool like Mahara for the first time will shudder at the thought of doing an installation on a Linux server. In fact, "What is Linux?", is the most likely response. If this is you, there are people who can help you out!
Mahara Partners are specialists who know how to:
Install Mahara on a Linux server
Host your Mahara
Offer support for developing your Mahara in the future
Upgrade your Mahara when new versions come out
Theme your Mahara
Provide training
Provide implementation consultancy support
....and more
Mahara Partners have a special relationship with the Mahara developer team and are very knowledgeable about how Mahara works. They can do all the things you don't feel comfortable doing, such as installing your Mahara, hosting it on the Internet and managing it. This will be at a cost and will depend on the individual partner.
Even if you have confidence that you could install Mahara on a Linux server, it is still very likely that a Mahara Partner has something to offer you. For example, you might want to brighten up the look of your Mahara to match your corporate branding, but have no knowledge of Internet technologies such as CSS and (X)HTML.
So, where can you find out more about Mahara Partners?
The easiest way to find a Mahara Partner is to visit the Partners section of the Mahara website. See https://Mahara.org/partners. This will open a page listing all the Mahara Partners. If you are thinking about using a Mahara Partner, have a look through the description of the services that each one offers and decide whether they are right for you or not. Each partner also has a website that you can visit to find out more information. The Mahara partners are based all over the world, so it is a good idea to find one that is close to wherever you are.
