Installation and Administration Guide

This document was released by Squoring Technologies.

It is part of the user documentation of the Squore software product edited and distributed by Squoring Technologies.

This document is the Installation Guide for the Squore software product.

While we recommend that you read it in its entirety, we divided it up into chapters for an easier introduction to Squore:

If you want to install Squore Command Line Interface, refer to the Command Line Interface manual.

If the information provided in this manual is erroneous or inaccurate, or if you encounter problems during your installation, contact Squoring Technologies Product Support: http://support.squoring.com/

You will need a valid Squore customer account to submit a support request. You can create an account on the support website if you do not have one already.

For any communication:

Approval of this version of the document and any further updates are the responsibility of Squoring Technologies.

The version of this manual included in your Squore installation may have been updated. If you would like to check for updated user guides, consult the Squoring Technologies documentation site to consult or download the latest Squore manuals at http://support.squoring.com/documentation/17.0.10. Manuals are constantly updated and published as soon as they are available.

Squore is based on a traditional 3-tier architecture consisting of:

The Squore Architecture

As shown in the schema above, Squore Server can provide analysis results to clients without having access to any source code, in scenarios where the analysis is carried out on a client machine with access to the SCM repository, as is the case in most Continuous Integration environments.

If you are planning to access source code hosted in a Subversion, Git, ClearCase, CVS or Synergy repository, a command line client for this repository must be available on the machine where the Squore analysis carried out. For complete information about all installation pre-requisites, consult the section called “Installation Prerequisites”.

Squore allows analysing source code in the following programming languages: ABAP, Ada, C, COBOL, C++, C#, Fortran 77, Fortran 90, Java, JavaScript, Lustre, Mind-C, Objective-C, PHP, PL/SQL, Python, T-SQL, Visual Basic .NET, XAML.

The Squore database is a PostgreSQL or Oracle database used for storing:

Along with the database, a set of data files is maintained on disk to compute information about project history and stability. A backup of a Squore installation must always include the database and the file system. For more information about backing up your installation, refer to the section called “Backing-Up the Squore Data”.

Note: No source code is stored in the database or the file system.

The Squore application server is based on the WildFly framework. Its main functionalities are:

Squore end-users access the server services through a Web interface that enables them to:

Refer to the section called “Browser Compatibility” to make sure that your the Squore Wib Interface is compatible with your browser

For more details on performance-related requirements when using Squore, please refer to Chapter 7, Sizing Squore Server and Database.

In order to provide compatibility with Continuous Integration systems or run analyses on machines other than Squore Server, Squoring Technologies also delivers Squore CLI (Command Line Interface): a set of APIs used to remotely create and manage software projects.

Squore CLI is a Squore package that allows a Squore client to locally analyse project source code files visible to the client machine and send the results to a remote Squore server.

Squore CLI comes as a separate installable package that can be downloaded from Squoring Technologies's support site: http://support.squoring.com/download_area.php.

For more information about installing Squore CLI, refer to the Command Line Interface manual.

Squore Server requires a valid licence file in order to run. The licence file information is served by the Squore Licence Server, which reads a licence file squore-license.p7s located in <SQUORE_HOME>/server/standalone/configuration.

The licence file is delivered by Squoring Technologies and can be copied on the machine hosting Squore Licence Server at installation time or post-installation. In all cases, Squore Server must be restarted to take into account new licence information.

If you run multiple instances of Squore Server, each one can have its own Squore Licence Server and licence file, or you can point them to a common Squore Licence Server.

The licence file restricts Squore usage according to the following parameters:

This section describes the possible scenarios for installing Squore on windows.

If you use all the default settings, the installer will deploy the following components in the specified locations:

The installer provides options to:

Note

When an error occurs during the installation, the installer wizard remains open and display the log file of the installation, as shown on the screenshot below. When this happens, review the contents of the installer window, and if necessary, copy and send the contents to support@squoring.com.

The Installation Aborted screen

In order to start installing Squore, log on with an account that has administrator privileges and launch the Squore installer (squore-17.0.10-windows-x86_64.exe). Each of the wizard screens is documented below in the order that you will see them.

