Diffblue Cover installation instructions

Prerequisites

Please ensure your system meets these software and hardware requirements:

  • Hardware (for medium-sized projects and proof of concept):
    • 64GB RAM
    • 50GB free local storage on / per repository being analyzed
      • 30GB free in /var/lib/docker
      • 20GB free in the $HOME of the user running the Diffblue Cover service (by default this is /root/diffblue-docker) Note: free means available at the time of Diffblue Cover installation.
    • 8 cores
  • Operating systems:
    • Ubuntu 16.04, 16.10
    • Red Hat 7.2, 7.3, 7.4
    • CentOS 7.2, 7.3, 7.4
    • Debian 9
  • Software packages to be installed:
    • Docker 1.13.0 (or later)
    • Docker-compose 1.15.0 (or later)
    • Python 2.6 (with argparse package) or later, including Python 3
    • OpenSSL 1.0.2 or later (or equivalent e.g. LibreSSL)
  • Network ports to be opened:
    • incoming (Diffblue as a server):
      • TCP/80
    • outgoing (Diffblue as a client):
      • access to your repository (if needed)

Note: Please install Docker using instructions from the official Docker website as most package repositories host only outdated versions.

  • Minimum hardware requirements (for single small projects and demos):
    • 16GB RAM
    • 30GB free local storage on / Note: free means available at the time of Diffblue Cover installation.
    • 4 cores

The install script install-diffblue.py will check that the requirements above are met. See the next section for details.

Installation

The package you received from us should contain these files:

  • datasheet.pdf
  • diffblue_check.py
  • diffblue.sha256
  • diffblue.tar.gz
  • install_readme.md
  • install-diffblue.py
  • install_guide.pdf
  • java-demo.zip
  • licenses.txt
  • user-manual.pdf

Copy the files to a new directory on the server and open the terminal in that directory. If you want to access the public documentation, move user-manual.pdf to a GUI-based environment. Note that the remaining installation steps assume your working directory is the new directory you created.

We provide both a quick and a detailed version of the installation procedure. The detailed version extends the quick one by describing optional steps, possible customizations, and other features and uses of the install script.

Quick install

By default, the installer generates its own self-signed SSL certificate. When you run Diffblue Cover in a browser, you'll receive an unsigned certificate warning. To proceed, you'll need to trust this certificate. If you prefer to use your own certificate, take a look at the detailed install section of this page.

To install Diffblue Cover:

sudo python ./install-diffblue.py

If the installation succeeds you'll see the following messages in the output:

The installation finished SUCCESSFULLY.
Starting Diffblue server.
The server started SUCCESSFULLY.

Detailed install

To provide your own SSL certificate after installation:

  1. Name your certificate CoverCert.crt.

  2. Name your private key CoverCert.key.

  3. Copy those two files to /opt/diffblue/certificates

    If you've run the install before, these two files are already in the directory. It's safe to replace them.

  4. Restart the systemd service:

    sudo systemctl restart diffblue.service

It is best practice to check the integrity of the archive provided:

sha256sum -c diffblue.sha256

You should see the following output. If not, please contact Diffblue:

diffblue.tar.gz: OK
install-diffblue.py: OK

If the integrity check is successful, run the installation:

sudo python ./install-diffblue.py

The installer checks for necessary free space in several locations; /var/lib/docker (30GB), /opt/ (10MB) and $HOME (20GB). $HOME is checked because by default the installer places Cover's workspace in this directory. This can be overridden by setting a new workspace directory using the --install-directory command line parameter.

To provide your own workspace directory:

  1. Create the directory you want to use e.g. /opt/diffblue/workspace

  2. Run the installer and provide the --install-directory argument e.g. sudo ./install-diffblue.py --install-directory=/opt/diffblue/workspace

The installation calculates an upper limit to the amount of memory it consumes by checking the amount of system memory available. If you would like to explicitly limit the amount of memory used by the service you can call the installation script with the following option, where 'N' is the amount of memory in GB:

sudo python ./install-diffblue.py --mem-limit N

