Developer Area/Developer Environment: Difference between revisions
From Mahara Wiki
< Developer Area
m (→Node) |
|||
(65 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
{{:Developer_Area/tabs}} <!-- to add further tabs, update the following page https://wiki.mahara.org/wiki/Developer_Area/tabs ... this will automatically cascade the changes to all relevant pages --> | |||
<div style="float:right">__TOC__</div> | |||
🚧 Note: this wiki is in the process of migrating to our GitLab Wiki. | |||
This page explains how to set up a copy of Mahara for development purposes. | This page explains how to set up a copy of Mahara for development purposes. | ||
== The short version == | ==The Docker version== | ||
Included in the main codebase is a docker version of Mahara with Behat capabilities. Before you try this, you will need to have Docker installed. | |||
See: https://docs.docker.com/engine/install/ubuntu/ | |||
The instructions for running the docker version are here:<br> | |||
https://git.mahara.org/mahara/mahara/-/blob/main/docker/README.md | |||
Please feel free to update if there are missing instructions that would be helpful to others. | |||
==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 | 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. | #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. | #Retrieve a copy of the Mahara codebase. Place it in your Apache web root. | ||
# Create a Mahara | #Create a Mahara <code>dataroot</code> directory '''outside''' your web root. Make it read/writeable by Apache. | ||
# Create a database instance and database user for Mahara to use. | #Create a database instance and database user for Mahara to use. | ||
# Edit the Mahara | #Edit the Mahara <code>config.php</code> file so that Mahara knows the location of its <code>dataroot</code> 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 | #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 have already installed, you may need one or more of these: | ||
# | ##<syntaxhighlight lang="text" inline="">php-pgsql</syntaxhighlight> | ||
##<syntaxhighlight lang="text" inline="">php-gd</syntaxhighlight> | |||
# | ##<syntaxhighlight lang="text" inline="">php-curl</syntaxhighlight> | ||
# | ##<syntaxhighlight lang="text" inline="">php-intl</syntaxhighlight> | ||
# | ##<syntaxhighlight lang="text" inline="">php-json</syntaxhighlight> | ||
# | ##<syntaxhighlight lang="text" inline="">php-zip</syntaxhighlight> | ||
#If you are using MySQL instead of Postgres | |||
# | ##<syntaxhighlight lang="text" inline="">php7.4-mysql</syntaxhighlight> or | ||
# | ##<syntaxhighlight lang="text" inline="">php-mysql</syntaxhighlight> | ||
# | |||
# | |||
== The long version (for Windows) == | ==The long version (for Windows)== | ||
If you want to install your developer environment on Windows, please [[Developer_Area/Developer_Environment_(Windows) | check the Windows instructions]]. | If you want to install your developer environment on Windows, please [[Developer_Area/Developer_Environment_(Windows) | check the Windows instructions]]. | ||
== The long version (for Linux) == | ==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 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 | Note: Please have an apache2 installed on your server | ||
<syntaxhighlight lang="bash"> | |||
sudo apt install apache2 | |||
</syntaxhighlight> | |||
'''The following instructions are for Ubuntu 22.10 and above, unless otherwise noted.''' | |||
=== Install required packages: === | |||
< | ==== PHP 7.4 ==== | ||
sudo apt | <syntaxhighlight lang="bash"> | ||
sudo apt install \ | |||
make curl wget xvfb git gitk 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 php-mbstring \ | |||
nodejs php7.4-pgsql php7.4-xml php7.4-xmlrpc php7.4-mbstring php7.4-intl libssl-dev pdo_sqlite php7.4-zip | |||
# Set 7.4 as apache2's version of php | |||
sudo a2enmod php7.4 | |||
</syntaxhighlight> | |||
< | ==== PHP 8.1 ==== | ||
sudo apt | <syntaxhighlight lang="bash"> | ||
sudo apt install \ | |||
make curl wget xvfb git gitk postgresql php8.1-common php-cli libapache2-mod-php8.1 \ | |||
php8.1-curl php8.1-gd php-json php-ldap php-pgsql php-xmlrpc php-zip php-xml php-mbstring \ | |||
nodejs php8.1-pgsql php8.1-xml php8.1-xmlrpc php8.1-mbstring php8.1-intl libssl-dev pdo_sqlite php8.1-zip | |||
# Set 8.1 as apache2's version of php | |||
sudo a2enmod php8.1 | |||
</syntaxhighlight>If you encounter any errors with the installation, you may want to try installing in chunks. See the [https://wiki.mahara.org/wiki/Developer_Area/Developer_Environment?section=8#Trouble-shooting Troubleshooting] section. | |||
</ | |||
If you | |||
==== To switch between PHP versions ==== | |||
<code>sudo a2dismod php7.4</code> | |||
<code>sudo a2enmod php8.1</code> | |||
<code>sudo update-alternatives --config php</code> | |||
<code>sudo service apache2 restart</code> | |||
< | |||
</ | |||
==== Node ==== | |||
Check which version of Node you are running with <syntaxhighlight lang="bash" inline="">node -v</syntaxhighlight> To install: <code>sudo apt install nodejs</code> | |||
=== Get a copy of the codebase === | |||
Get a copy of the Mahara code from git. We'll put it under your home directory, in a new directory called <code>code</code>: See also [[Developer_Area/Getting_Code_from_Git|Getting Code from Git]] | |||
< | <syntaxhighlight lang="bash"> | ||
cd ~ | cd ~ | ||
mkdir code | mkdir code | ||
cd code | cd code | ||
# if you have an account on git.mahara.org ... | |||
git clone [email protected]:mahara/mahara.git | |||
# else, use http... | |||
git clone https://git.mahara.org/mahara/mahara.git | git clone https://git.mahara.org/mahara/mahara.git | ||
# if that doesn't work, try... | |||
git clone https://github.com/MaharaProject/mahara.git | |||
</syntaxhighlight> | |||
< | ==== Fix permissions ==== | ||
Give the Apache web server access to your Mahara code directory:<syntaxhighlight lang="bash"> | |||
# Give all users read access + executable (if required) to the mahara directory | |||
sudo chmod a+rX ~/code/mahara | |||
# To avoid a possible 403 error later, confirm that your code directory permissions are also drwxr-xr-x | |||
ls -la ~/ | |||
# To fix, run: | |||
sudo chmod a+ | sudo chmod a+rX ~/code | ||
# Your home directory permissions should be drwx--x--x | |||
ls -la /home # to check | |||
ls -la | |||
# To fix, run: | |||
sudo chmod a+X /home/[name of your home directory] | |||
</syntaxhighlight> | |||
sudo chmod a+ | |||
</ | |||
=== Create a Mahara database === | |||
< | ==== Create a PostgreSQL database user ==== | ||
<syntaxhighlight lang="bash"> | |||
# Use maharapassword as the password | |||
sudo -u postgres createuser -P -D -R -S maharauser | sudo -u postgres createuser -P -D -R -S maharauser | ||
</ | </syntaxhighlight> | ||
If Postgres is not available, check its status and if it says that it's inactive, start the service: | If Postgres is not available, check its status and if it says that it's inactive, start the service: | ||
< | <syntaxhighlight lang="bash"> | ||
# Check status | |||
service postgresql status | service postgresql status | ||
# Restart service | |||
sudo service postgresql start | sudo service postgresql start | ||
</ | </syntaxhighlight> | ||
==== Create a database ==== | |||
<syntaxhighlight lang="bash"> | |||
sudo -u postgres createdb -Omaharauser mahara-main | |||
</syntaxhighlight> | |||
< | '''5.''' Using a text editor, copy these contents into a file and save it to <syntaxhighlight lang="text" inline="">~/code/mahara/htdocs/config.php</syntaxhighlight>: | ||
</ | |||
<syntaxhighlight lang="php"> | |||
<?php | <?php | ||
$cfg = new stdClass(); | $cfg = new stdClass(); | ||
$branch = ' | $branch = 'main'; | ||
// database connection details | // database connection details | ||
Line 157: | Line 171: | ||
$cfg->productionmode = false; | $cfg->productionmode = false; | ||
$cfg->perftofoot = true; | $cfg->perftofoot = true; | ||
</ | </syntaxhighlight> | ||
Make sure to replace < | Make sure to replace <syntaxhighlight lang="text" inline=""><your email address></syntaxhighlight> with your email address. | ||
If you're mainly testing, and you don't find the stack traces in these screen messages particularly useful, adding < | If you're mainly testing, and you don't find the stack traces in these screen messages particularly useful, adding <syntaxhighlight lang="text" inline="">$cfg->log_backtrace_levels = LOG_LEVEL_ENVIRON;</syntaxhighlight> to config.php will display important warning messages on a single line, without stack traces. | ||
=== Set up <code>dataroot</code>, host, and site === | |||
< | ==== Create a <code>dataroot</code> directory ==== | ||
This is where Mahara stores uploaded files):<syntaxhighlight lang="bash"> | |||
sudo mkdir /var/lib/maharadata | sudo mkdir /var/lib/maharadata | ||
sudo mkdir /var/lib/maharadata/ | sudo mkdir /var/lib/maharadata/main | ||
sudo chown www-data:www-data /var/lib/maharadata/ | sudo chown www-data:www-data /var/lib/maharadata/main | ||
</ | </syntaxhighlight> | ||
==== Set up local domain ==== | |||
Set up a new local domain name <code>mahara</code> for your Mahara site, in <code>/etc/hosts:</code><syntaxhighlight lang="bash"> | |||
< | |||
sudo sh -c "echo '127.0.0.1 mahara' >> /etc/hosts" | sudo sh -c "echo '127.0.0.1 mahara' >> /etc/hosts" | ||
</ | </syntaxhighlight> | ||
< | ==== Increase your PHP <code>post_max_size</code> ==== | ||
sudo sh -c "echo ' | These files will be under the version of php you are using, e.g. /etc/php/<PHP version>:<syntaxhighlight lang="bash"> | ||
sudo sh -c "echo 'post_max_size = | # for PHP 7.4 | ||
sudo sh -c "echo 'post_max_size = 37M' >> /etc/php/7.4/cli/php.ini" | |||
sudo sh -c "echo 'upload_max_filesize = 32M' >> /etc/php/7.4/cli/php.ini" | |||
sudo sh -c "echo 'post_max_size = 37M' >> /etc/php/7.4/apache2/php.ini" | |||
sudo sh -c "echo 'upload_max_filesize = 32M' >> /etc/php/7.4/apache2/php.ini" | |||
# for PHP 8.1 | |||
sudo sh -c "echo 'post_max_size = 37M' >> /etc/php/8.1/cli/php.ini" | |||
sudo sh -c "echo 'upload_max_filesize = 32M' >> /etc/php/8.1/cli/php.ini" | |||
sudo sh -c "echo 'post_max_size = 37M' >> /etc/php/8.1/apache2/php.ini" | |||
sudo sh -c "echo 'upload_max_filesize = 32M' >> /etc/php/8.1/apache2/php.ini" | |||
</syntaxhighlight> | |||
Note: The 'post_max_size' is slightly bigger, as a POST command also contains some wrapper information. That wrapper is just text strings and relates to how much the form submits. So usually, 1 MB should be enough, but to be on the safe side, 5 MB would be better, which then also works for larger uploads. | |||
==== Create an Apache config file ==== | |||
You can do this by first copying the following contents into a file called <code>mahara.conf</code>, saved in your home directory. | |||
See also: [[Developer_Area/Changing_Hostnames|Changing Hostnames]] | |||
< | <syntaxhighlight lang="apache"> | ||
<VirtualHost *:80> | <VirtualHost *:80> | ||
ServerName mahara | ServerName mahara | ||
Line 211: | Line 229: | ||
DirectoryIndex index.php index.html | DirectoryIndex index.php index.html | ||
</VirtualHost> | </VirtualHost> | ||
</ | </syntaxhighlight> | ||
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. | 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. | ||
<syntaxhighlight lang="text" inline="">sudo cp ~/mahara.conf /etc/apache2/sites-available/mahara.conf</syntaxhighlight> | |||
< | ==== Enable the site in Apache ==== | ||
<syntaxhighlight lang="bash"> | |||
sudo a2ensite mahara | sudo a2ensite mahara | ||
sudo apache2ctl configtest | sudo apache2ctl configtest | ||
sudo apache2ctl graceful | sudo apache2ctl graceful | ||
</ | </syntaxhighlight> | ||
<code>composer update && make initcomposerdev</code> | |||
< | === Set up <code>cron</code>: === | ||
<syntaxhighlight lang="bash"> | |||
# To get cron emails every minute: | |||
sudo vim /etc/cron.d/mahara | sudo vim /etc/cron.d/mahara | ||
* * * * * www-data /usr/bin/php /home/<your username>/code/mahara/htdocs/lib/cron.php | * * * * * www-data /usr/bin/php /home/<your username>/code/mahara/htdocs/lib/cron.php | ||
# Otherwise: | |||
sudo vim /etc/cron.d/mahara | sudo vim /etc/cron.d/mahara | ||
* * * * * www-data /usr/bin/php /home/<your username>/code/mahara/htdocs/lib/cron.php >/dev/null 2>&1 | * * * * * www-data /usr/bin/php /home/<your username>/code/mahara/htdocs/lib/cron.php >/dev/null 2>&1 | ||
</ | </syntaxhighlight> | ||
=== Set up <code>npm</code> and <code>gulp</code> for theming === | |||
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 "<code>make css</code>, but it requires setting up a couple of additional items first. | |||
<syntaxhighlight lang="bash"> | |||
# 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 | cd /home/<your username>/code/mahara | ||
npm install | 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. | # 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 | cd /home/<your username>/code/mahara | ||
sudo npm install -g gulp | sudo npm install -g gulp | ||
# Mahara runs with at least version 14.x of node. | |||
sudo npm cache clean -f | |||
sudo npm install -g n | |||
sudo nvm use stable | |||
< | # Then update node-sass bindings: | ||
sudo npm rebuild node-sass | |||
</syntaxhighlight> | |||
==== Build the themes (CSS) ==== | |||
Run <code>make css</code> in the Mahara code directory to compile the CSS for Mahara themes. This will run the necessary series of instructions written out in the Makefile (including <code>npm install</code> for both the development and production JS libraries. | |||
<syntaxhighlight lang="bash"> | |||
cd /home/<your username>/code/mahara | cd /home/<your username>/code/mahara | ||
make css | make css | ||
If you see a lot of errors, such as depreciation warnings for .css files | # If you see a lot of errors, such as depreciation warnings for .css files: | ||
# Delete your /home/<your username>/code/mahara/package-lock.json | |||
# Then re-run "nvm install" and "make css", which should resolve the issues. | |||
# If you run 'make css' and see the following "ERROR: Can't find the "nvm" executable ..." try the following: | |||
# Steps (for me) to get nvm working | |||
## First Install nvm | |||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash | |||
Then | ## Then make the .nvm.sh executable | ||
< | cd ~/.nvm && chmod 755 nvm.sh | ||
## Then reload your .bashrc file | |||
source ~/.bashrc | |||
## The set the first nvm version manually to create a default | |||
./nvm.sh && nvm install 12 | |||
</syntaxhighlight> | |||
==== Build the CSS in non-production mode ==== | |||
Sometimes it gets confusing where the SASS info comes from to compile the css files. To make things easier, you can edit the 'Makefile' and change the production mode to false. | |||
<code>production = false</code> | |||
Then run the <code>make css</code> again - this will compile the theming files to create <code>*.css</code> files in an easier to read format with comments about which sass file contributed to the chuck of CSS code, e.g.: | |||
<syntaxhighlight lang="css"> | |||
/* line 27, /home/robertl/code/mahara-devel/mahara/htdocs/theme/raw/sass/layout/_footer.scss */ | /* line 27, /home/robertl/code/mahara-devel/mahara/htdocs/theme/raw/sass/layout/_footer.scss */ | ||
.admin .footer .footer-inner { | .admin .footer .footer-inner { | ||
Line 315: | Line 333: | ||
border: 0; | border: 0; | ||
border-radius: 0; } | border-radius: 0; } | ||
</ | </syntaxhighlight> | ||
=== Go to the site in your browser === | |||
[http://mahara/ https://mahara/] | |||
You should see the Mahara installer page. If you do, congratulations! Your development environment is now set up. | |||
==Trouble-shooting== | |||
=== Checking what version of PHP is running on your site === | |||
The PHP version on the CLI can be different to what is running on the site, especially if you run php-fpm which allows having two PHP servers of different serving different PHP versions. | |||
To check the PHP version your site is serving, create the file <code>/htdocs/test.php</code> and populate it with following lines.<syntaxhighlight lang="php"> | |||
<?php | |||
phpinfo(); | |||
// In your browser go to <your wwwroot>/test.php | |||
</syntaxhighlight> | |||
=== Ubuntu 22.04 & PHP 8.x === | |||
By default Ubuntu 22.04 will have PHP 8.2 enabled | |||
To run commands on a different PHP version (e.g. 8.x) run: <code>sudo update-alternatives --set php /usr/bin/php8.x</code> | |||
Run <code>composer update && make initcomposerdev</code> so the composer.lock file matches your PHP version. | |||
===Enabling apache2's version of PHP=== | |||
When you do: | |||
<syntaxhighlight lang="bash"> | |||
# for PHP 7.4 | |||
sudo a2enmod php7.4 | |||
# for PHP 8.1 | |||
sudo a2enmod php8.1 | |||
</syntaxhighlight> | |||
===Using MySql8=== | |||
If you are going to be using '''MySql 8''' or later, you will need to do the following: | |||
*To install MySql 8 on Ubuntu 16.04 see https://www.digitalocean.com/community/tutorials/how-to-install-the-latest-mysql-on-ubuntu-16-04 | |||
We need to add a line to our mysql conf file so that we can log in with older format passwords, so edit: | |||
<syntaxhighlight lang="bash"> | |||
vi /etc/mysql/mysql.conf.d/mysqld.cnf | |||
</syntaxhighlight> | |||
And make sure we have | |||
<syntaxhighlight lang="bash"> | |||
[mysqld] | |||
default_authentication_plugin=mysql_native_password | |||
</syntaxhighlight> | |||
You will need to set the db user to use the native password | |||
CREATE USER 'maharauser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'mahara'; | |||
=====MySQL in Docker===== | |||
If you have Docker available you can [[System Administrator's Guide/Installing Mahara/MySQL and Docker|spin it up a dedicated container for it]]. | |||
===Installing Node versions=== | |||
Check which version of Node you are running with | |||
<syntaxhighlight lang="bash"> | |||
node -v | |||
</syntaxhighlight> | |||
If you are running one of the long term service (lts) versions, 8.x or 10.x, that should work with Mahara fine. If you are running a higher version, or Node is not installed, you will need to add a version to run with Mahara. | |||
You can find various instructions on how to upgrade NodeJS on your distribution depending on your preference on package manager. (There are a couple of links at the bottom of this section.) | |||
A straight-forward way to manage multiple versions of Node is to use NVM: | |||
*[https://github.com/creationix/nvm#install-script/ How to install NVM] | |||
Once you have it installed run: | |||
<syntaxhighlight lang="bash"> | |||
nvm install --lts | |||
nvm use --lts | |||
</syntaxhighlight> | |||
This will download the latest lts version of Node and set it to default. Then if you need to switch versions for other projects, you can do so with "nvm use <version>". | |||
Links to alternative ways of installing Node: | |||
*[https://nodejs.org/en/download/package-manager/ Installing Node.js via package manager] | |||
*[https://tecadmin.net/install-latest-nodejs-npm-on-ubuntu/ How to Install Latest Nodejs & Npm on Ubuntu 16.04 & 14.04] | |||
ts-php versions - also add set alternatives here | |||
Note on changing versions: you can see which version apache is using by adding phpinfo() in your code. | |||
==Adding another branch== | ==Adding another branch== | ||
'''1.''' Create a new local branch for it in git (replace '''1.10 / 110''' with the version of Mahara for which you want to add a branch) | '''1.''' Create a new local branch for it in git (replace '''1.10 / 110''' with the version of Mahara for which you want to add a branch) | ||
< | <syntaxhighlight lang="bash"> | ||
$ cd ~/code/mahara | $ cd ~/code/mahara | ||
$ git checkout -t origin/1.10_STABLE | $ git checkout -t origin/1.10_STABLE | ||
</ | </syntaxhighlight> | ||
'''2.''' Create the sitedata directory for the new branch: | '''2.''' Create the sitedata directory for the new branch: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo mkdir /var/lib/maharadata/110stable | $ sudo mkdir /var/lib/maharadata/110stable | ||
$ sudo chown www-data:www-data /var/lib/maharadata/110stable | $ sudo chown www-data:www-data /var/lib/maharadata/110stable | ||
</ | </syntaxhighlight> | ||
'''3.''' Create a database: | '''3.''' Create a database: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo -u postgres createdb -Omaharauser mahara-110stable | $ sudo -u postgres createdb -Omaharauser mahara-110stable | ||
</ | </syntaxhighlight> | ||
'''4.''' Change your ~/code/mahara/htdocs/config.php to point to the 1.10 branch: | '''4.''' Change your ~/code/mahara/htdocs/config.php to point to the 1.10 branch: | ||
< | <syntaxhighlight lang="php"> | ||
$branch = '110stable'; | $branch = '110stable'; | ||
</ | </syntaxhighlight> | ||
'''5.''' Go to the site in your browser to run the Mahara installer: | '''5.''' Go to the site in your browser to run the Mahara installer: | ||
Line 351: | Line 447: | ||
http://mahara/ | http://mahara/ | ||
==Switching back to the main branch== | |||
==Switching back to the | |||
'''1.''' Change the config.php file: | '''1.''' Change the config.php file: | ||
< | <syntaxhighlight lang="php"> | ||
$branch = ' | $branch = 'main'; | ||
</ | </syntaxhighlight> | ||
'''2.''' Switch to the right git branch: | '''2.''' Switch to the right git branch: | ||
< | <syntaxhighlight lang="bash"> | ||
$ cd ~/code/mahara/ | $ cd ~/code/mahara/ | ||
$ git checkout | $ git checkout main | ||
</ | </syntaxhighlight> | ||
| | ||
Line 370: | Line 464: | ||
'''1.''' Delete the old database: | '''1.''' Delete the old database: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo -u postgres dropdb mahara- | $ sudo -u postgres dropdb mahara-main | ||
</ | </syntaxhighlight> | ||
'''2.''' Create a new one with the same name: | '''2.''' Create a new one with the same name: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo -u postgres createdb -Omaharauser mahara- | $ sudo -u postgres createdb -Omaharauser mahara-main | ||
</ | </syntaxhighlight> | ||
'''3.''' Go to the site in your browser to run the Mahara installer again: | '''3.''' Go to the site in your browser to run the Mahara installer again: | ||
Line 388: | Line 482: | ||
'''1.''' Go to the change page, for example: | '''1.''' Go to the change page, for example: | ||
< | <syntaxhighlight lang="bash"> | ||
https://reviews.mahara.org/#change,230 | https://reviews.mahara.org/#change,230 | ||
</ | </syntaxhighlight> | ||
'''2.''' In your local repository, switch to the branch listed in the Gerrit change (in this case: | '''2.''' In your local repository, switch to the branch listed in the Gerrit change (in this case: main): | ||
< | <syntaxhighlight lang="bash"> | ||
$ cd ~/code/mahara | $ cd ~/code/mahara | ||
$ git checkout | $ git checkout main | ||
</ | </syntaxhighlight> | ||
'''3.''' Update your config.php to use the right branch, too. | '''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, for example: | '''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, for example: | ||
< | <syntaxhighlight lang="bash"> | ||
$ git fetch git://reviews.mahara.org/git/mahara refs/changes/30/230/1 && git checkout FETCH_HEAD | $ git fetch git://reviews.mahara.org/git/mahara refs/changes/30/230/1 && git checkout FETCH_HEAD | ||
$ make css | $ make css | ||
</ | </syntaxhighlight> | ||
'''5.''' After finishing the testing, go back to | '''5.''' After finishing the testing, go back to main: | ||
< | <syntaxhighlight lang="bash"> | ||
$ git checkout | $ git checkout main | ||
$ make css | $ make css | ||
</ | </syntaxhighlight> | ||
| | ||
Line 424: | Line 518: | ||
'''1.''' Do a checkout of the code into a new directory: | '''1.''' Do a checkout of the code into a new directory: | ||
< | <syntaxhighlight lang="bash"> | ||
$ cd ~ | $ cd ~ | ||
$ mkdir code | $ mkdir code | ||
$ cd code | $ cd code | ||
$ git clone [email protected]:mahara/mahara.git 15stable | $ git clone [email protected]:mahara/mahara.git 15stable | ||
</ | </syntaxhighlight> | ||
'''2.''' Copy the database: | '''2.''' Copy the database: | ||
<syntaxhighlight lang="bash"> | |||
< | |||
$ sudo -u postgres pg_dump -Fc mahara-14stable > 14stable.pg | $ sudo -u postgres pg_dump -Fc mahara-14stable > 14stable.pg | ||
$ sudo -u postgres createdb -Omaharauser mahara-15stable | $ sudo -u postgres createdb -Omaharauser mahara-15stable | ||
$ sudo -u postgres pg_restore -O -j4 -d mahara-15stable -U maharauser -W -h localhost 14stable.pg | $ sudo -u postgres pg_restore -O -j4 -d mahara-15stable -U maharauser -W -h localhost 14stable.pg | ||
</ | </syntaxhighlight> | ||
If you've not given the user 'maharauser' full privileges yet (should only need to do this once) | If you've not given the user 'maharauser' full privileges yet (should only need to do this once) | ||
< | <syntaxhighlight lang="bash"> | ||
$ 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 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 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 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;' | $ sudo -u postgres psql -d mahara-15stable -c 'GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO maharauser;' | ||
</ | </syntaxhighlight> | ||
'''3.''' Change the wwwroot in the new database: | '''3.''' Change the wwwroot in the new database: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo -u postgres psql mahara-15stable | $ sudo -u postgres psql mahara-15stable | ||
delete from config where field = 'wwwroot'; | delete from config where field = 'wwwroot'; | ||
Ctrl + d to exit | Ctrl + d to exit | ||
</ | </syntaxhighlight> | ||
'''4.''' Create the config file ~/code/mahara/htdocs/config.php: | '''4.''' Create the config file ~/code/mahara/htdocs/config.php: | ||
< | <syntaxhighlight lang="php"> | ||
<?php | <?php | ||
$cfg = new StdClass; | $cfg = new StdClass; | ||
Line 496: | Line 574: | ||
$cfg->log_environ_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG; | $cfg->log_environ_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG; | ||
$cfg->perftofoot = true; | $cfg->perftofoot = true; | ||
</ | </syntaxhighlight> | ||
'''5.''' Copy the source sitedata directory into the new sitedata folder: | '''5.''' Copy the source sitedata directory into the new sitedata folder: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo cp -r /var/lib/maharadata/14stable/ /var/lib/maharadata/15stable | $ sudo cp -r /var/lib/maharadata/14stable/ /var/lib/maharadata/15stable | ||
$ sudo chown -R www-data:www-data /var/lib/maharadata/15stable | $ sudo chown -R www-data:www-data /var/lib/maharadata/15stable | ||
</ | </syntaxhighlight> | ||
'''6.''' Add a new entry to /etc/hosts: | '''6.''' Add a new entry to /etc/hosts: | ||
< | <syntaxhighlight lang="bash"> | ||
127.0.0.1 15stable | 127.0.0.1 15stable | ||
</ | </syntaxhighlight> | ||
'''7.''' Create a new Apache vhost file in /etc/apache2/sites-available/15stable.conf: | '''7.''' Create a new Apache vhost file in /etc/apache2/sites-available/15stable.conf: | ||
< | <syntaxhighlight lang="apacheconf"> | ||
<VirtualHost *:80> | <VirtualHost *:80> | ||
ServerName 15stable | ServerName 15stable | ||
Line 527: | Line 605: | ||
DirectoryIndex index.php index.html | DirectoryIndex index.php index.html | ||
</VirtualHost> | </VirtualHost> | ||
</ | </syntaxhighlight> | ||
'''8.''' Enable the site in Apache: | '''8.''' Enable the site in Apache: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo a2ensite 15stable | $ sudo a2ensite 15stable | ||
$ sudo apache2ctl configtest | $ sudo apache2ctl configtest | ||
$ sudo apache2ctl graceful | $ sudo apache2ctl graceful | ||
</ | </syntaxhighlight> | ||
'''9.''' Go to the site in your browser to run the Mahara installer: | '''9.''' Go to the site in your browser to run the Mahara installer: | ||
< | <syntaxhighlight lang="bash"> | ||
http://15stable/ | http://15stable/ | ||
</ | </syntaxhighlight> | ||
'''10.''' Resetting the admin password: | '''10.''' Resetting the admin password: | ||
Line 551: | Line 629: | ||
| | ||
== Elasticsearch == | ==Elasticsearch== | ||
If you want to test the Elasticsearch search plugin, you'll also need to set up and run an Elasticsearch server. See [[Developer Area/Setting up Elasticsearch]]. | If you want to test the Elasticsearch search plugin, you'll also need to set up and run an Elasticsearch server. See [[Developer Area/Setting up Elasticsearch]]. | ||
| |||
==ClamAV== | |||
If you want to test the ClamAV virus protection see [[Developer Area/Setting up ClamAV|Setting up ClamAV]] | |||
| | ||
== Set up site for local https:// == | ==Set up site for local https://== | ||
You will need to set up your Mahara developer site with an SSL certificate if you want to use the web services functionality as that is only available over https. | You will need to set up your Mahara developer site with an SSL certificate if you want to use the web services functionality as that is only available over https. | ||
Line 562: | Line 643: | ||
You should already have Apache 2 installed on your computer. Otherwise, Mahara wouldn't run. Install the openssl and ssl-cert packages: | You should already have Apache 2 installed on your computer. Otherwise, Mahara wouldn't run. Install the openssl and ssl-cert packages: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo apt-get install openssl ssl-cert | $ sudo apt-get install openssl ssl-cert | ||
</ | </syntaxhighlight> | ||
'''1.''' Enable SSL in Apache 2: | '''1.''' Enable SSL in Apache 2: | ||
< | <syntaxhighlight lang="bash"> | ||
$ cd /etc/apache2/mods-enabled/ | $ cd /etc/apache2/mods-enabled/ | ||
$ ls | $ ls | ||
Line 573: | Line 654: | ||
$ service apache2 restart | $ service apache2 restart | ||
$ ls | $ ls | ||
</ | </syntaxhighlight> | ||
You should see "ssl.conf" and "ssl.load" | You should see "ssl.conf" and "ssl.load" | ||
'''2.''' You'll need to check that the port for SSL traffic is configured. | '''2.''' You'll need to check that the port for SSL traffic is configured. | ||
< | <syntaxhighlight lang="bash"> | ||
$ cd .. | $ cd .. | ||
$ cat ports.conf | $ cat ports.conf | ||
</ | </syntaxhighlight> | ||
If you see '''<IfModule ssl_module> Listen 443''', you are good to go. | If you see '''<IfModule ssl_module> Listen 443''', you are good to go. | ||
'''3.''' Enable SSL also in your Mahara Apache 2 config file. | '''3.''' Enable SSL also in your Mahara Apache 2 config file. | ||
< | <syntaxhighlight lang="bash"> | ||
$ vim sites-available/mahara.conf (or the name of your config file of the site for which you want to enable SSL) | $ vim sites-available/mahara.conf (or the name of your config file of the site for which you want to enable SSL) | ||
</ | </syntaxhighlight> | ||
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. | 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. | ||
< | <syntaxhighlight lang="apache"> | ||
<IfModule mod_ssl.c> | <IfModule mod_ssl.c> | ||
<VirtualHost *:443> | <VirtualHost *:443> | ||
Line 742: | Line 823: | ||
</VirtualHost> | </VirtualHost> | ||
</IfModule> | </IfModule> | ||
</ | </syntaxhighlight> | ||
'''4.''' Create the SSL folder in /etc/apache2/ if it doesn't already exist: | '''4.''' Create the SSL folder in /etc/apache2/ if it doesn't already exist: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo mkdir /etc/apache2/ssl | $ sudo mkdir /etc/apache2/ssl | ||
</ | </syntaxhighlight> | ||
'''5.''' Run the following command to set up your local cert and follow the ensuing steps for generating it: | '''5.''' Run the following command to set up your local cert and follow the ensuing steps for generating it: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.pem | $ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.pem | ||
</ | </syntaxhighlight> | ||
When it asks you for the "Common name", you can put your local server's name. | When it asks you for the "Common name", you can put your local server's name. | ||
'''6.''' Restart Apache. | '''6.''' Restart Apache. | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo service apache2 restart | $ sudo service apache2 restart | ||
</ | </syntaxhighlight> | ||
If you have an error message that pertains to your SSL site, you'll need to fix it first before continuing. | If you have an error message that pertains to your SSL site, you'll need to fix it first before continuing. | ||
'''7.''' Test the Apache config: | '''7.''' Test the Apache config: | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo apache2ctl configtest | $ sudo apache2ctl configtest | ||
</ | </syntaxhighlight> | ||
'''8.''' Delete the old wwwroot as that still points to http://. If you left it, you wouldn't see all assetts. | '''8.''' Delete the old wwwroot as that still points to http://. If you left it, you wouldn't see all assetts. | ||
< | <syntaxhighlight lang="bash"> | ||
$ sudo -u postgres psql mahara- | $ sudo -u postgres psql mahara-main | ||
delete from config where field = 'wwwroot'; | delete from config where field = 'wwwroot'; | ||
Ctrl + d to exit | Ctrl + d to exit | ||
</ | </syntaxhighlight> | ||
'''9.''' Go to your Mahara URL and use '''https://'''. Since you created a self-signed cert, your connection will be untrusted. Proceed anyway. | '''9.''' Go to your Mahara URL and use '''https://'''. Since you created a self-signed cert, your connection will be untrusted. Proceed anyway. | ||
Line 779: | Line 860: | ||
'''10.''' Now you can use your developer site with web services as well. | '''10.''' Now you can use your developer site with web services as well. | ||
==Set up Behat== | |||
== Set up Behat == | |||
You can use the automated testing suite from Mahara 15.04 on. There is a [[Testing/Behat_Testing/Setup | separate installation page for Behat]]. | You can use the automated testing suite from Mahara 15.04 on. There is a [[Testing/Behat_Testing/Setup | separate installation page for Behat]]. | ||
== XDebug == | |||
=== VS Codium === | |||
Install the extension PHP Debug <syntaxhighlight> | |||
Name: PHP Debug | |||
Id: xdebug.php-debug | |||
Description: Debug support for PHP with Xdebug | |||
Version: 1.32.0 | |||
Publisher: Xdebug | |||
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug | |||
</syntaxhighlight>Use the Xdebug wizard to help you with installation https://xdebug.org/wizard | |||
To use with Behat, make sure in your <code>99-xdebug.ini</code> file<syntaxhighlight lang="ini"> | |||
# in /etc/php/8.1/mods-available | |||
zend_extension = xdebug | |||
xdebug.mode = debug | |||
# This will not work in Behat tests however, triggering it in VS Code will work | |||
xdebug.start_with_request = trigger | |||
# This will work with Behat tests as well as in VS Code - use this one for Behat | |||
# xdebug.start_with_request = yes | |||
</syntaxhighlight>Remember to restart your PHP server if applicable <code>sudo service php8.x-fpm restart</code> |
Latest revision as of 13:06, 30 November 2023
Overview | Finding your way around | Dev setup | Dev tools | Contributing | Testing |
Keep in touch | API Docs | Architecture | Release Instructions | Plugins |
🚧 Note: this wiki is in the process of migrating to our GitLab Wiki.
This page explains how to set up a copy of Mahara for development purposes.
The Docker version
Included in the main codebase is a docker version of Mahara with Behat capabilities. Before you try this, you will need to have Docker installed. See: https://docs.docker.com/engine/install/ubuntu/
The instructions for running the docker version are here:
https://git.mahara.org/mahara/mahara/-/blob/main/docker/README.md
Please feel free to update if there are missing instructions that would be helpful to others.
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 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 itsdataroot
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 have already installed, you may need one or more of these:
php-pgsql
php-gd
php-curl
php-intl
php-json
php-zip
- If you are using MySQL instead of Postgres
php7.4-mysql
orphp-mysql
The long version (for Windows)
If you want to install your developer environment on Windows, please check the Windows instructions.
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.
Note: Please have an apache2 installed on your server
sudo apt install apache2
The following instructions are for Ubuntu 22.10 and above, unless otherwise noted.
Install required packages:
PHP 7.4
sudo apt install \
make curl wget xvfb git gitk 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 php-mbstring \
nodejs php7.4-pgsql php7.4-xml php7.4-xmlrpc php7.4-mbstring php7.4-intl libssl-dev pdo_sqlite php7.4-zip
# Set 7.4 as apache2's version of php
sudo a2enmod php7.4
PHP 8.1
sudo apt install \
make curl wget xvfb git gitk postgresql php8.1-common php-cli libapache2-mod-php8.1 \
php8.1-curl php8.1-gd php-json php-ldap php-pgsql php-xmlrpc php-zip php-xml php-mbstring \
nodejs php8.1-pgsql php8.1-xml php8.1-xmlrpc php8.1-mbstring php8.1-intl libssl-dev pdo_sqlite php8.1-zip
# Set 8.1 as apache2's version of php
sudo a2enmod php8.1
If you encounter any errors with the installation, you may want to try installing in chunks. See the Troubleshooting section.
To switch between PHP versions
sudo a2dismod php7.4
sudo a2enmod php8.1
sudo update-alternatives --config php
sudo service apache2 restart
Node
Check which version of Node you are running with node -v
To install: sudo apt install nodejs
Get a copy of the codebase
Get a copy of the Mahara code from git. We'll put it under your home directory, in a new directory called code
: See also Getting Code from Git
cd ~
mkdir code
cd code
# if you have an account on git.mahara.org ...
git clone [email protected]:mahara/mahara.git
# else, use http...
git clone https://git.mahara.org/mahara/mahara.git
# if that doesn't work, try...
git clone https://github.com/MaharaProject/mahara.git
Fix permissions
Give the Apache web server access to your Mahara code directory:
# Give all users read access + executable (if required) to the mahara directory
sudo chmod a+rX ~/code/mahara
# To avoid a possible 403 error later, confirm that your code directory permissions are also drwxr-xr-x
ls -la ~/
# To fix, run:
sudo chmod a+rX ~/code
# Your home directory permissions should be drwx--x--x
ls -la /home # to check
# To fix, run:
sudo chmod a+X /home/[name of your home directory]
Create a Mahara database
Create a PostgreSQL database user
# Use maharapassword as the password
sudo -u postgres createuser -P -D -R -S maharauser
If Postgres is not available, check its status and if it says that it's inactive, start the service:
# Check status
service postgresql status
# Restart service
sudo service postgresql start
Create a database
sudo -u postgres createdb -Omaharauser mahara-main
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 = 'main';
// 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.
Set up dataroot
, host, and site
Create a dataroot
directory
This is where Mahara stores uploaded files):
sudo mkdir /var/lib/maharadata
sudo mkdir /var/lib/maharadata/main
sudo chown www-data:www-data /var/lib/maharadata/main
Set up local domain
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"
Increase your PHP post_max_size
These files will be under the version of php you are using, e.g. /etc/php/<PHP version>:
# for PHP 7.4
sudo sh -c "echo 'post_max_size = 37M' >> /etc/php/7.4/cli/php.ini"
sudo sh -c "echo 'upload_max_filesize = 32M' >> /etc/php/7.4/cli/php.ini"
sudo sh -c "echo 'post_max_size = 37M' >> /etc/php/7.4/apache2/php.ini"
sudo sh -c "echo 'upload_max_filesize = 32M' >> /etc/php/7.4/apache2/php.ini"
# for PHP 8.1
sudo sh -c "echo 'post_max_size = 37M' >> /etc/php/8.1/cli/php.ini"
sudo sh -c "echo 'upload_max_filesize = 32M' >> /etc/php/8.1/cli/php.ini"
sudo sh -c "echo 'post_max_size = 37M' >> /etc/php/8.1/apache2/php.ini"
sudo sh -c "echo 'upload_max_filesize = 32M' >> /etc/php/8.1/apache2/php.ini"
Note: The 'post_max_size' is slightly bigger, as a POST command also contains some wrapper information. That wrapper is just text strings and relates to how much the form submits. So usually, 1 MB should be enough, but to be on the safe side, 5 MB would be better, which then also works for larger uploads.
Create an Apache config file
You can do this by first copying the following contents into a file called mahara.conf
, saved in your home directory.
See also: Changing Hostnames
<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.
sudo cp ~/mahara.conf /etc/apache2/sites-available/mahara.conf
Enable the site in Apache
sudo a2ensite mahara
sudo apache2ctl configtest
sudo apache2ctl graceful
composer update && make initcomposerdev
Set up cron
:
# To get cron emails every minute:
sudo vim /etc/cron.d/mahara
* * * * * www-data /usr/bin/php /home/<your username>/code/mahara/htdocs/lib/cron.php
# Otherwise:
sudo vim /etc/cron.d/mahara
* * * * * www-data /usr/bin/php /home/<your username>/code/mahara/htdocs/lib/cron.php >/dev/null 2>&1
Set up npm
and gulp
for theming
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
# Mahara runs with at least version 14.x of node.
sudo npm cache clean -f
sudo npm install -g n
sudo nvm use stable
# Then update node-sass bindings:
sudo npm rebuild node-sass
Build the themes (CSS)
Run make css
in the Mahara code directory to compile the CSS for Mahara themes. This will run the necessary series of instructions written out in the Makefile (including npm install
for both the development and production JS libraries.
cd /home/<your username>/code/mahara
make css
# If you see a lot of errors, such as depreciation warnings for .css files:
# Delete your /home/<your username>/code/mahara/package-lock.json
# Then re-run "nvm install" and "make css", which should resolve the issues.
# If you run 'make css' and see the following "ERROR: Can't find the "nvm" executable ..." try the following:
# Steps (for me) to get nvm working
## First Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
## Then make the .nvm.sh executable
cd ~/.nvm && chmod 755 nvm.sh
## Then reload your .bashrc file
source ~/.bashrc
## The set the first nvm version manually to create a default
./nvm.sh && nvm install 12
Build the CSS in non-production mode
Sometimes it gets confusing where the SASS info comes from to compile the css files. To make things easier, you can edit the 'Makefile' and change the production mode to false.
production = false
Then run the make css
again - this will compile the theming files to create *.css
files in an easier to read format with comments about which sass file contributed to the chuck of CSS code, e.g.:
/* line 27, /home/robertl/code/mahara-devel/mahara/htdocs/theme/raw/sass/layout/_footer.scss */
.admin .footer .footer-inner {
padding: 10px; }
/* line 36, /home/robertl/code/mahara-devel/mahara/htdocs/theme/default/sass/layout/_footer.scss */
.admin .footer .footer-inner {
padding: 20px 10px;
background: none;
border: 0;
border-radius: 0; }
Go to the site in your browser
https://mahara/
You should see the Mahara installer page. If you do, congratulations! Your development environment is now set up.
Trouble-shooting
Checking what version of PHP is running on your site
The PHP version on the CLI can be different to what is running on the site, especially if you run php-fpm which allows having two PHP servers of different serving different PHP versions.
To check the PHP version your site is serving, create the file /htdocs/test.php
and populate it with following lines.
<?php
phpinfo();
// In your browser go to <your wwwroot>/test.php
Ubuntu 22.04 & PHP 8.x
By default Ubuntu 22.04 will have PHP 8.2 enabled
To run commands on a different PHP version (e.g. 8.x) run: sudo update-alternatives --set php /usr/bin/php8.x
Run composer update && make initcomposerdev
so the composer.lock file matches your PHP version.
Enabling apache2's version of PHP
When you do:
# for PHP 7.4
sudo a2enmod php7.4
# for PHP 8.1
sudo a2enmod php8.1
Using MySql8
If you are going to be using MySql 8 or later, you will need to do the following:
- To install MySql 8 on Ubuntu 16.04 see https://www.digitalocean.com/community/tutorials/how-to-install-the-latest-mysql-on-ubuntu-16-04
We need to add a line to our mysql conf file so that we can log in with older format passwords, so edit:
vi /etc/mysql/mysql.conf.d/mysqld.cnf
And make sure we have
[mysqld]
default_authentication_plugin=mysql_native_password
You will need to set the db user to use the native password
CREATE USER 'maharauser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'mahara';
MySQL in Docker
If you have Docker available you can spin it up a dedicated container for it.
Installing Node versions
Check which version of Node you are running with
node -v
If you are running one of the long term service (lts) versions, 8.x or 10.x, that should work with Mahara fine. If you are running a higher version, or Node is not installed, you will need to add a version to run with Mahara.
You can find various instructions on how to upgrade NodeJS on your distribution depending on your preference on package manager. (There are a couple of links at the bottom of this section.)
A straight-forward way to manage multiple versions of Node is to use NVM:
Once you have it installed run:
nvm install --lts
nvm use --lts
This will download the latest lts version of Node and set it to default. Then if you need to switch versions for other projects, you can do so with "nvm use <version>".
Links to alternative ways of installing Node:
ts-php versions - also add set alternatives here Note on changing versions: you can see which version apache is using by adding phpinfo() in your code.
Adding another branch
1. Create a new local branch for it in git (replace 1.10 / 110 with the version of Mahara for which you want to add a branch)
$ cd ~/code/mahara
$ git checkout -t origin/1.10_STABLE
2. Create the sitedata directory for the new branch:
$ sudo mkdir /var/lib/maharadata/110stable
$ sudo chown www-data:www-data /var/lib/maharadata/110stable
3. Create a database:
$ sudo -u postgres createdb -Omaharauser mahara-110stable
4. Change your ~/code/mahara/htdocs/config.php to point to the 1.10 branch:
$branch = '110stable';
5. Go to the site in your browser to run the Mahara installer:
http://mahara/
Switching back to the main branch
1. Change the config.php file:
$branch = 'main';
2. Switch to the right git branch:
$ cd ~/code/mahara/
$ git checkout main
Reset the database
1. Delete the old database:
$ sudo -u postgres dropdb mahara-main
2. Create a new one with the same name:
$ sudo -u postgres createdb -Omaharauser mahara-main
3. Go to the site in your browser to run the Mahara installer again:
http://mahara/
If you reset the database a lot, you might want to try out the "maharawipe.sh" utility at https://github.com/agwells/mahara-devtools
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: main):
$ cd ~/code/mahara
$ git checkout main
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, for example:
$ git fetch git://reviews.mahara.org/git/mahara refs/changes/30/230/1 && git checkout FETCH_HEAD
$ make css
5. After finishing the testing, go back to main:
$ git checkout main
$ make css
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.
1. Do a checkout of the code into a new directory:
$ cd ~
$ mkdir code
$ cd code
$ git clone [email protected]:mahara/mahara.git 15stable
2. Copy the database:
$ 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
If you've not given the user 'maharauser' full privileges yet (should only need to do this once)
$ 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.conf:
<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/
10. Resetting the admin password:
If you do not know the login info for the copied site's database or the new site uses a different 'passwordsaltmain' from the old one you can reset a users password via the CLI script "reset_password.php", for example if you need to reset the 'admin' user's password you can go:
sudo -u www-data php htdocs/admin/cli/reset_password.php -u=admin -p=changeme
This will reset the password and on next login you will be prompted to change the password again to something more robust.
Elasticsearch
If you want to test the Elasticsearch search plugin, you'll also need to set up and run an Elasticsearch server. See Developer Area/Setting up Elasticsearch.
ClamAV
If you want to test the ClamAV virus protection see Setting up ClamAV
Set up site for local https://
You will need to set up your Mahara developer site with an SSL certificate if you want to use the web services functionality as that is only available over https.
You should already have Apache 2 installed on your computer. Otherwise, Mahara wouldn't run. Install the openssl and ssl-cert packages:
$ sudo apt-get install openssl ssl-cert
1. Enable SSL in Apache 2:
$ cd /etc/apache2/mods-enabled/
$ ls
$ sudo a2enmod ssl
$ service apache2 restart
$ ls
You should see "ssl.conf" and "ssl.load"
2. You'll need to check that the port for SSL traffic is configured.
$ cd ..
$ cat ports.conf
If you see <IfModule ssl_module> Listen 443, you are good to go.
3. Enable SSL also in your Mahara Apache 2 config file.
$ 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:
$ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.pem
When it asks you for the "Common name", you can put your local server's name.
6. Restart Apache.
$ sudo service apache2 restart
If you have an error message that pertains to your SSL site, you'll need to fix it first before continuing.
7. Test the Apache config:
$ sudo apache2ctl configtest
8. Delete the old wwwroot as that still points to http://. If you left it, you wouldn't see all assetts.
$ sudo -u postgres psql mahara-main
delete from config where field = 'wwwroot';
Ctrl + d to exit
9. Go to your Mahara URL and use https://. Since you created a self-signed cert, your connection will be untrusted. Proceed anyway.
10. Now you can use your developer site with web services as well.
Set up Behat
You can use the automated testing suite from Mahara 15.04 on. There is a separate installation page for Behat.
XDebug
VS Codium
Install the extension PHP Debug
Name: PHP Debug
Id: xdebug.php-debug
Description: Debug support for PHP with Xdebug
Version: 1.32.0
Publisher: Xdebug
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
Use the Xdebug wizard to help you with installation https://xdebug.org/wizard
To use with Behat, make sure in your 99-xdebug.ini
file
# in /etc/php/8.1/mods-available
zend_extension = xdebug
xdebug.mode = debug
# This will not work in Behat tests however, triggering it in VS Code will work
xdebug.start_with_request = trigger
# This will work with Behat tests as well as in VS Code - use this one for Behat
# xdebug.start_with_request = yes
Remember to restart your PHP server if applicable sudo service php8.x-fpm restart