Developer Area/Developer Environment

The instructions below are for an installation on Ubuntu, but should be fairly similar for other Linux systems.

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

Initial installation of your developer environment on your computer

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

For ubuntu 13.10, you have to also install php5-json

sudo apt-get install php5-json

Also add this line to the end of your /etc/php5/apache2/php.ini file (to enable the extension).

extension=json.so

2. do a checkout of the code:

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

3. make sure the code checkout is accessible to Apache:

sudo chmod a+rx /home/<your username>

4. create a db user and database:

sudo -u postgres createuser -P -D -R -S maharauser
(use "mahara" as the password)

sudo -u postgres createdb -Omaharauser mahara-master

5. create the config file ~/code/mahara/htdocs/config.php containing:

<?php
$cfg = new StdClass;

$branch = 'master';

// 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;

If you're doing a lot of development, and you're frequently adding calls to log_debug() to examine data structures, for example, you will find LOG_TARGET_SCREEN in the $cfg->log_..._targets lines will send long messages to your screen which get in the way. You can safely remove all those lines provided you watch the webserver log for warnings.

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 sitedata directory:

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

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

127.0.0.1 mahara

8. set the following in /etc/php5/apache2/php.ini:

post_max_size = 32M

9. create a new Apache vhost file in /etc/apache2/sites-available/mahara:

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

Under Ubuntu 13.10, you will need to create the vhost file with .conf at the end, i.e. /etc/apache2/sites-available/mahara.conf and have a slightly different content:

create a new Apache vhost file in /etc/apache2/sites-available/mahara.conf:

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

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:

sudo a2ensite mahara
sudo apache2ctl configtest
sudo apache2ctl graceful

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

http://mahara/

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/