Squore is now ready for use and can be accessed via http://localhost:8180/SQuORE_Server . Refer to the next section if you need more information about how to start and stop Squore and, if applicable, change the default configuration.

Before installing Squore on a Linux platform, verify that all prerequisites are met, as described in the section called “Installation Prerequisites”

If you use all the default settings, the installer will deploy the following components in the specified locations:

Ensure that the user that installs and runs Squore has read and write access to these locations.

Follow these instructions to install Squore Server:

The Squore installation package can be used to upgrade an existing Squore installation from Squore 2013-B-SP3.

When an installation is upgraded, the following happens:

The Squoring program group created during the installation process contains all commands to start Squore on Windows.

Squore is now started. Please refer to the Squore Getting Started Guide for more details on how to use Squore.

During the installation of Squore Server on Windows, the installer provides the option to register a service to control Squore's startup and shutdown. This section covers the functionality of the prunmgr utility that allows you to further configure some aspects of the Squore Windows service. Note that when you install the Windows service, you should no longer use the start and stop scripts described in the section called “Starting Squore on Windows”

<SQUORE_HOME>\bin\prunmgr.exe //ES/squore

Squore is now started. Please refer to the Squore Getting Started Guide for more details on how to use Squore.

During the installation process, the Squore Installation Wizard creates several folders and files in the Squore installation directory <SQUORE_HOME> :

<SQUORE_HOME>/addons contains the Data Providers and Repository Connectors available in Squore

<SQUORE_HOME>/bin contains the main commands available to administer Squore. Most of these commands are also available from the Start menu in the Squoring/Squore program group on Windows.

<SQUORE_HOME>/client contains the libraries used by Squore CLI.

<SQUORE_HOME>/configuration contains folders and files that provide the default analysis and decision models, as well as the default dashboards for these models. For more details on how to understand and use these configuration files, refer to the Squore Configuration Guide.

<SQUORE_HOME>/database contains PostgreSQL tools to administer the database.

<SQUORE_HOME>/docs contains licences for third party libraries included in Squore.

<SQUORE_HOME>/lib contains libraries used by Squore Server for installation and maintenance tasks.

<SQUORE_HOME>/samples contains some sample source code in various programming languages that can be used as examples when getting to know Squore. This folder can safely be deleted if you do not need it.

<SQUORE_HOME>/server contains the Squore application server. See the section called “The Squore Application Server” for more information.

<SQUORE_HOME>/share contains some custom perl modules.

<SQUORE_HOME>/tools contains the deployed instances of perl, tclsh and PostgreSQL on Windows.

<SQUORE_HOME>/config.xml is used to specify the location of some configuration folders. See the section called “Understanding config.xml ” for more information.

Note: This section deals with editing the configuration of the installed instance of Squore. For more information about how to edit analysis models and wizards, refer to the Squore Configuration Guide.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<squore type="server">
	<paths>
		<path name="perl.dir" path="C:\Squoring\Squore\tools\perl\perl"/>
		<path name="tclsh.dir" path="C:\Squoring\Squore\tools\tclsh"/>
	</paths>
	<database>
		<postgresql directory="C:\Squoring\Squore\tools\pgsql"/>
		<cluster directory="C:\Squoring\Squore\cluster"/>
		<backup directory="C:\Squoring\Squore\backup"/>
		<security>
			<user-name>postgres</user-name>
		</security>
	</database>
	<phantomjs>
		<socket-binding port="3003"/>
	</phantomjs>
	<configuration>
		<path directory="C:\Squoring\Squore\configuration"/>
	</configuration>
	<addons>
		<path directory="C:\Squoring\Squore\addons"/>
	</addons>
	<tmp directory="C:\Users\username\AppData\Local\Temp\Squore"/>
	<projects directory="C:\Squoring\Squore\projects"/>
	<sources directory="C:\Users\username\AppData\Local\Temp\Squore\sources"/>
