The short version

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. If you haven't set up a PHP web application before, skip to "the long version" down below.

Set up your Apache web server. For development purposes, it is often handy to have the web root sitting inside your home directory.

Retrieve a copy of the Mahara codebase. Place it in your Apache web root.

Create a Mahara "dataroot" directory outside of your web root. Make it read/writeable by Apache.

Create a database instance and database user for Mahara to use.

Edit the Mahara "config.php" file so that Mahara knows the location of its dataroot directory, and its database login credentials.

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:

If you're on Ubuntu 14.04

php5-pgsql

php5-gd

php5-curl

php5-json

If you're on Ubuntu 16.04

php-pgsql

php-gd

php-curl

php-json

php-zip

The long version (for Windows)

The long version (for Linux)

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.

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

Note: The Node packages that come with the default installation may be outdated and not new enough for Mahara. You may need to install a later version of Node because Node 0.10 is not enough. You can find various instructions on how to upgrade NodeJS on your distribution depending on your preference on package manager

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.

As of Mahara 15.10, the main Mahara git repository includes SCSS files that compile into CSS files, instead of including CSS files directly. We compile these using a Gulp (NodeJS) script that's included with the code. This can easily be invoked via our Makefile by doing "make css", but it requires setting up a couple of additional items first.

First you'll need to run "npm install" from within the Mahara code directory, to get npm to properly set up all the proper caches and such.

cd /home/<your username>/code/mahara
npm install

Once that's finished, you'll need to install the npm "gulp" package using the "-g" (global) flag, so that "gulp" can be run as a CLI command. This requires using sudo.

cd /home/<your username>/code/mahara
sudo npm install -g gulp

13. Build the CSS

Now that this is done, you can build the CSS files. The easiest way to do this is by doing "make css" in the Mahara code directory. This will run the necessary series of instructions written out in the Makefile.

Submitting a change to Gerrit

If you want to contribute a patch to the Mahara project yourself, please check out the wiki page on contributing code. There is also a troubleshooting page in case you run into issues pushing code to Gerrit.

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.

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"

$ vim sites-available/mahara.conf (or the name of your config file of the site for which you want to enable SSL)

Paste the following into the .conf file after the </VirtualHost> for port 80. The last re-write rules are only necessary if you use the "Clean URL" functionality.

