Developer Area/Developer Environment

This page explains how to set up a copy of Mahara for development purposes.

Mahara is a fairly standard PHP web application. You mainly need to place it in your web server and give it a database, and a file storage directory.

The short version

1. Set up your Apache web server. For development purposes, it is often handy to have the web root sitting inside your home directory.
2. Retrieve a copy of the Mahara codebase. Place it in your Apache web root.
3. Create a Mahara "dataroot" directory outside of your web root. Make it read/writeable by Apache.
4. Create a database instance and database user for Mahara to use.
5. Edit the Mahara "config.php" file so that Mahara knows the location of its dataroot directory, and its database login credentials.
6. Run the Mahara installer by visiting your Mahara site in your web browser. If you are missing any required PHP modules, Mahara should tell you. Depending on what you already have installed, you may need one or more of these:
   1. php5-pgsql
   2. php5-gd
   3. php5-curl
   4. php5-json (in Ubuntu 13.10 and later)

Initial installation of your developer environment on your computer

The instructions explain one way to set up an installation of Mahara for development purposes. These instructions are specifically for Ubuntu Linux, although the process will probably be quite similar in other Linux versions.

If you want to install your developer environment on Windows, please check the Windows instructions.

The following instructions are for Ubuntu 12.04-13.04 unless otherwise noted.

1. Install required packages:

sudo apt-get install libapache2-mod-php5 postgresql git php5-pgsql php5-gd php5-curl gitk

If you are using Ubuntu 13.10 or later, you will also have to install php5-json:

sudo apt-get install php5-json

2. Get a copy of the Mahara code from git. We'll put it under your home directory, in a new directory called "code":

cd ~
mkdir code
cd code
git clone git://gitorious.org/mahara/mahara.git

3. Give the Apache web server access to your Mahara code directory:

sudo chmod a+rx ~/code/mahara

4. Create a PostgreSQL database user:

sudo -u postgres createuser -P -D -R -S maharauser

You'll be prompted for a password. Enter maharapassword for the password.

Now create a database:

sudo -u postgres createdb -Omaharauser mahara-master

5. Using a text editor, copy these contents into a file and save it to ~/code/mahara/htdocs/config.php:

<?php
$cfg = new stdClass();

$branch = 'master';

// database connection details
// valid values for dbtype are 'postgres8' and 'mysql5'
$cfg->dbtype   = 'postgres';
$cfg->dbhost   = 'localhost';
$cfg->dbuser   = 'maharauser';
$cfg->dbname   = "mahara-$branch";
$cfg->dbpass   = 'maharapassword'; 

$cfg->dataroot = "/var/lib/maharadata/$branch";

$cfg->sendemail = true;
$cfg->sendallemailto = '<your email address>';

$cfg->productionmode = false;
$cfg->perftofoot = true;

Make sure to replace <your email address> with your email address.

If you're mainly testing, and you don't find the stack traces in these screen messages particularly useful, adding "$cfg->log_backtrace_levels = LOG_LEVEL_ENVIRON;" to config.php will display important warning messages on a single line, without stack traces.

6. Create a dataroot directory (this is where Mahara stores uploaded files):

sudo mkdir /var/lib/maharadata
sudo mkdir /var/lib/maharadata/master
sudo chown www-data:www-data /var/lib/maharadata/master

7. Set up a new local domain name "mahara" for your Mahara site, in /etc/hosts:

sudo sh -c "echo 127.0.0.1 mahara' >> /etc/hosts"

8. Increase your PHP "post_max_size" setting to 32M in php.ini:

sudo sh -c "echo 'post_max_size = 32M' >> /etc/php5/cli/php.ini"
sudo sh -c "echo 'post_max_size = 32M' >> /etc/php5/apache2/php.ini"

9. Create an Apache configuration file to point to your copy of Mahara. You can do this by first copying the following contents into a file called "mahara", saved in your home directory:

/etc/apache2/sites-available/mahara.conf

This will open a text editor with permissions to save a file in the correct location. Then copy one of these configurations into the text editor.

If you are using Ubuntu 13.04 or earlier:

<VirtualHost *:80>
 ServerName mahara
 DocumentRoot /home/<your username>/code/mahara/htdocs

 <Directory /home/<your username>/code>
   Options Indexes FollowSymLinks MultiViews
   Order allow,deny
   Allow from all
 </Directory>

 ErrorLog /var/log/apache2/error.log
 LogLevel info

 CustomLog /var/log/apache2/access.log combined
 DirectoryIndex index.php index.html
</VirtualHost>

... if you are using Ubuntu 13.10 or later:

<VirtualHost *:80>
 ServerName mahara
 DocumentRoot /home/<your username>/code/mahara/htdocs

 <Directory /home/<your username>/code>
   Options Indexes FollowSymLinks MultiViews
   Require all granted
 </Directory>

 ErrorLog /var/log/apache2/error.log
 LogLevel info

 CustomLog /var/log/apache2/access.log combined
 DirectoryIndex index.php index.html
</VirtualHost>

Then copy the file into your Apache sites-enable directory. The name to give the file will also vary depending on what version of Ubuntu you are using.

• 13.04 and earlier: sudo cp ~/mahara /etc/apache2/sites-available/mahara
• 13.10 and later: sudo cp ~/mahara /etc/apache2/sites-available/mahara.conf

