Sysadmin Guide/Installing Mahara

Home » Wiki » En » Sysadmin Guide » Installing Mahara

Installing Mahara requires that you have some basic understanding of how web applications work. These instructions assume that you understand the basics of setting up webservers/databases etc.

If you're running Debian/Ubuntu, a lot of the required software can be installed using apt-get. If you're using some other linux distribution, you may be able to use your distribution specific install tool also.

1. Dependencies

Basic Operating Environment

  • Linux
  • PHP 5.1.3+
  • Postgres 8.1+ (recommended), or MySQL 5.0.25+

NOTE: Your MySQL version must be 5.0.25 or above - see http://bugs.mysql.com/bug.php?id=20519 for a bug in previous versions that affects some queries in Mahara.

PHP Extensions

  • gd
  • json
  • libxml
  • SimpleXML
  • session
  • pgsql OR mysqli
  • For networking support: openssl, curl and xmlrpc
  • Optionally: imagick

Can I use Windows to host Mahara?

Users may access Mahara with a standard web browser. For hosting solutions, Mahara has been designed for Linux, Apache, PHP and an SQL database, and currently there has been very little testing for Windows hosted environments.

For those people who are adventurous enough to try, it seems that you need to install an equivalent of the 'file' program (see Bug #700), among other things, to make it work.

Will Windows be supported in future?

We have already heard rumours of Mahara being installed on Windows. Windows support, when it comes is likely to be addressed through our Partner programme or through a specific client funded request.

What about hosting Mahara on Solaris/Mac/BSD/Other OS?

You will likely have more luck than installing on Windows, although there may still be some issues. The biggest issue is around the 'file' command, which works differently on Mac OS Leopard and Solaris. Bug #1891 has more information, including workaround information. We hope to fix this bug in Mahara 1.1, and add instructions for Mac and Solaris to the installation instructions.

What about using Other Web Server/Other Database/Other PHP?

No other webservers are tested, you're on your own. Please contact the dev team in #mahara/on forums if you're interested in implementing support for other databases. PHP 5.1+ is required, all versions above this should be fine.

Can I use shared hosting?

Maybe. It depends on your host. Some hosts disable certain functions (e.g. exec) or use safe mode, and these things can badly impact on Mahara functionality. Mahara is not explicitly designed to run on shared hosting - while it is a goal we keep in mind, and will accept patches for, shared hosting by its nature limits what you can do, and you should endeavour to obtain a VPS or dedicated host if at all possible.

If your host has disabled exec, Mahara will not be able to detect images files properly, so thumbnail generation will be incorrect and you will not be able to embed images in views. See this bug report for more information.

Hosts often (stupidly) set AllowOverride None, meaning that .htaaccess isn't allowed. If you are getting 500 errors when trying to set up your site, you may find commenting out the php_flag lines, or removing the .htaccess file is necessary. This will not cause a critical reduction in functionality, but if you are forced to remove the entire file it will make your site less performant than it otherwise would be. [Important note: The .htaccess file may be invisible on Mac OS X and your server; it may be best to make changes to this file from a Windows based PC and upload it from that platform, which is possible despite the fact that it may appear as a nameless file.]

2. Get the code

You can either download a snapshot from http://git.mahara.org/?p=mahara.git;a=summary or you can check out the project from the git repo: 

git clone git://git.mahara.org/git/mahara.git

3. Create the Database

You need to create a database for Mahara and ensure that the webserver is able to connect to it. In postgres: 

createdb -U (username who will be connecting) (databasename)

In MySQL: 

mysql -Uroot
[enter password]
create database mahara;
grant all on mahara.* to 'username'@'localhost' identified by 'password';

Which database should I use?

The developers recommend PostgreSQL for maximum stability and data integrity. Properly tuned, PostgreSQL will likely outperform MySQL anyway - we are using InnoDB tables for the transaction support.

Furthermore, PostgreSQL can do DDL in transactions - that is to say BEGIN; CREATE TABLE foo(bar int); ROLLBACK; actually works how you would expect. This makes the upgrade process a lot safer, if the upgrade fails you know you won't have left your database schema in a mess that can't be automatically upgraded once the original problem is fixed.

4. Configuration

PHP Settings

You should make sure that magic_quotes_gpc is off, and that register_globals is off. Mahara will warn you about any other unsafe or unoptimal settings when it is run. Mahara also ships with a .htaccess file that will ensure that bad settings are off.

Webserver Configuration

Copy the contents of the htdocs/ directory to your webserver. It is best if you either:

  • Copy the entire directory, then rename it to something like 'mahara' - so you will see your site at example.org/mahara/; or
  • Copy the contents of the htdocs/ directory to the top level public directory (often called htdocs or public_html) of your webserver, so you can see your site at example.org

Mahara Configuration

You need to make a directory (outside the document root) and ensure the web server user has write access to it. This is where Mahara will store data like uploaded files.

In htdocs/ is config-dist.php. You need to make a copy of this called config.php. You then need to go through the file and make changes where appropriate. The file is commented, and there are not many settings to change. However, take special note of the following settings:

  • database connection details — ensure you include the database connection details by inserting the proper values for $cfg->dbname, $cfg->dbuser, $cfg->dbpass, $cfg->dbprefix. Note: If you are on shared hosting, it may be best to leave dbprefix empty and add the prefix directly to $cfg->dbname, $cfg->dbuser values.
  • dataroot - set this to the filesystem path to the directory you made that the web server user can write to
  • wwwroot - set this to the filesystem path to the directory where mahara runs (ex. http://mysite.org/mahara)
  • directorypermissions - if you're on shared hosting, you might need to change this from 0700 to 0777 or similar, so that you can download your dataroot later for backup purposes. This is less secure, but given apache is normally run on a shared host as the same user for anyone's code, you're not gaining much by having the permissions as 0700.

Cron Job

You will need to set up a cron job to hit htdocs/lib/cron.php every minute. Mahara implements its own cron internally, so hitting cron every minute is sufficient to make everything work.

You can set it up using the command line 'php' command to run the cron script, or by using a command line web browser such as lynx or w3m.

Something like the following in a crontab file will be sufficient: 

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

5. Run the Web Based Installer

Once you have set up your config.php, you should now be able to navigate to the Mahara installation using your web browser. This will pop up a page stating the conditions of using Mahara, and will ask for agreement. If you agree with the conditions, click "agree" and Mahara will install itself into your database. Click continue, and you should now be at a login screen.

Log into the system with user "admin", password "mahara". Congratulations!

Troubleshooting

Q: I see this:

Fatal error: Call to undefined function get_config() in /.../htdocs/lib/errors.php on line 122

A: Create config.php from config-dist.php

Q: Upon successful install, I see messages like You have dangerous PHP settings, magic_quotes_gpc is on. Mahara is trying to work around this, but you should really fix it

A: These messages warn you about PHP settings that you should have disabled. Mahara tries to disable them via .htaccess. If this has not worked, then you're probably on shared hosting, and need to tell Mahara to disable the messages. In your config.php, find this line: 

$cfg->log_environ_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;

and change it to 

$cfg->log_environ_targets = 0;

Q: I see this:

Parse error: syntax error, unexpected '{' in .../htdocs/init.php on line 79

A: You're probably running Mahara on PHP4. Mahara requires PHP 5.1 or greater.

Q: Every page I go to, Mahara wants me to log in again!

A: It is very likely that you have specified your dataroot incorrectly. Dataroot is an absolute path relative to the filesystem. It is NOT a URL, or part of one. It will also NOT work if it is a relative path.

To work out where on the filesystem your Mahara is installed, if you can't find it some other way (like FTP), put a line in index.php like echo getcwd();.

Your dataroot path then needs to be placed according to the normal rules, as documented in config-dist.php.

Installing Mahara in Wampserver

If you need to set up a Mahara development site, and you don´t have prior knowledge of Debian-Ubuntu, you can install Mahara under WAMPSERVER. This last one is a web development environment which allows to run web applications using Apache, MySQL and php in a windows environment. It also includes phpmyAdmin and SQLiteManager to manage the databases.

The following steps have been only tested with Wampserver 2.0c, so if you have already a previous version installed and doesn’t work, you may need to upgrade to 2.0c.

1. The first step is to download and install the latest version of WAMPSERVER. This installation is pretty straightforward and you shouldn’t have any problems with it. Once it is installed, click on the shortcut Wampserver icon displayed on screen. You will notice a new small icon display on the bottom left of the taskbar. You can activate the different utilities of WAMPSERVER by clicking on that small icon.

2. Download the latest version of Mahara.

3. In the /www directory that Wampserver has created in your hard-drive, create a subfolder called “Mahara” and extract all the Mahara’s files there.

4. The next step is to configure all the variables in the config-dist file of the /htdocs directory. You need to complete this file with the values of your installation: 

$cfg->dbtype   = 'mysql5'; 
$cfg->dbhost   = 'localhost';
$cfg->dbport   = null;
$cfg->dbname   = 'mahara';
$cfg->dbuser   = 'root'; // this is usually the default user for the database administrator.
$cfg->dbpass   = 'password'; If you have added a password to your root user, you should add the password here.
$cfg->dbprefix = '';

You need to configure the paths for the wwwroot and dataroot directories with the values in your installation. In my case: $cfg->wwwroot = 'http://localhost/mahara/htdocs/'; and $cfg->dataroot = 'C:\\wamp\\data';

Leave the rest of the config-dist file as it is. Once you have saved the file, rename as “config”

5. Before launching Mahara, we need to create the database, with the same name that we have set up in the config. php. For that, go to the “phpmyAdmin” menu of “Wampserver”. Type “mahara” -or the name you have added for your database in the config file- in the box “create new database”.

6. Once the database has been created, go to the “localhost” option of Wampserver. You will see that under “Project”, there is a new folder for Mahara. Click on it in order to complete the installation.

If everything goes OK, Mahara will start installing the different pluggins and components in the database.

When the installation finishes, if everything goes OK, you will be prompted to log in first time in Mahara as administrator (remember that the username is “admin” and the password “mahara”)