</squore>

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<squore type="server">
	<paths>
		(...)
	</paths>
	<database>
		(...)
	</database>
	<configuration>
		<path directory="C:\MyModels\configuration"/>
		<path directory="C:\Squoring\Squore\configuration"/>
	</configuration>
	<addons>
		<path directory="C:\MyModels\addons"/>
		<path directory="C:\Squoring\Squore\addons"/>
	</addons>
	<tmp directory="C:\Users\username\AppData\Local\Temp\Squore"/>
	<projects directory="C:\Squoring\Squore\projects"/>
	<sources directory="C:\Users\username\AppData\Local\Temp\Squore\sources"/>
</squore>

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<squore type="server">
	<paths>
        (...)
	</paths>
	<database>
        (...)
	</database>
	<configuration>
        (...)
	</configuration>
	<addons>
        (...)
	</addons>
	<client>
		<!-- java system properties are supported under the client node only -->
		<tmp directory="${java.io.tmpdir}/squore-${user.name}"/>
		<projects directory="${user.home}/.squore/projects"/>
		<sources directory="${java.io.tmpdir}/sources"/>
	</client>
	<tmp directory="..."/>
	<projects directory="..."/>
	<sources directory="..."/>
</squore>

Your installation of Squore includes some scripts designed to help save and restore snapshots of your analysis data. These scripts will allow you to:

The scripts are located in the <SQUORE_HOME>/bin folder of the Squore installation directory.

The Windows and Linux backup scripts accept a parameter that is used as the path to store the backup file. This makes it possible to use a scheduled task on Windows or a cron job on Linux to automate your backups. If you do not specify this parameter, the default backup folder will be used and each new backup will replace the previous one.

In order to handle cases where the URL configured in Administration > System is not accessible to PhantomJS, you can configure a different URL for the communication between Squore and PhantomJS. This is useful when you need to bypass a proxy on your network, or when the Squore Server URL just cannot be resolved from the machin it runs on itself. In those cases, you can force PhantomJS to make requests to Squore Server by adding the squore-url attribute to your <SQUORE_HOME>/config.xml, as shown below:

<phantomjs>
	<socket-binding port="3003" squore-url="http://127.0.0.1:8180/SQuORE_Server/" />
</phantomjs>

When using Microsoft Edge, extra configuration is needed in order to use the Save as ... menu items in the chart viewer. In this specific case, PhantomJS must be reachable on your network so that the end user's browser calls it directly to generate a downloadable chart on the fly. The PhantomJS URL needs to be specified in the distant-url attribute:

<phantomjs>
	<socket-binding port="3003" distant-url="http://servername:3003" />
</phantomjs>

Squore users can only have access to a project when they are added to the project's team by the project manager or an administrator. Until this happens, users are unaware of the projects that others have created. In situations where you wish users to be able to see the list of projects that exist on the server, you can configure Squore Server to provide users with a list of projects they do not currently have access to, so that they contact the project owner and ask to be added to the project's team.

As an administrator, your role is to define which projects should appear on this public list. The list includes all project whose group matches the value set up in the administration settings. The procedure below shows how you can automatically list all projects that were created within the public group to the public list.

The Project Owners List options required to list projects from the public group

After saving your changes, the Projects page will display a new button labelled Ask access to Project Owners, as shown below:

The Projects page with the Ask access to Project Owners button

When clicking the button, you will see the list of projects in the specified groups, together with their owner. Users can click on a user's e-mail address to ask the project owner if they can add them to the project team.

The Projects page with the Ask access to Project Owners button

Squore versions use the following naming convention: major.minor.patch - buildId - scmInfo. Major and minor releases usually introduce new functionality, while patch releases normally only contain bugfixes.

There are two ways to find out which version of Squore you are running:

You can change Squore Server port number after installation. The procedure involves modifying some configuration files in a text editor and restarting the server.

You can change the port used by the Squore Database by editing PostgreSQL's configuration file and modifying Squore Server's <SQUORE_HOME>/server/standalone/configuration/standalone.xml to point to the new port. The procedure involves modifying some configuration files in a text editor and restarting the server.

The port used by PhantomJS can be changed by editing <SQUORE_HOME>/config.xml to change the port value in the following line:

