Developing Webwork on MacOS

This document goes through setting up an apache web server with all the needed pieces to run on MacOS. This was last tested on macOS Mojave (10.14).

Preliminary Packages

Homebrew

Even though macOS comes with apache, I have had more success with a separate installation from homebrew. Before installing apache, start with homebrew, a manager that is able to install a number of open source programs/packages for MacOS. From a terminal:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Apache

Although you can use the built-in version of Apache that ships with MacOS, I find it is more up to date and other things compile better with the home-brew version:

brew install apache2

This will install a number of dependencies as well as apache2 (version 2.4 currently). To test if apache installed correctly, go to a webpage and enter localhost:8080, because the home-brew version puts the default port at 8080. This will need to be changed later as we will show.

perlbrew

perlbrew is a very handy software package to manage different versions of perl. In addition, it makes working on MACOS and other operating systems nice as upgrades are made. To install perlbrew

curl -L https://install.perlbrew.pl | bash

and if curl is not installed use brew to install it with brew install curl.

Now, you need to install a particular version of perlbrew for example if you are installed 5.26.3, type:

perlbrew install -Duseithreads perl-5.26.3
perlbrew switch perl-5.26.3

and note that if some tests fail, but it still probably will work you may need to force it with

perlbrew --force install -Duseithreads perl-5.16.3

CPAN Minus

To install perl packages, the command line tool cpanm is quite nice and I use it instead of cpan and if you have installed perlbrew as above, perlbrew comes with a handy installer that work across versions of perl:

perlbrew install-cpanm

Installing mod_perl

The Mod_Perl apache package is used to run perl code through webpages and apache. The following will install it via cpanm:

cpanm --sudo --reinstall --verbose --configure-args="MP_CCOPTS=-std=gnu89" mod_perl2

And it will download the mod_perl code and take a while to compile and test it. Grab another cup of coffee. If there is any fail, you can try the build again.

Check that the mod_perl.so file was created by

ls ~/.cpanm/latest-build/mod_perl-2.0.10/src/modules/perl/mod_perl.so

and if it shows the file then it was successfully created. If not you may need to try again.

cd ~/.cpanm/latest-build/mod_perl-2.0.10
perl Makefile.PL MP_CCOPTS=-std=gnu89
make && make install

or more-recently (mojave) make sure that openssl is installed via brew and

perl Makefile.PL --libs="-L/usr/local/opt/openssl/lib/ -lmysqlclient -lssl -lcrypto" MP_CCOPTS=-std=gnu89
make && make install

To copy the mod_perl.so file to the correct place:

cp ~/.cpanm/latest-build/mod_perl-2.0.10/src/modules/perl/mod_perl.so /usr/local/lib/httpd/modules/

Installing the DBD::mysql perl package

There is often problems arising from installing the mysql perl package. First, if

cpanm DBD::mysql

fails, then cd to the working directory--it will say where it is. I have found that:

perl Makefile.PL --cflags="-I/usr/local/Cellar/mariadb/10.4.6/include/mysql -I/usr/local/Cellar/mariadb/10.4.6/include -I/usr/local/opt/openssl/include/openssl" --libs="-L/usr/local/opt/openssl/lib -L/usr/local/lib -lmysqlclient"

then make && make install worked. Note: change the location of the mysql (mariadb) files above to the current version.

install Apache2::Status module

Type:

sudo cpanm Apache2::Status

to install a status module that will help in troubleshooting later.

Initial Configuration and Checking that Mod Perl installed correctly.

Open /usr/local/etc/httpd/httpd.conf in your favorite text editor and do three things:

1. Find the port configuration (about line 50) and change Listen 8080 to Listen 80 to switch the port to the standard port.
2. In the list of modules add the line: LoadModule perl_module /usr/local/lib/httpd/modules/mod_perl.so
3. Add the following at the bottom of the file:

<Location /perl-status>
      # disallow public access
      Order Deny,Allow
      Deny from all
      Allow from localhost

      SetHandler perl-script
      PerlResponseHandler Apache2::Status
  </Location>

and then restart the apache server with sudo apachectl restart. You may see an error similar to

httpd: Could not reliably determine the server's fully qualified domain name, using XXXXX.local. Set the 'ServerName' directive globally to suppress this message
httpd not running, trying to start

but that doesn't matter for a development server. Other errors, try to make sure the perl module is compiled and in the right location.

You can test it by typing http://localhost in a browser window. You should see an "It Works!" message.

Also, type: http://localhost/perl-status to see that the mod_perl module is installed and loaded correctly.

Installing libapreq.

The libapreq apache module helps with the handling of http requests and cookies. To install this.

1. Download source from apache website.
2. Move to an empty directory . I like to use /usr/local/src, which may not exist.
3. Untar (tar xvf libapreq-2.XX.tar) and cd into that directory.
4. perl Makefile.PL --with-apache2-apxs=/usr/local/bin/apxs
5. make
6. make test You may get errors on this and may be free to ignore.
7. sudo make install
8. Add the following line to the bottom of /usr/local/etc/httpd/httpd.conf

LoadModule apreq_module    /usr/local/lib/httpd/modules/mod_apreq2.so

Getting the webwork source

First create the directory to store the webwork source and set permissions:

sudo mkdir /opt/webwork
cd /opt/
sudo chown XXX webwork && sudo chgrp _www webwork

where XXX is your username. Type whoami to determine this.

The webwork code is on github at https://github.com/openwebwork/webwork2 and you should sign up for an account and fork the code by clicking the Fork button at the top right of the webpage. You should fork this into your own account.

You can clone the code by copying the URL by clicking the Download or Clone button (green button) and use your favorite Git management software. I use either SourceTree or the built-in via the Atom Editor.

Note: you should also fork and clone the pg code and Open Problem Library.

Creating the courses directory

mkdir /opt/webwork/courses
cd /opt/webwork/webwork2/courses.dist
cp *.lst /opt/webwork/courses/
rsync -a modelCourse /opt/webwork/courses/

Webwork libraries

mkdir /opt/webwork/libraries
cd /opt/webwork/libraries/
git clone https://github.com/openwebwork/webwork-open-problem-library.git

Installing and Starting MySQL

brew install mysql

and to start it:

mysql.server start

To test that it installed, type mysql -uroot and you should see:

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 9
Server version: 8.0.11 Homebrew

or something similar. To set up WeBWorK database:

mysql> CREATE DATABASE webwork;
mysql> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'XXXXXX';
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';
mysql> exit
Bye
$ 

where XXXX is your database password. You will need this later.

Configuring WeBWorK

Installing Modules

Type

check_modules apache2

and install any (using cpanm) that are not installed.

Create local versions of each of the configuration files:

cd /opt/webwork/webwork2/conf
cp site.conf.dist site.conf
cp webwork.apache2.4-config.dist webwork.apache2.4-config
cp localOverrides.conf.dist localOverrides.conf