Setting up CoNtRol

Contents

  1. Instructions
    1. System requirements
    2. Installation
      1. Enabling batch processing
      2. Mac OS X notes
  2. Downloads
    1. Prebuilt packages
      1. Linux
      2. Mac OS X
    2. Source code
    3. Building CoNtRol manually

Instructions

System requirements

To run CoNtRol on your own server or desktop, you will need a PHP-enabled web server such as Apache, and the packages glpk-utils, libginac2, maxima and octave installed on Debian/Ubuntu, or their equivalent for other OSes. You will also need Sage and (optionally) SCIP. For batch processing to work you will need a working database and mail server.

To build CoNtRol instead of using a pre-built copy, you will also need the packages build-essential, libginac-dev and libglpk-dev or equivalent.

CoNtRol has only been tested on Ubuntu, Debian and Mac OS X 10.9.3, but we believe it should run straightforwardly on other Linux/BSD variants, including other OS X versions and Windows (via Cygwin). We welcome feedback and bug reports about installing and running CoNtRol on these systems.

Installation

Once you have a local copy of CoNtRol, either from a pre-built package or by following the build instructions below, simply drop it into the root folder of your website (see step 8 in the Mac OS X instructions below, or /var/www/html in most Linux distros). CoNtRol has only been tested with Apache, but should work with any correctly configured web server that supports PHP, such as lighttpd or NGINX. For a local install without batch processing, the default config settings should work without modification. The default URL is http://127.0.0.1/control/.

Enabling batch processing

For test/small installations, e.g. on a local desktop machine rather than a dedicated web server, if you want to enable batch processing we recommend using SQLite for the database and msmtp to send mail. These will need to be set up correctly, along with a cron job to periodically check for new batches. To create a cron job, run sudo nano /etc/cron.hourly/control, paste in the following lines, save and make it executable with sudo chmod +x /etc/cron.hourly/control):

#!/bin/sh
cd /var/www/html/control/cron
sudo -u www-data /var/www/html/control/cron/cron.php

For a shared server install with batch processing, we recommend using a more powerful database such as MariaDB (or MySQL). There is a database schema for MariaDB/MySQL in the sql directory. Batch processing in CoNtRol will work with any database supported by PDO, including Microsoft SQL Server, Postgres, IBM DB2 and Oracle.

Setting up an email server is an advanced topic and beyond the scope of these instructions. If you would like assistance in configuring email sending, please contact pete dot donnell at port dot ac dot uk and we will do our best to help.

Mac OS X notes

These notes will help you get the prerequisites set up to run CoNtRol on Mac OS X. You will need to be comfortable using the Terminal to enter commands. Note: these instructions have only been tested under Mac OS X Mavericks 10.9.3 using Homebrew. The instructions should be straightforward to adapt to different versions of OS X, and to MacPorts or Fink, but these have not been tested.

  1. Enable PHP by editing your Apache config with the command sudo nano /private/etc/apache2/httpd.conf.
    1. Uncomment the line LoadModule php5_module libexec/apache2/libphp5.so.
    2. In the <IfModule dir_module> section, find the line beginning with DirectoryIndex and add index.php on the end.
    3. (Optional but recommended) In the <Directory "/Library/WebServer/Documents"> section, change AllowOverride None to AllowOverride Limit.
  2. Set the $PATH variable to /usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/opt/local/bin for the _www user. Use the command sudo nano /System/Library/LaunchDaemons/org.apache.httpd.plist to edit the Apache config and follow these instructions.
  3. Restart Apache with sudo apachectl restart.
  4. Install Homebrew with the command ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)".
  5. Install coreutils, ginac, glpk, maxima and octave with the command brew install <packagename>.
  6. Create a symlink for timeout with the command sudo ln -s /usr/local/bin/gtimeout /usr/local/bin/timeout.
  7. Get the files that make up CoNtRol, either by downloading and unzipping the prebuilt version below, or by compiling it using the build.sh script at the bottom of this page.
  8. Copy the control directory to a suitable location (/Library/WebServer/Documents/control is a sensible default).
  9. Edit the CoNtRol configuration:
    1. cd includes/ && cp config.php.dist config.php
    2. Edit the configuration with nano config.php and follow the notes it contains.
    3. (Optional, for batch processing) Configure the database. Setting up MySQL on OS X is beyond the scope of this document, but for a local install SQLite should suffice:
      1. Change the sql directory to belong to the web server user with sudo chown -R _www sql.
      2. Copy the database into place with cd sql && sudo cp -a control.dist.sqlite control.sqlite.
    4. (Optional, for batch processing) Enable mail sending (beyond the scope of this document).
  10. You should now be able to run CoNtRol. Open http://127.0.0.1/control/ in your browser.
  11. Troubleshooting: if the CoNtRol page loads successfully but the tests return no output, try turning on detailed output in the Options.

Downloads

Prebuilt packages

Linux amd64 (1.5.3)

Linux x86 (1.1.2)

Linux PowerPC (1.0.5)

Mac OS X (1.1.2)

Windows Cygwin builds to come.

Source code

Browse source code.

Browse PHPdoc documentation.

Building CoNtRol manually

Alternatively, simply download our build script and run it with the command ./build.sh. The script generates a zip archive and tar.gz archive of the functioning code, which you can then just extract to your web server root directory.