<phantomjs>
	<socket-binding port="3003"/>
</phantomjs>

The maximum amount of memory used by Squore Server's Java process at runtime is defined at installation time. If you have not specified any value, the maximum amount of memory used will be 25% of the RAM available on the machine. It is recommended to keep the memory allocated to Squore under 25% of the total physical RAM so that other Squore modules (especially the database) or external processes (the OS and some Data Providers like Checkstyle or FindBugs) still have enough resources available.

This setting can be changed by following this procedure:

The path to the Java installation on your server can be updated by following the procedure below:

You can change the main timeout value for tasks on a Squore Server installation. . The default value is six hours and is generally fine: if an analysis runs for six hours, it is assumed that something went wrong or will go wrong for reasons regarding memory consumption.

If you decide that the timeout does not suit your workflow, you can change the default timeout value from the Administration pages:

You can change the size of the project queue on a Squore Server installation. The default value is 8, which means that 8 projects can be analysed in parallel.

If your hardware can handle a higher number of concurrent analyses, you can increase the queue size by editing the file <SQUORE_HOME>/Server/server/default/deploy/squore-server.ear/squore-server.jar/META-INF/ejb-jar.xml, and set the maxSession key to the desired size. This involves repackaging and redeploying the application, as explained below:

Squore's web interface allows users to choose between several UI themes: chocolate (brown), classico (green) , neroverdi (light green), rossoneri (red). When a user selects a theme, their preference is saved and this theme is applied each time they log into Squore. As an administrator, you can manage theme functionality in two ways:

You can access these options from Administration > System in the Theme Control section.

ui.theme.default = classico
ui.theme.changeable = true

A Squore licence key file named squore-license.p7s should have been provided to you by Squoring Technologies under the applicable Squore licencing agreement.

Follow these steps to deploy the Squore licence file:

In this section, you will learn to configure Squore to rely on a remote licence server instead of using the licence server embedded into your local installation. This is useful when you run a production server and a development server, and you want the licence to be shared between both installations.

<interface name="public">
	<inet-address value="${jboss.bind.address:0.0.0.0}"/>
</interface>

<?xml version='1.0' encoding='UTF-8'?>
<server name="production" xmlns="urn:jboss:domain:4.2">
...
</server>

In order to point a local Squore server to a licence served by a remote Squore installation, carry out the following steps:

The local Squore Server is now using a remote licence server.

This section is useful if you want to manually execute Perl scripts that are usually internally used by Squore.

As a Squore administrator, you may need to keep track of the usage of the platform and report on its overall performance. This information is now available directly within Squore via Administration > Statistics. If you are also a model developer or a project manager and wish to fine-tune the layout of your dashboards, you will find more statistical data about how users consult analysis results via Models > Statistics and the Manage Project page. This section describes the information you can access from these pages. Note that statistics are collected locally, saved in the Squore database, and never sent anywhere. Statistics collection cannot be turned off. Viewing the statistics collected on the server is subject to licence.

Tip

Before you can view statistics on these pages, a date range must be selected in order to display information about the activity on the server during this period. You can also select whether the information is aggregated by day, week, month or year by adjusting the granularity setting.

Application Usage Statistics for Administrators

The application usage statistics are broken down into five sections where you can view information about users, projects, hardware resources, pages response time and dashboard usage.

Users

The Users tab displays the following information:

• Global statistics about user accounts for this Squore Server installation

• Information about current Web Users Web Users during the selected period

• A series of charts containing information about the number of users, new users and overall connections to the server during the selected period

• A table detailing session information per user

• A table displaying session duration statistics

Projects

The Projects tab displays information about the number of projects viewed. You can get overall numbers of visits for all the projects on the server, or select specific projects to compare their number of views. The data is rendered as:

• A chart showing a trend of the total number of projects viewed for the selected reporting period

• A chart where you can consult detailed view statistics about the projects of your choice. You can click on a project name to show or hide it from the chart.

• Information about the number of sessions per project during the selected period

Resources

The Resources tab helps administrators in monitoring the memory and disk consumption and the performance of the application.