<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerName mahara
DocumentRoot /home/'''<your username>'''/code/mahara/htdocs
<Directory /home/'''<your username>'''/code>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Require all granted
</Directory>
ErrorLog /var/log/apache2/mahara-ssl-error.log
LogLevel info
CustomLog /var/log/apache2/mahara-ssl-access.log combined
# SSL Engine Switch:# Enable/Disable SSL for this virtual host.
SSLEngine on
# A self-signed (snakeoil) certificate can be created by installing# the ssl-cert package. See# /usr/share/doc/apache2.2-common/README.Debian.gz for more info.# If both key and certificate are stored in the same file, only the# SSLCertificateFile directive is needed.
SSLCertificateFile /etc/apache2/ssl/apache.pem
SSLCertificateKeyFile /etc/apache2/ssl/apache.key
# Server Certificate Chain:# Point SSLCertificateChainFile at a file containing the# concatenation of PEM encoded CA certificates which form the# certificate chain for the server certificate. Alternatively# the referenced file can be the same as SSLCertificateFile# when the CA certificates are directly appended to the server# certificate for convinience.#SSLCertificateChainFile /etc/apache2/ssl.crt/server-ca.crt# Certificate Authority (CA):# Set the CA certificate verification path where to find CA# certificates for client authentication or alternatively one# huge file containing all of them (file must be PEM encoded)# Note: Inside SSLCACertificatePath you need hash symlinks# to point to the certificate files. Use the provided# Makefile to update the hash symlinks after changes.#SSLCACertificatePath /etc/ssl/certs/#SSLCACertificateFile /etc/apache2/ssl.crt/ca-bundle.crt# Certificate Revocation Lists (CRL):# Set the CA revocation path where to find CA CRLs for client# authentication or alternatively one huge file containing all# of them (file must be PEM encoded)# Note: Inside SSLCARevocationPath you need hash symlinks# to point to the certificate files. Use the provided# Makefile to update the hash symlinks after changes.#SSLCARevocationPath /etc/apache2/ssl.crl/#SSLCARevocationFile /etc/apache2/ssl.crl/ca-bundle.crl# Client Authentication (Type):# Client certificate verification type and depth. Types are# none, optional, require and optional_no_ca. Depth is a# number which specifies how deeply to verify the certificate# issuer chain before deciding the certificate is not valid.#SSLVerifyClient require#SSLVerifyDepth 10# Access Control:# With SSLRequire you can do per-directory access control based# on arbitrary complex boolean expressions containing server# variable checks and other lookup directives. The syntax is a# mixture between C and Perl. See the mod_ssl documentation# for more details.#<Location />#SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)/ \# and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \# and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \# and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \# and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \# or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/#</Location># SSL Engine Options:# Set various options for the SSL engine.# o FakeBasicAuth:# Translate the client X.509 into a Basic Authorisation. This means that# the standard Auth/DBMAuth methods can be used for access control. The# user name is the `one line' version of the client's X.509 certificate.# Note that no password is obtained from the user. Every entry in the user# file needs this password: `xxj31ZMTZzkVA'.# o ExportCertData:# This exports two additional environment variables: SSL_CLIENT_CERT and# SSL_SERVER_CERT. These contain the PEM-encoded certificates of the# server (always existing) and the client (only existing when client# authentication is used). This can be used to import the certificates# into CGI scripts.# o StdEnvVars:# This exports the standard SSL/TLS related `SSL_*' environment variables.# Per default this exportation is switched off for performance reasons,# because the extraction step is an expensive operation and is usually# useless for serving static content. So one usually enables the# exportation for CGI and SSI requests only.# o StrictRequire:# This denies access when "SSLRequireSSL" or "SSLRequire" applied even# under a "Satisfy any" situation, i.e. when it applies access is denied# and no other module can change it.# o OptRenegotiate:# This enables optimized SSL connection renegotiation handling when SSL# directives are used in per-directory context.#SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire
<FilesMatch "\.(cgi|shtml|phtml|php)$">
SSLOptions +StdEnvVars
</FilesMatch>
# SSL Protocol Adjustments:# The safe and default but still SSL/TLS standard compliant shutdown# approach is that mod_ssl sends the close notify alert but doesn't wait for# the close notify alert from client. When you need a different shutdown# approach you can use one of the following variables:# o ssl-unclean-shutdown:# This forces an unclean shutdown when the connection is closed, i.e. no# SSL close notify alert is send or allowed to received. This violates# the SSL/TLS standard but is needed for some brain-dead browsers. Use# this when you receive I/O errors because of the standard approach where# mod_ssl sends the close notify alert.# o ssl-accurate-shutdown:# This forces an accurate shutdown when the connection is closed, i.e. a# SSL close notify alert is send and mod_ssl waits for the close notify# alert of the client. This is 100% SSL/TLS standard compliant, but in# practice often causes hanging connections with brain-dead browsers. Use# this only for browsers where you know that their SSL implementation# works correctly.# Notice: Most problems of broken clients are also related to the HTTP# keep-alive facility, so you usually additionally want to disable# keep-alive for those clients, too. Use variable "nokeepalive" for this.# Similarly, one has to force some clients to use HTTP/1.0 to workaround# their broken HTTP/1.1 implementation. Use variables "downgrade-1.0" and# "force-response-1.0" for this.
BrowserMatch "MSIE [2-6]"\
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
# MSIE 7 and newer should be able to use keepalive
BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule ^/user/([a-z0-9-]+)/?$ /user/view.php?profile=$1&%{QUERY_STRING}
RewriteRule ^/user/([a-z0-9-]+)/([a-z0-9-]+)/?$ /view/view.php?profile=$1&page=$2&%{QUERY_STRING}
RewriteRule ^/group/([a-z0-9-]+)/?$ /group/view.php?homepage=$1&%{QUERY_STRING}
RewriteRule ^/group/([a-z0-9-]+)/([a-z0-9-]+)/?$ /view/view.php?homepage=$1&page=$2&%{QUERY_STRING}
</IfModule>
</VirtualHost>
</IfModule>

4. Create the SSL folder in /etc/apache2/ if it doesn't already exist:

$ sudo mkdir /etc/apache2/ssl

5. Run the following command to set up your local cert and follow the ensuing steps for generating it: