Installing Mahara

Richard Hand

February 2010

What will you need?

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 run Mahara.

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.1 or later and MySQL Version 5.0.25 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.1.3 or later.
  • Web Server: The preferred web server is Apache.
  • PHP extensions:
    • Compulsory Extensions: GD, JSON, cURL, libxml, SimpleXML, Session, pgSQL or Mysqli, EXIF, OpenSSL or XML-RCP (for networking support)
    • Optional Extension: Imagick

Ask your resident IT expert about the features listed above if you don't understand what they mean.

A quick way to install some of the software listed above is to use the apt-get install command if you are using the Ubuntu/Debian Linux systems. See to find out more.

Downloading Mahara

It's time for action. Let's start by seeing how easy it is for us to get a copy of Mahara for ourselves, and the best part is... it's free!

Time for action – downloading Mahara

  1. Go to Click on the download button on the Mahara home page. The button will be labeled with the name of the current version of Mahara:

    Installing Mahara

  2. You will now see a web page that lists all the various versions of Mahara, both previous and forthcoming versions, in Alpha and Beta. Choose the most recent version from the list in the format you prefer. We recommend that you use the .tar.gz type because it is faster to download than .zip.
  3. You will be asked if you would like to open or save the file. Select Save File, and click OK.
  4. That's all there is to it. Go to your Internet downloads folder. In there, you should see your newly downloaded Mahara package.

What Just Happened?

You have just taken your first step on the road to installing Mahara. We have seen the website we have to go to for downloading the most recent version and learned how to download the package in the format we prefer.

Using the command line

The best way of installing and administering your Mahara is to use the command line. This is a way of writing text commands to perform specific tasks, rather than having to use a graphical user interface. There are many things you can do from the command line, from common tasks such as copying and deleting files to more advanced ones such as downloading and installing software from the Internet.

A lot of the things we will be doing in this section assume that you will 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 web server. Windows users can achieve the same functionality by downloading a free terminal client called PuTTY from Speak to your resident IT expert for more information on how to use the terminal, or see an introduction to the Linux command line.

For now, let's just learn how to get the contents of our downloaded package into the correct place on our server.

Time for action – creating your Mahara file structure

  1. Copy the mahara- 1.2.0.tar.gz package you downloaded 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 using the scp command (on Linux or Mac):

    scp mahara-1.2.0.tar.gz servername:pathtohomedirectory

    On Windows, you may prefer to use a free FTP utility such as FileZilla (

  2. Unpack the contents of the Mahara package on the Linux server. On the terminal, you can do this using the tar command:

    tar xvzf mahara-1.2.0.tar.gz
  3. You will now see a new folder called mahara-1.2.0; you will need to rename this to public. To do this on the terminal, you can use the mv command:

    mv mahara-1.2.0 public
  4. That's it! The Mahara code is now in place.

What Just Happened?

You just learned where to copy the Mahara package on your server and how to extract its contents.

Creating the database

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 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. Get in touch with your local IT expert to find out how to do this.

However, for smaller Mahara installations, we often prefer to use something like phpPgAdmin, which is a software application that allows you to manage PostgreSQL databases over the Internet. See for more information on setting up phpPgAdmin on your server.

Also see, for phpMyAdmin which works in a very similar way to phpPgAdmin but operates on a MySQL database.

For now, let's get on with creating a Postgres database using our phpPgAdmin panel.

Time for action – creating the Mahara database

  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.

    Installing Mahara

  2. On the front page there is a section that invites you to create database, click there. Give your database a relevant name such as mysite_Mahara. Make sure you select the UTF8 collation from the drop-down box. Finally, click Create.

    Installing Mahara

  3. If you want to, it is a good idea to have a new user for each database you create. Use phpPgAdmin to create a new user.
  4. That's it, you're done!

What Just Happened?

We just created the database for our Mahara installation using the open source phpPgAdmin 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 using the command line? For instructions on how to do this see the database section of the Mahara installation guide:

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 in 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.

The data directory is often referred to as the dataroot.

Time for action – setting up the data directory

  1. Create the data directory in the public folder of your home directory. We will create the directory using the mkdir command and call it uploaddir:

    It doesn't really matter what you decide to call your dataroot directory, but try to choose a name that is relevant to what the directory is doing. The name suggested by Mahara and the most commonly used name is uploaddir, but other names such as maharadata would be just as good.

  2. Set the permissions on this folder using the chmod command
    chmod -R 0777
  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:
    chown -R www-data:www-data
  4. And that's all there is to it, we now have a place where Mahara can put all of the stuff belonging to our users.

What just happened?

What we have just done is really very simple, so hopefully you aren't feeling bogged down with all those commands you had to type.

We created our data directory and made sure that it was in a safe place in your home directory above the htdocs directory. Then we 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 we have just created for our Mahara installation:

Installing Mahara

So far we have downloaded and put the Mahara files into place on our server and seen how to create the database and dataroot needed to store all the Mahara information.

Now, we 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 we use an important file called config.php.


Time for action – creating the config.php file

  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 config-dist.php file.
    nano config-dist.php

    Other Linux people use much more sophisticated text editors like Vim and Emacs. We are simple folk and are perfectly happy with nano:

  2. You will now see the file open on the command line. Use the arrow keys on your keyboard to scroll up and 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:

    Installing Mahara

  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 we created earlier in this article.

    Installing Mahara

  4. Congratulations, you've now finished editing the configuration file. Save it by clicking Ctrl + C on your keyboard. When asked if you would like to rename the file, type Y for yes and name the file config.php.

What Just Happened?

What we just did was very important, we let Mahara know where the database is and the password needed to access it. We also let it know the location of the dataroot directory.

Running the Installer

Now that we'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 we created earlier.

Time for action – running the installer

  1. The Mahara installer is started when you navigate to the wwwroot (the location you have installed Mahara) in your Internet browser. For example, we visit Your domain will have a different name.
  2. The first page you see in the installer invites you to read the GNU General Public License. Click I agree to continue.

    If you don't see the GNU information screen, then it is likely that you have done something wrong. Mahara will typically give you a message at this point explaining what the problem is.

  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 check mark for each component. When the installation has finished, click 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, and I'm sure you can't wait to log in for the first time.

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 hour. This is useful for updating RSS feeds, amongst 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 a crontab, by using the command:

crontab -e

...and adding a line similar to:

* * * * www-data php /path/to/mahara/htdocs/lib/cron.php

If you are interested, see for more information on crontab files.

Can I install Mahara on Windows?

At the moment, the Mahara developers offer no support for running Mahara on Windows Servers. It is designed to primarily work with Linux, Apache, PHP, and open source SQL databases.

This, however, doesn't mean that Mahara won't work on Windows, so If you are feeling adventurous why not give it a go and report back to Mahara on your experience?

What about installation on other operating systems?

The Mahara developers state clearly 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.

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, then there are people who can help you out!

Mahara partners are specialists who know how to:

  • Install Mahara on a 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, or don’t want to do, 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 do 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?

Finding a Mahara partner

The easiest way to find a Mahara Partner is to visit the Partners section of the Mahara website. See 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. 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.


This article discusses the installation of Mahara, along with the requirements for installation.

You've been reading an excerpt of:

Mahara 1.2 E-Portfolios: Beginner's Guide

Explore Title