Memory Consumption vs. Users: displays a history of the amount of memory used by the java process running the application and a line indicating the number of users who logged in during the selected period.

Database Size vs Average Load Time: displays a history of the size of the database on disk. Trend lines displaying the average page or tab load times can be displayed on the chart.

Pages

The Pages tab, shows statistics about page views and load times in tabular form and graphical form. The table automatically highlights the best result in green and the worst result in red.

Dashboard

The Dashboard tab allows analysing the usage of each tab on the dashboard. Each tab is represented in a treemap according to how many views it receives. This information can be used to adjust the default display status of each tab or their availability to end users.

Statistics for Model Developers

You can learn more about the usage of particular features of a model by clicking Models > Statistics. For each analysis model, find out how many users consult results, which projects are the most popular and which regions and charts of the dashboard are the most useful for users.

Users

The Users tab displays the information about the number of users and overall connections to the server for projects in this analysis model.

Projects

On the Projects tab, you can check how many projects had visitors over the selected period.

Dashboard

The Dashboard tab allows analysing the usage of each tab on the dashboard. Each tab is represented in a treemap according to how many views it receives. This information can be used to adjust the default display status of each tab or their availability to end users.

Charts

The Charts tab provides information about chart usage in your model: The number of views per chart (per artefact type or for all artefact types), the average loading time and the number of comments.

Statistics for Project Managers

As a project manager, you can use project statistics to investigate the popularity of your project by going to Manage > Statistics.

When you select a reporting period, the following information is displayed:

• The trend of the number of views for this project uses the colours from the scale of the root indicator as background to help you correlate the project rating with the number of visits.

• The treemap helps you understand which of the dashboard tabs is the most visited for this project.

• A table summarises the breakdown of views per user, as well as the number of comments left by each user.

You can configure WildFly to allow https access to Squore Server instead of http by following the instructions below.

After you enable HTTPS access to Squore Server following the steps described in the section called “Accessing Squore via HTTPS”, you can redirect insecure traffic to HTTPS by modifying the web server's configuration and the Squore Server application:

It is possible to use Apache in a proxy/reverse proxy role on top of Squore Server. This approach makes use of the proxy and proxy_wstunnel modules to handle web and websocket traffic between client browsers and Squore Server.

The following configuration can be used to proxy Squore Server traffic in your Apache configuration file:

<VirtualHost *:80>
  ServerName   squore.example.com
  ProxyPass / http://localhost:8180/
  ProxyPassReverse / http://localhost:8180/
  <Location />
    RewriteEngine on
    RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
    RewriteCond %{HTTP:CONNECTION} Upgrade$ [NC]
    RewriteRule .* ws://localhost:8180%{REQUEST_URI} [P]
  </Location>
</VirtualHost>

These lines of configuration are the minimum required to guarantee that the necessary traffic to and from Squore. For more complex scenarios, including SSL and certificate configuration, refer to official Apache documentation on http://httpd.apache.org/docs/2.4/.

By default, Squore Server uses its own authentication mechanism, storing user information in the Squore database. An existing directory can be used in addition, so that all existing users your the directory can log into Squore without having to create accounts manually, and the user's full name, e-mail address and department can be imported automatically. The process described in this section explains how to configure a Squore administrator, set up the server to authenticate all new users as standard users when they log in via with their LDAP credentials and finally lists the configuration files that need to be modified to turn on LDAP authentication. After you integrate with LDAP, you will still be able to create and use users that are only known to Squore and do not exist in your directory.

In order to enable LDAP authentication, follow these steps:

<login-module code="com.squoring.squore.server.security.LdapLoginModule" flag="sufficient">

<login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="sufficient">

<module-option name="allowEmptyPasswords" value="false"/>

For more details on keys and certificates management with the keytool utility, please refer to the keytool(1) man page, or online documentation.

The system-wide keystore with CA certificates is a cacert file, which is located in the java.home/lib/security directory, where java.home is the runtime environment's directory.

Note: the default password of the system-wide keystore is changeit.

Squore allows users to configure automatic sending of e-mail notifications at the end of an analysis. In order to use this feature, Squore Server must be configured to communicate with an SMTP server.

