Are you trying to install Mahara on Ubuntu?

This guide is for you.

Mahara is a popular ePortfolio and social networking system that helps educators to develop a digital classroom in a remote learning environment and track student's progress.

In a remote learning environment, Mahara can help educators foster a digital classroom and organize a student's progress.

Here at Ibmi Media, as part of our Server Management Services, we regularly help our Customers to perform software installation tasks.

In this context, we shall look into how to install Mahara on Ubuntu.

Steps to install and configure Mahara on Ubuntu 18.04?

The installation of Mahara in Ubuntu involves a series of tasks. 

This include:

1. Creating a Database and User for Mahara

2. Downloading Mahara

3. Creating the Dataroot Directory

4. Setting Up the Mahara Configuration File

5. Configuring Apache

6. Adjusting PHP Settings

7. Running the Mahara Installer

Now let's discuss each of them in detail.

How to Create a Database and User for Mahara ?

Let us begin this process by creating a Postgres database and user for Mahara. 

For this switch to the postgres user from server's command line :

$ sudo -i -u postgres

The -i switch provides an interactive shell, while sudo used with the -u switch allows us to switch users. Now let us create a Postgres user. 

Replace the username in the command below with a suitable user name:

$ createuser -SRDP username

Postgres will now prompt to Enter the password for a new user. 

Provide the password and re-enter it when prompted.

Now we shall create a database for the Mahara installation. 

Replace maharadb with a preferred name for the new database and username with the new user we just created:

$ createdb -O username -EUTF8 maharadb

We can now exit from the postgres user using the exit command.

How to use MySQL for Mahara?

Though Postgres is the recommended one for the Mahara database, we could also set up a new user and database for Mahara using MySQL. 

To do so, log in to your MySQL root account using the following command:

$ mysql -u root -p

Provide the MySQL root password to gain access. 

Now create the Mahara database. Replace maharadb with another name:

mysql> create database maharadb character set UTF8;

Next, create a new MySQL user for Mahara, set a password, and grant it access to the maharadb database. Remember to provide a strong password in place of password and replace username with your desired username:

mysql> grant all on maharadb .* to 'username '@'localhost' identified by 'password';

Now that we have created a database and a role for Mahara, next is to install and configure Mahara.

How to download Mahara ?

We can download a standard build from Mahara's server. 

The latest Mahara build is available here https://launchpad.net/mahara/+download.

We can download the .tar.gz file with the wget command. 

Make sure to replace the link with the one to the release that you selected:

$ wget https://launchpad.net/mahara/19.10/19.10.2/+download/mahara-19.10.2.tar.gz

This will download a compressed file labeled mahara-19.10.2.tar.gz. 

Extract the compressed file to create the Mahara directory structure:

$ tar xzvf mahara-19.10.2.tar.gz

Let us copy Mahara to document root of the domain.

Let it be /var/www/mahara.your_domain in the example below:

$ sudo cp -a mahara-19.10.2/. /var/www/mahara.your_domain/

Mahara must install into an empty directory. If we have files here already, we may need to change the DocumentRoot and consider using a new directory.

Mahara requires additional PHP extensions to function correctly. 

Run the following commands to install all the necessary dependencies:

$ sudo apt update
$ sudo apt install php-gd php-pgsql php-xmlrpc php-xml php-curl php-mbstring

How to create the Dataroot Directory ?

Now that we have our Mahara code set up let us create a data root directory. 

This is where Mahara will store uploaded files as well as some other files that it needs to run. Therefore, the webserver should be able to write to it.

The data root directory should also be outside the directory that contains Mahara code. 

Let us create the directory in /var/maharadata:

$ sudo mkdir /var/maharadata Update the ownership with chown:
$ sudo chown -R www-data:www-data /var/maharadata

How to set Up the Mahara Configuration File ?

Let us make some to Mahara’s config.php file to connect to the database and the encrypted password.

Switch to the Mahara code directory:

$ cd /var/www/mahara.your_domain/htdocs

Create the config.php file by copying the config-dist.php file in the htdocs directory.

$ cp config-dist.php config.php

Now open config.php using any preferred text editor and locate the following section in the file to make the required changes.

Change the $cfg->dbtype to mysql in case you are using MySQL. 

Change maharadb, username, and dbpassword to match the values for the database name, user, and password, respectively:

...
$cfg->dbtype = 'postgres';
$cfg->dbhost = 'localhost';
$cfg->dbport = null; // Change if you are using a non-standard port number for your database
$cfg->dbname = 'maharadb';
$cfg->dbuser = 'username';
$cfg->dbpass = 'dbpassword';
...

In the same file, locate the following section:

...
$cfg->dataroot = '/path/to/uploaddir';
...

Change it to point to Mahara’s data root directory:

...
$cfg->dataroot = '/var/maharadata';
...

Finally, let us update the passwordsaltmain with a random secret string.

This encrypts stored user passwords. 

Locate and uncomment the following line:

...
// $cfg->passwordsaltmain = 'some long random string here with lots of characters';
...

We can use the OpenSSL rand function to generate a random string to use as the secret salt string. 

Open a new terminal, connect to the server again, and run the following command to generate this string:

$ openssl rand -base64 32

The -base64 32 option ensures a Base64 encoded string that is 32 characters long. Update the value for passwordsaltmain to your_generated_salt:

...
$cfg->passwordsaltmain = 'your_generated_salt';
...