Both methods for running the installation command perform these actions:

  1. Checks whether platform requirements from the previous section are met - if not, the script terminates with an error message describing the issue.
  2. Extracts all installation packages inside diffblue.tar.gz to a temporary folder ./diffblue.
  3. Loads extracted images into the local Docker registry.
  4. Creates a systemd service.
  5. Reloads the systemd daemon.
  6. Computes the memory limit for the Diffblue service, compares it with the user's limit (if passed to the script), and writes the result into the config file docker-compose.yml.
  7. Saves the configuration files to the directory /opt/diffblue.
  8. Deletes the temporary installation folder.
  9. Starts Diffblue server.

You can also use the install script to check platform requirements without performing the installation with the --check-requirements option:

sudo python ./install-diffblue.py --check-requirements

The script uses PyYAML Python library for manipulating the YAML file. If the library is already available to Python (for example, installed using pip), the script will use it. Otherwise, the script will use a copy of the library included in the diffblue.tar.gz package. The script will NOT install the library to Python, it will only use the library temporarily during the execution of the script.

If you want to suppress the automated start of the Diffblue server after successful installation, add the option --no-start-service to the installation command.

If the script runs successfully the output should end with:

The installation finished SUCCESSFULLY.
Starting Diffblue server.
The server started SUCCESSFULLY.

The installation is now complete. You can check that the Diffblue service is running:

sudo systemctl status diffblue

The expected output is:

● diffblue.service - Diffblue Server
   Loaded: loaded (/etc/systemd/system/diffblue.service; disabled; vendor preset: disabled)
   Active: active (running) since Thu 2017-01-12 12:05:11 UTC; 1min 57s ago
 Main PID: 2760 (docker-compose)
   Memory: 44.5M
   CGroup: /system.slice/diffblue.service
           ├─2760 /usr/local/bin/docker-compose -f /opt/diffblue/docker-compose.yml up
           └─2761 /usr/local/bin/docker-compose -f /opt/diffblue/docker-compose.yml up

Jan 12 12:05:22 test1.c.united-backbone-144118.internal docker-compose[2760]: application-server_1  | Database connected
Jan 12 12:05:22 test1.c.united-backbone-144118.internal docker-compose[2760]: application-server_1  | Admin Database connected
Jan 12 12:05:22 test1.c.united-backbone-144118.internal docker-compose[2760]: mongo_1               | 2017-01-12T12:05:22.902+0000 I NETWORK ... open)
Jan 12 12:05:22 test1.c.united-backbone-144118.internal docker-compose[2760]: mongo_1               | 2017-01-12T12:05:22.914+0000 I INDEX   ...true }
Jan 12 12:05:22 test1.c.united-backbone-144118.internal docker-compose[2760]: mongo_1               | 2017-01-12T12:05:22.914+0000 I INDEX   ...0 secs
Jan 12 12:05:22 test1.c.united-backbone-144118.internal docker-compose[2760]: mongo_1               | 2017-01-12T12:05:22.927+0000 I INDEX   ...true }
Jan 12 12:05:22 test1.c.united-backbone-144118.internal docker-compose[2760]: mongo_1               | 2017-01-12T12:05:22.927+0000 I INDEX   ...0 secs
Jan 12 12:05:22 test1.c.united-backbone-144118.internal docker-compose[2760]: mongo_1               | 2017-01-12T12:05:22.937+0000 I NETWORK ... open)
Jan 12 12:05:27 test1.c.united-backbone-144118.internal docker-compose[2760]: mongo_1               | 2017-01-12T12:05:27.895+0000 I NETWORK  [conn...
Jan 12 12:05:52 test1.c.united-backbone-144118.internal docker-compose[2760]: mongo_1               | 2017-01-12T12:05:52.983+0000 I -       ... open)
Hint: Some lines were shortened, use -l to show in full.

Usage

You can control the Diffblue service.

  • Start the Diffblue service:

    sudo systemctl start diffblue
    
  • Check the status of the Diffblue service:

    sudo systemctl status diffblue
    
  • Stop the Diffblue service:

    sudo systemctl stop diffblue
    
  • Configure the Diffblue service to start automatically at boot time:

    sudo systemctl enable diffblue
    

When running, the Diffblue service is accessible on all interfaces of the server on TCP/443 - https://SERVERIP

results matching ""

    No results matching ""