System Administrator's Guide/Installing Mahara/How to install Mahara in Ubuntu

If you are unfamiliar with Linux in general, and Debian-based distributions in particular, this guide will show you how to proceed.

This guide is just for installing a development site of Mahara as a localhost. For a production site, you would read helpful documentation from [tutorials] for best practices.

These instructions assume that you're running a fresh installation of an in support version of Ubuntu or similar.

Install Required Packages

To install a site using apache2 webserver and postgresql database server

sudo apt-get install make curl wget xvfb postgresql php7.4-common php-cli libapache2-mod-php7.4 php7.4-curl php7.4-gd php-json php-ldap php-pgsql php-xmlrpc php-zip php-xml php7.4-pgsql php7.4-xml php7.4-xmlrpc php7.4-mbstring

Note on php versions: At the time of writing (Nov 2020), php 7.4 has a year of active development remaining, and we are expecting the release of php 8.0 sometime soon. Php 7.4 is currently the recommended version to install. Sometimes there is a generic package _and_ a version-specific package to be installed. [PHP supported versions](https://www.php.net/supported-versions.php)

This should install all the dependencies we need.

If you are wanting to install using mysql version 8.0 then you will need to install the following:

sudo apt-get install mysql php7.4-mysql

And do the following step: Using MySql 8]

After installing the packages, just follow the instructions provided in the "Installing Mahara" main document to unzip and install the Mahara folders.

Download and unpack Mahara

In this example, we install mahara to /var/www/[hostname], and store our data in /var/lib/sitedata/[hostname].

Where [hostname] is some identifying name for your site, eg my-site-production

First find the supported version you want to download, either from [downloads], for example the 21.04.1 release:

 cd /var/
 mkdir www
 cd /var/lib/
 mkdir sitedata
 cd /var/www
 wget https://launchpad.net/mahara/21.04/21.04.1/+download/mahara-21.04.1.zip
 unzip mahara-21.04.1.zip
 rm mahara-21.04.1.zip
 mv mahara-21.04.1 [hostname]

Configure the Database

The easiest way to create the database if using postgres is via the postgres user.

First make the database user that will own the database, in this case 'maharauser'

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

You'll be prompted for a password. Enter a complex value for the password and write it down. (easiest to use pwgen to generate one for you)

Next create the database with the [hostname].

sudo -u postgres createdb -Omaharauser [hostname]

Configure Apache2

The next step is to add your Mahara site as a new virtual hosts. There are many ways of doing so but this is the most straight forward:

1. Create a new file called "mahara.conf" (for instance) at /etc/apache2/sites-available.
2. You need to edit that file by typing from the console:

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

(or alternatively "sudo nano /etc/apache2/sites-available").

The following is a very basic example of an Apache configuration for Mahara. You'll need to put this into the mahara.conf file you just opened

   <VirtualHost *:80>
       ServerName [hostname]
       DocumentRoot /var/www/[hostname]/htdocs

       <Directory /var/www/[hostname]/htdocs/>
           Options Indexes FollowSymLinks MultiViews
           Require all granted
       </Directory>

       ErrorLog /var/log/apache2/[hostname]-error.log
       CustomLog /var/log/apache2/[hostname]-access.log combined
   </VirtualHost>

We'll then need to enable the site. On Ubuntu, Apache comes with a suite of commands for doing this kind of thing. We'll use the Apache2 Enable Site command:

 sudo a2ensite mahara.conf

DNS/Friendly Name

Depending on what you chose as your host name, you may need to add a DNS entry, or a line to the /etc/hosts file.

In this example, I'm running mahara on my local system for development/demonstration purposes. I don't have proper DNS available so I'm adding my mahara.local domain.

 sudo gedit /etc/hosts

And add:

127.0.0.1 [hostname]

Mahara Configuration

The next step is to create the config.php from the config-dist.php. This step is pretty well explain at the "Mahara Configuration", but essentialy we'll

 cd /var/www/[hostname]/htdocs
 sudo cp config-dist.php config.php
 sudo gedit config.php

The key items to set are:

• $cfg->wwwroot
• $cfg->dataroot
• $cfg->dbname
• $cfg->dbuser
• $cfg->dbpass

If you've followed the steps so far, the following should work

 <?php
 $cfg = new stdClass();
 $cfg->dataroot = '/var/lib/sitedata/[hostname]';
 $cfg->dbname = '[hostname]';
 $cfg->dbuser = 'maharauser';
 $cfg->dbpass = '[password]';

We'll need to make sure that the web server can write to the data directory (dataroot). To do this, we'll change who owns the directory with the chown command. Apache2 typically runs as the user 'www-data' on Debian and Ubuntu:

 sudo chown -R www-data:www-data /var/lib/sitedata/[hostname]

There is a very good-and short-tutorial  about how to change permissions and groups of users in Ubuntu by using the chmod command. It only takes 10 minutes to read it and it really gives you a good insight.

Install Mahara

You should now be ready to actually install Mahara. Open your browser of choice, and visit the site (e.g. http://[hostname])

After checking you're ready to proceed, Mahara will install and ask for an e-mail address and password for your admin user.