Skip to content

Manual Install Process

Jump to bottom
Saron Solomon Gebre edited this page Oct 8, 2025 · 12 revisions

This document outlines the manual install process

Step 1: Set up the server

Server Requirements

  • php7
  • MySQL, 5.7 is recommended
  • Unix environment (not tested on windows)
  • git
  • apache
  • composer (php package manager)
  • node v15.14.0 (v7 and greater may work as well) and npm

The following php extensions are required

  • cli
  • intl
  • tidy
  • mbstring

Note that the linux timeout command is also required for headless testing. This should be available on most servers, but is not available on Mac. To install on Mac you can run brew install coreutils and then ln -s /usr/local/bin/gtimeout /usr/local/bin/timeout to make it available to php.

Step 2: Download SiteMaster

Clone the SiteMaster repo found at https://github.com/UNLSiteMaster/site_master.git into a directory that is accessible by apache, probably the document root for the domain that you want SiteMaster to be located at

Step 3: Create a MySQL database

Create a database named sitemaster. Default character set should be utf8 and collation should be utf8_unicode_ci. Some tables that need case sensitivity will be created as utf8_bin.

Step 4: Copy and edit configuration files

From the root of the SiteMaster project, run the following commands from command line:

  • run cp sample.htaccess .htaccess
  • run cp config.sample.php config.inc.php

Now, you may want to edit both .htaccess and config.inc.php for your environment. If your install is located in a subdirectory like yourdomain.com/sitemaster/ you will need to change the RewriteBase in .htaccess to include the path.

Edit config.inc.php, be sure to include details about your base URL (if different), database settings, and test database settings. See the groups documentation for details on how to configure groups of similar websites.

Step 5: run the install process

  • run git submodule init && git submodule update
  • run composer install
  • run npm install
  • run php scripts/install.php

Step 6: install packages for the headless browser

This project uses nightmarejs for a headless browser. The use of a headless browser is key for reliable and consistent results, as this is the only way to compile the rendered DOM and get the same data that an actual user would see in a browser. This will require that several packages be installed on the server in order to work.

ubuntu

(unknown, see centos as a reference)

centos

Required system libraries and commands to install on centos

  • sudo yum install xorg-x11-server-Xvfb
  • sudo yum install gtk2
  • sudo yum install libXtst
  • sudo yum install libXScrnSaver
  • sudo yum install GConf2
  • sudo yum install alsa-lib
  • sudo yum install xorg-x11-fonts
  • I didn’t see a specific error which indicated that this package needed to be installed. I ended up diving into this issue to find the fix.

Debugging the headless browser:

See https://github.com/mfairchild365/the-axe-nightmare for a demo and debugging tips. The actual script to run the headless tests in SiteMaster is generated on the fly for each scan, so it can be difficult to debug. This script is located in the tmp/ directory and includes the name of the worker. For example, tmp/sitemaster_headless_default_compiled.js. If the headless browser fails to run, you can manually run that script with the debugging instructions found in the-axe-nightmare project.

Step 6: Make sure it works!

Go to the URL for the install and make sure it is functioning.

At this point, the SiteMaster should be functional, but authentication needs to be configured. By default, SiteMaster uses Google for its authentication, but you can configure it to use CAS or any other method.

Step 7: Configure authentication

To configure the google authentication, follow the guide found here: https://github.com/UNLSiteMaster/site_master/tree/master/plugins/auth_google

Everything after this step is optional.

Step 8: Set up an system admin (optional)

There are two system roles for users.

  • USER - can only manage the sites that they are members of
  • ADMIN - can manage any site and skip verification workflows

To make some an admin, follow these steps:

These steps assume that you are using a terminal and that the vagrant box is already running.

Run php scripts/edit_user.php list to list all users so that you can correctly identify the uid and provider that you want to edit. Run php scripts/edit_user.php (UID) (PROVIDER) role ADMIN to change a users role to admin. example:

php scripts/edit_user.php 9999999999999999 Google role ADMIN

Step 9: Run tests

Ensure that everything is working by running tests.

There are two levels of tests. The sitemaster project has its own test suite located in the tests directory, and all plugins should have their own tests located in the plugin's tests directory.

To run all tests:

php vendor/bin/phpunit

Step 10: The daemon

SiteMaster requires a background script to process the scan queue. This script can be ran with the following command: php scripts/daemon.php. For more details about this, See our page about the daemon.

Clone this wiki locally