Before you start, ensure that the following details are available:

In order to configure the SMTP server integration:

Squore allows notifying all users by e-mail when planned maintenance is necessary. If you have already configured e-mail notification as explained in the section called “Configuring E-Mail Notifications”, follow these steps to send a maintenance e-mail:

The e-mail will be sent to all enabled users that have an e-mail address.

All the charts displayed on the Squore Dashboard have a unique URL, so they can be embedded into other sites.

In order to find out what the URL of a chart is, follow these steps:

The URL http://localhost:8180/SQuORE_Server/squore/resource/chart/<CHART_UID>.png.xhtml (the ?s= parameter is a way to work around the browser cache) is a permalink to this chart for this project version.

It is possible to extract some elements from the Squore dashboard and integrate them into a Confluence page. This section details how to configure Squore Server and Confluence to trust each other and how to extract the URLs to display charts.

## Macro title: Squore Dashboard Element Importer
## Macro category: External Content
## Macro has a body: N
## Body processing: No Body
##
## Developed by: Squoring Technologies
## Date created: 2013/07/28

## @param squrl:title=Squore Server URL|type=string|required=true|desc=The Squore Server URL
## @param sqport:title=Squore Server Port|type=string|required=true|desc=The Squore Server Port
## @param chart:title=Squore Element URL|type=string|required=true|desc=The URL of the Squore Dashboard Element
## @param sizex:title=Squore Element Width|type=string|required=true|desc= The Squore Element Width
## @param sizey:title=Squore Element Height|type=string|required=true|desc= The Squore Element Height
## @param version:title=Version|type=enum|enumValues=Current version,Last draft,Last baseline|default=Current version
#if ("Last draft"==$paramversion)
    #set($pversion="?version=last")
#elseif ("Last baseline"==$paramversion)
    #set($pversion="?version=last-baseline")
#else
    #set($pversion="")
#end
#set($login=$action.remoteUser.name)
<IFRAME frameborder="0" src="$paramsqurl:$paramsqport/SQuORE_Server/Export/ChartExport.xhtml?user=$login&width=$paramsizex&height=$paramsizey&chart=$paramchart$pversion" scrolling="no" width="$paramsizex" height="$paramsizey">
</IFRAME>

Adding Dashboard Elements

The macro you added in the previous section should be available to other Confluence users as the form show below from External Content.

The Confluence Squore form

Users need to fill in the following details:

• the Squore Server URL

• the Squore Server port

• the chart permalink (as retrieved according to the instructions in the section called “Embedding Dashboard Elements”)

• the desired width of the chart

• the desired height of the chart

• the version of the chart to display (exact, last or last baseline)

Note

You can either link to the chart URL ending in .png or .json. Using the link ending with .json allows you to embed a fully interactive chart with tooltips and zoom functionality in Confluence (new in 17.0), while the link ending in .png only displays a static image of the chart.

Tip

You can add several charts on the same Confluence page.

Squore for TeamForge Integration does not require any additional installation procedure.

<login-module code="com.squoring.squore.server.security.CollabnetLoginModule" flag="sufficient"/>

Squore Server can be monitored with external tools on your network by connecting to administration URLs to retrieve information about the status of projects and users on the server.

The possible values of the status field are:

Note that in order to access these URLs you must be either:

The disk space necessary for analyses varies depending on your analysis model as well as the amount of information analysed.

As a result, it is difficult to predict accurately the amount of space that your Squore installation will use. After a few runs, you should be able to estimate disk space requirements by working out the space required to analyse an artefact with your analysis model. Keep in mind that the first version of a project is always more costly than subsequent analyses, and that an analysis with only a few changes will use a lot less space than an analysis where there are a lot of changes.

Here is an example based on the Risk Index model, one of the standard multi-language models shipped in Squore 16.1.

You can save disk space by keeping data files generated by Squore only for the last baseline version. This behaviour is enabled by default and can be overridden either by using a setting in your <SQUORE_HOME>/config.xml, or by changing the behaviour for each project. This can be useful when you want to debug the analysis data later.