CIMA runs on the LAMP stack in production:

• Ubuntu 16.04 - 20.04
• Apache 2.4
• MySQL 8
• PHP 7.0 - 7.4

You'll need PHP and MySQL. If you wish to try a different OS and webserver, you're welcome to. Document your experience so we can include it here.

To install a standard stack in one line, use

$ sudo apt install apache2 php libapache2-mod-php mysql-server

If you want to experiment with the stack, use the following sections for individual components.

Digital Ocean has a great guide to installing the LAMP stack on Ubuntu 20.04. Look there for anything not covered by what's below.

Apache is not installed by default in Ubuntu 20.04. Its repository package is apache2; install it with

$ sudo apt install apache2

Get used to including the version number in all commands, since Ubuntu uses apache2, not apache (i.e., $ sudo systemctl reload apache2). Be aware that Debian Linux and its derivatives, including Ubuntu, have created their own file structure and configuration system for Apache, so if you have experience with it on other platforms, your knowledge may not carry over.

PHP is not installed by default in Ubuntu 20.04. The repository package php is a dependency package that installs whatever the latest version available for that Ubuntu release is, which is almost certainly what you want. If you intend to use Apache as your webserver, you'll also want the Apache PHP mod, mod_php, which is installed as the package libapache2-mod-php. So, in most cases, run

$ sudo apt install php libapache2-mod-php

Installing libapache2-mod-php should enable it automatically, but you can check by looking for it in /etc/apache2/mods-enabled/ (Debian/Ubuntu location). If it's not there, enable it with $ sudo a2enmod php7.x (replacing x with whatever you have; hit TAB after typing php to auto-complete. Again, this is the Debian/Ubuntu command).

MySQL has separate packages for its client and server programs, and neither are installed by default in Ubuntu 20.04. CIMA requires only the server. That Ubuntu repository package is mysql-server; install it with

$ sudo apt install mysql-server

Once MySQL is installed, follow the MySQL Setup page of this wiki to configure it for use with CIMA.

You'll access the CIMA source code through the QuarkNet GitHub repository, so you'll need Git installed. Git is installed by default on Ubuntu 20.04; if for some reason it isn't on your copy, its package is git and you can install it with

$ sudo apt install git

This guide will help you set up a localhost development environment for CIMA. This procedure has not been tested start-to-finish and is largely educated supposition. Corrections and feedback are welcomed.

Since CIMA is a CGI-based PHP webapp, its source code does not need to be placed within the traditional Apache DocumentRoot of /var/www/. As long as the webserver is properly configured, however, there's no harm in doing so. In production, CIMA files are placed within the home directory of the quarkcat user, a utility user originally created to manage the I2U2 e-Labs. Changing this is an active but complex TODO item, since CIMA has nothing to do with the e-Labs. In this guide, we will call this directory $CIMA_HOME and use $CIMA_HOME=/var/www/php/cima/ when a concrete example is needed, but this is ultimately the developer's choice.

Clone CIMA to $CIMA_HOME on your machine using the method of your choice:

• HTTPS: /var/www/php/cima$ git clone https://github.com/QuarkNet-HEP/cima-wzh.git

• SSH: /var/www/php/cima$ git clone [email protected]:QuarkNet-HEP/cima-wzh.git

(You'll need to have established an SSH key with GitHub prior to using this.)

• GitHub CLI: gh repo clone QuarkNet-HEP/cima-wzh

(I've never used this. You're on your own.)

Create a file /etc/apache2/sites-available/cima.conf. This is the Debian/Ubuntu configuration location; you'll have to adjust as necessary if you're using a different OS. You can use anything besides cima in cima.conf as long as you adjust everything following accordingly.

Add this configuration:

<VirtualHost *:80>
    ServerName localhost

    DirectoryIndex index.php index.html index.htm index.shtml

    # CIMA
    DocumentRoot "$CIMA_HOME"
    Alias        /cms/cima    "$CIMA_HOME"
    AliasMatch   ^/elab/(.*)/cima/(.*)$      $CIMA_HOME/$2

    <Directory "$CIMA_HOME">
        Options -Indexes +FollowSymlinks +MultiViews
        AllowOverride none
	Require local
    </Directory>

<VirtualHost>

substituting for the four instances of $CIMA_HOME as appropriate. Notes on this configuration:

• CIMA is currently served in production under the I2U2 e-Labs URL tree, and its internal links reflect this. Thus, you'll need to keep the Alias and AliasMatch directives as shown until that situation is changed.

• The Indexes option allows users to access directory listings. We disallow this with -Indexes.

• The FollowSymlinks option probably does nothing, since there are no symlinks in the code. I've never tested removing it.

• The MultiViews option probably does nothing, too, since I'm pretty sure CIMA doesn't implement options for content negotiation. Language negotiation might be something to implement in the future, though, so I've left it in so far.

Enable the new config and reload Apache to pick up the new configuration:

$ sudo a2ensite cima.conf
$ sudo systemctl reload apache2.service

Again, these are Debian/Ubuntu commands (the latter is Debian/Ubuntu using systemd in particular). Adjust as necessary for your system.

TODO: Do mod_php and php.ini require configuration for CIMA?

This is enough work that it has its own wiki page: MySQL Setup.