Once set, we must not lose this string or we will need to reset all user passwords. It is a good practice to keep a secure backup of the config.php file.

While using Mahara as a development or test site we may need to set productionmode to false. 

It will enable the on-screen display of warnings and error messages to aid in testing.

Save and close the file.

How to configure Apache for Mahara ?

If the Virtual Host configuration file is named mahara.your_domain.conf, Let's Encrypt creates a new configuration file called mahara.your_domain-le-ssl.conf that handles HTTPS requests for the domain.

Open that file. Be sure to replace mahara.your_domain with the actual name of the file:

$ sudo nano /etc/apache2/sites-available/mahara.your_domain-le-ssl.conf

The file will look similar to this:

...
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerAdmin webmaster@localhost
ServerName mahara.your_domain
DocumentRoot /var/www/mahara.your_domain
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
SSLCertificateFile /etc/letsencrypt/live/mahara.your_domain/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/mahara.your_domain/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
</IfModule>
...

The ServerName directive defines the base domain that should match for this virtual host definition. 

This should also be the domain name we chose to secure with an SSL certificate.

The Apache configuration should contain no ServerAliases. 

Mahara expects to be accessed through one URL.

Using a server alias may break Single Sign On (SSO) features.

However, if we do need an alias for some reason, we can set up a separate second VirtualHost directive in addition to the one above.

Make the following additions to the file:

...
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerAdmin webmaster@localhost
ServerName mahara.your_domain
DocumentRoot /var/www/mahara.your_domain/htdocs
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory /var/www/your_domain/htdocs>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
allow from all
</Directory>
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
SSLCertificateFile /etc/letsencrypt/live/mahara.your_domain/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/mahara.your_domain/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
</IfModule>
...

First, we update the DocumentRoot to include /htdocs. Then we will add two new blocks.

The <Directory /> block refers to the filesystem root. It specifies directives applying to all files and directories anywhere on the server. Specifying directives for this block allows us to protect the server from intrusions by placing default directives such as AllowOverride None.

The <Directory /var/www/mahara.your_domain/htdocs> block refers to the document root for Mahara. 

Directives declared here override ones declared on the <Directory /> block. These directives are the fundamental requirements for an Apache configuration to serve Mahara.

Save and close the file.

How to adjust PHP Settings for Mahara ?

The final step is to update Apache's php.ini file. This will change the logging verbosity and resize maximum upload and POST sizes.

Open the file:

$ sudo nano /etc/php/7.2/apache2/php.ini

This is a large file. Let us go through the updates one by one.

Find the log_errors line and make sure it matches the highlighted code:

. . .
log_errors = On
. . .

Setting log_errors to On will enable PHP to log errors encountered while running Mahara to aid in debugging.

Now find the line beginning upload_max_filesize = 2M. Replace 2M with 50M:

. . .
upload_max_filesize = 50M
. . .

This will increase the max upload file size to 50 megabytes.

Now find the line beginning post_max_size = 8M. Replace 8M with 100M:

. . .
post_max_size = 100M
. . .

upload_max_filesize accounts for the maximum size allowed for files posted, while post_max_size is the maximum size allowed for all POST body data. So we will always want to have this second number higher. 

These settings will enable Mahara to accept file uploads at the set maximums.

Now move to the end of the file and add the following directives:

...
register_globals = Off
magic_quotes_runtime = Off
magic_quotes_sybase = Off
magic_quotes_gpc = Off
allow_call_time_pass_reference = Off

register_globals = Off disables register_globals.

Enabling it has security implications as highlighted on PHP’s Manual.

Setting magic_quotes_runtime to Off stops PHP from automatically escaping quotes with a backslash from any functions coming in from an external source (POST/GET). magic_quotes_runtime, magic_quotes_sybase, and magic_quotes_gpc are deprecated.

allow_call_time_pass_reference is also deprecated.

Save and close the file.

Now restart Apache:

$ sudo systemctl restart apache2

How to run the Mahara Installer ?

With Apache and PHP properly configured, let us proceed to finish up Mahara’s installation through its web-based installer.

In the browser, navigate to the server’s domain name. A screen will appear displaying Mahara's licensing information and a button to continue the installation.

Click the Install Mahara button and wait until the installer finishes performing all installations. Once done, scroll down. We will see a section that says Successfully installed Mahara. Continue. Click on Continue to proceed.

Mahara will prompt us to enter a new password and a primary email address. Go ahead and submit the form.

We are ready to start using Mahara. But before we start exploring the new ePortfolio, we might want to set up a few final features.

How to Set up Email for Mahara ?

For production settings, make sure that Mahara can send out emails.

This is useful for sending out notifications such as confirmation emails after users register on the site. We can specify an outgoing SMTP server with admin settings. Click on the drop-down menu on the upper-right and choose Configure Site -> Site options -> Email.

How to Set up a Cron Job for Mahara ?

Lastly, consider setting up a cron job to hit htdocs/lib/cron.php every minute.

This helps in updating the RSS feeds and sending out email notifications. Go ahead and enter the following command:

$ sudo crontab -e

Add the following line at the bottom of the file replacing mahara.your_domain with the name of the directory where we installed Mahara.

* * * * * php /var/www/mahara.your_domain/htdocs/lib/cron.php

With the email and cron job configured, we are now ready to use Mahara.

[Are you still wondering how to install Mahara? – We're available 24*7. ]