If you are upgrading from Ubuntu 12.04-13.04 to 13.10, you may find answers on this page helpful.

10. Enable the site in Apache:

 enclose="div">
sudo a2ensite mahara
sudo apache2ctl configtest
sudo apache2ctl graceful

11. Go to the site in your browser.

http://mahara/

12. You should see the Mahara installer page. If you do, congratulations! Your development environment is now set up.

Adding another branch

1. create a new local branch for it in git:

cd ~/code/mahara
git checkout -t origin/1.4_STABLE

2. create sitedata for the new branch:

sudo mkdir /var/lib/maharadata/14stable
sudo chown www-data:www-data /var/lib/maharadata/14stable

3. create a database:

sudo -u postgres createdb -Omaharauser mahara-14stable

4. change your ~/code/mahara/htdocs/config.php to point to the 1.4 branch:

$branch = '14stable';

5. Go to the site in your browser to run the Mahara installer:

http://mahara/

Switching back to the master branch

1. change the config.php file:

$branch = 'master';

2. switch to the right git branch:

cd ~/code/mahara/
git checkout master

Reset the database

1. delete the old database

sudo -u postgres dropdb mahara-master

2. create a new one with the same name

sudo -u postgres createdb -Omaharauser mahara-master

3. Go to the site in your browser o run the Mahara installer again:

http://mahara/

Testing a change submitted to Gerrit

1. go to the change page, for example:

https://reviews.mahara.org/#change,230

2. in your local repository, switch to the branch listed in the Gerrit change (in this case: master):

cd ~/code/mahara
git checkout master

3. update your config.php to use the right branch, too

4. copy the "Anonymous Git" URL in the "Download" section of "Patch Set X" and run it in ~/code/mahara to check the branch out:

git fetch git://reviews.mahara.org/git/mahara refs/changes/30/230/1 && git checkout FETCH_HEAD

5. after finishing the testing, go back to master:

git checkout master

Copying a local install to another

This example uses the directory 15stable as an example for the new install and the 14stable install as database and sitedata directory to copy.

1. do a checkout of the code into a new directory

cd ~
mkdir code
cd code
git clone git://gitorious.org/mahara/mahara.git 15stable

2. copy the database

On Postgres 8

sudo -u postgres pg_dump -Fc mahara-14stable > 14stable.pg
sudo -u postgres createdb -Omaharauser mahara-15stable
sudo -u postgres pg_restore -O -j4 -d mahara-15stable -U maharauser -W -h localhost 14stable.pg

This may give you the following warning

pg_restore: WARNING:  no privileges could be revoked for "public"
pg_restore: WARNING:  no privileges could be revoked for "public"
pg_restore: WARNING:  no privileges were granted for "public"
pg_restore: WARNING:  no privileges were granted for "public"

On Postgres 9

sudo -u postgres pg_dump -Fc mahara-14stable > 14stable.pg
sudo -u postgres createdb -Omaharauser mahara-15stable
sudo -u postgres pg_restore -O -j4 -d mahara-15stable 14stable.pg
sudo -u postgres psql -d mahara-15stable -c 'GRANT ALL PRIVILEGES ON SCHEMA public TO maharauser;'
sudo -u postgres psql -d mahara-15stable -c 'GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO maharauser;'
sudo -u postgres psql -d mahara-15stable -c 'GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO maharauser;'
sudo -u postgres psql -d mahara-15stable -c 'GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO maharauser;'

3. change the wwwroot in the new database

sudo -u postgres psql mahara-15stable
delete from config where field = 'wwwroot';
Ctrl + d to exit

4. create the config file ~/code/mahara/htdocs/config.php

<?php
$cfg = new StdClass;

$branch = '15stable';

// database connection details
// valid values for dbtype are 'postgres8' and 'mysql5'
$cfg->dbtype   = 'postgres8';
$cfg->dbhost   = 'localhost';
$cfg->dbuser   = 'maharauser';
$cfg->dbname   = "mahara-$branch";
$cfg->dbpass   = 'mahara'; 
$cfg->dbprefix = ''; 

$cfg->dataroot = "/var/lib/maharadata/$branch";

$cfg->sendemail = true;
$cfg->sendallemailto = 'your email address';

$cfg->log_dbg_targets     = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;
$cfg->log_info_targets    = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;
$cfg->log_warn_targets    = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;
$cfg->log_environ_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;
$cfg->perftofoot = true;

5. copy the source sitedata directory into the new sitedata folder:

sudo cp -r /var/lib/maharadata/14stable /var/lib/maharadata/15stable
sudo chown -R www-data:www-data /var/lib/maharadata/15stable

6. add a new entry to /etc/hosts:

127.0.0.1 15stable

7. create a new Apache vhost file in /etc/apache2/sites-available/15stable:

<VirtualHost *:80>
 ServerName 15stable
 DocumentRoot /home/<your username>/code/15stable/htdocs

 <Directory /home/<your username>/code>
   Options Indexes FollowSymLinks MultiViews
   Order allow,deny
   Allow from all
 </Directory>

 ErrorLog /var/log/apache2/error.log
 LogLevel info

 CustomLog /var/log/apache2/access.log combined
 DirectoryIndex index.php index.html
</VirtualHost>

8. enable the site in Apache:

sudo a2ensite 15stable
sudo apache2ctl configtest
sudo apache2ctl graceful

9. Go to the site in your browser to run the Mahara installer:

http://15stable/