Installing report42

v3.3.1, ©2017 Circle Cardiovascular Imaging Inc.

1 Introduction

report42 with a Basic database is a small, self-contained web application with a lightweight and self-maintaining database back-end. It may be installed on Windows or Mac OS X.

report42 with an Advanced database is designed for Enterprise use. It has two major components: a web server and a database server. The web server must installed on Windows. The database server must be a Windows Server and requires Microsoft SQL Server 2008/2012/2014 Express, Standard, or Enterprise.

Advanced (Enterprise) installation should be performed by your institution's Information Technology (IT) staff, and generally requires:

  1. A fully-qualified domain name or static IP address for the web server,
  2. a fully-qualified domain name or static IP address for the database server (if it will not be installed on the same host as the web server),
  3. the administrator's email address (for the web server configuration),
  4. a valid SSL certificate for the web server, if encrypting web traffic is required by your security policy, and
  5. the required server hardware.

2 Requirements

2.1 Basic-Mode Requirements

Hardware Minimum Recommended
Processor (Intel) Core 2 Duo Core i7-4770
RAM 4GB RAM 8GB RAM
Storage Conventional hard drive with enough space to store the estimated number of images expected to be saved for each exam multiplied by the size of each image SSD drive with enough space to store the estimated number of images expected to be saved for each exam multiplied by the size of each image

Software Minimum Recommended
Operating System (Windows) Microsoft Windows 7 Home Premium Microsoft Windows 10
Operating System (Windows Server) Microsoft Windows Server 2008 R2 Microsoft Windows Server 2012 R2
Operating System (Mac) OS X 10.10 Yosemite macOS 10.12 Sierra
Client Software * cvi42® v5.5-5.6, Microsoft Edge 25 (or higher), Internet Explorer 11 (or higher), Firefox 46 (or higher), Safari 7 (or higher), or Google Chrome 50 (or higher)
Javascript Javascript must be enabled in the client web browser for correct operation of all reporting functions.
PDF Reader Adobe Reader 8 (or higher), Adobe Acrobat 8 (or higher), Apple Preview

* Adobe Flash is no longer required for version v3.2 and higher.

2.2 Advanced-Mode Database Server Requirements

Hardware Minimum Recommended
Processor (Intel) Core 2 Duo @ 1.83 GHz Xeon E5-2660
RAM 2GB RAM 4GB RAM
Storage 100GB Software RAID 1 (Mirrored) 100GB Hardware RAID 1+0 (Striped Mirrored Set) or RAID 5

Software Minimum Recommended
Operating System Microsoft Windows Server 2008 R2 Microsoft Windows Server 2012 R2
Database Management System Microsoft SQL Server 2008/2012/2014 Express Microsoft SQL Server 2014 Standard

The choice of Microsoft SQL Server Express/Standard/Enterprise edition depends on the performance requirements of the installation. Generally:

  1. For small installations with no more than about 5 concurrent (simultaneous) users the no-cost Express Edition is adequate.
  2. The Express Editions have several technical limitations, such as:
    • the number of processing cores that will be used,
    • the amount of RAM that will be used, and
    • the maximum size of the database.
  3. The Express Edition's license restricts it from being used for a public-facing web server application.
  4. More sophisticated installations will require a higher Edition of SQL Server.

2.3 Advanced-Mode Web Server Requirements

Hardware Minimum Recommended
Processor (Intel) Core 2 Duo @ 1.83 GHz Xeon Xeon E5-2660
RAM 2GB RAM 4GB RAM
Storage Enough hard drive space to store the estimated number of images expected to be saved for each exam multiplied by the size of each image

Software Minimum Recommended
Operating System Microsoft Windows Server 2008 R2 Microsoft Windows Server 2012 R2
HL7 Engine (optional) MDI MD Link 6.0, or Mirth Connect 3.2 + Java Runtime Environment 8

An SSL certificate suitable for Apache (PEM format) and a (minimum) 128-bit encryption key are required to operate over the Internet or where network security policy requires encryption.

2.4 Advanced-Mode Client Requirements

Hardware Recommended
Processor Business Class CPU at 1.5GHz or higher
RAM 1GB RAM
Printer (optional) Color printer for report hard-copy

Software Recommended
Operating System Windows 7, Windows 8, Windows 10, Mac OS X 10.10 (or higher)
Client Software * cvi42® v5.5-5.6, Microsoft Edge 25 (or higher), Internet Explorer 11 (or higher), Firefox 46 (or higher), Safari 7 (or higher), or Google Chrome 50 (or higher)
Javascript Javascript must be enabled in the client web browser for correct operation of all reporting functions.
PDF Reader Adobe Reader 8 (or higher), Adobe Acrobat 8 (or higher), Apple Preview

* Adobe Flash is no longer required for version v3.2 and higher.

3 Installation

3.1 Basic-Mode Installation

3.1.1 Installing on Windows

Copy and run the report42 installer on your Windows worstation or server. You may customize the install path for the report42 web application.

By default, report42 will install to C:\report42\.

Click Images to Enlarge

Configuration Options:

  1. Web Application
    1. Web Server Hostname (FQDN): The workstation or server's host name.
    2. Web Server Port: It is advisable to run the Web App on port 4280 on a workstation and port 80 on a server.
    3. Web Admin email: The email address for the web admin. This will appear on certain error pages if the web app fails to load.
    4. Timezone: The timezone the web server will operate under.
  2. Database Connection
    1. Basic Database File Name: The location on disk for the report42 database.
  3. Report Defaults
    1. Report Paper Orientation: The default page orientation for PDF reports. Your two options are "portrait" (tall) or "landscape" (wide).
    2. Report Paper Size: The default page size for PDF report. Common US and Metric paper sizes are supported. Suggested sizes are "letter" (US Letter) and "a4" (Metric A4).
    3. Default Number of Image Columns: The default number of columns to use for arranging images in the report.

Administrative tip: You can start or stop the report42 Web App using any of these methods:

  • manually start the "report42 Web App" service in the Windows Service Manager,
  • execute NET START "report42 Web App" at the command line, or
  • launch the report42 Web Service Monitor from the Start Menu and starting the service from its task-bar icon.

3.1.2 Installing on a Mac

Copy and run the report42 installer on your workstation.

report42 will install the software to /usr/local/report42/ and will save data under /Library/Application Support/report42/.

Administrative tip: You can start or stop the report42 Service using the following commands in Terminal.app:

  • Stop: sudo launchctl unload -w /Library/LaunchDaemons/com.circlecvi.report42.plist
  • Start: sudo launchctl load -w /Library/LaunchDaemons/com.circlecvi.report42.plist

3.2 Advanced-Mode Web Server Installation

3.2.1 Installing the report42 Web App

Copy and run the report42 installer as an administrative user on your web server. You may customize the install path for the report42 web application.

By default, report42 will install to C:\report42\.

Click Images to Enlarge

Configuration Options:

  1. Web Application
    1. Web Server Hostname (FQDN): The host name or static IP address assigned to the web server.
    2. Web Server Port: It is advisable to run the Web App on port 80, the default for HTTP.
    3. Web Server Admin: The email address for the web admin. This will appear on certain error pages if the web app fails to load.
    4. Timezone: The timezone the web server will operate under.
  2. Database Connection
    1. Database Server Hostname: The machine name (for local shared-memory-mode connections), fully-qualified domain name or IP address of the database server, with an optional Instance Name. The Instance Name is mandatory on Microsoft SQL Server Express, and is usually "\SQLEXPRESS".
    2. Database Name: The logical database name. This is REPORT42DB by default.
    3. Database Server Login: The name of the SQL server user to create with login rights to the logical database. This is "Report42WebClient" by default.
    4. Database Server Password: The password for the SQL server user with login rights to the logical database. You are strongly advised to customize this.
  3. Report Defaults
    1. Report Paper Orientation: The default page orientation for PDF reports. Your two options are "portrait" (tall) or "landscape" (wide).
    2. Report Paper Size: The default page size for PDF report. Common US and Metric paper sizes are supported. Suggested sizes are "letter" (US Letter) and "a4" (Metric A4).
    3. Default Number of Image Columns: The default number of columns to use for arranging images in the report.

Important: If you are using a version of Microsoft SQL Server other than 2012 on a single server, or you are using different servers for the Web App and Database, you need to install the Microsoft SQL Server 2012 Native Client (sqlncli.exe) on the Web Server.

Administrative tip: You can start or stop the report42 Web App using any of these methods:

  • manually start the "report42 Web App" service in the Windows Service Manager,
  • execute NET START "report42 Web App" at the command line, or
  • launch the report42 Web Service Monitor from the Start Menu and starting the service from its task-bar icon.

3.3 Advanced-Mode Database Server Installation

Install and configure Microsoft SQL Server to suit your environment. Be sure to keep a few things in mind:

  1. For installations using a single host for the Web Server and Database Server, Shared Memory will be used to connect the Web App to the database.
  2. For installations using separate hosts, Microsoft SQL Server will have to be configured to listen on TCP/IP using port 1433. On Express editions this usually needs to be manually enabled.
  3. You'll be running SQL Scripts manually to implement the report42 database schema, so be sure you have access on the server or an administration workstation from a client such as the Microsoft SQL Server Management Studio.
  4. The SQL Scripts will create an ID that connects the report42 web app with the report42 logical database, so you don't need to give out system administrator IDs.

3.3.1 Installing Microsoft SQL Server Express

If you are not integrating into an existing Microsoft SQL Server infrastructure, download and install Microsoft SQL Server 2008/2012/2014 Express.

Click Images to Enlarge

The recommended configuration options are:

  • Feature Selection: Add the Connectivity Components
  • Authentication Mode: Use Mixed Mode and set a password for the sa login ID
  • Configuration Options: Disable User Instances, Add the current user to the Administrator Role

3.3.2 Configuring SQL Server for TCP/IP

Important: this step is only required for installations where the Web Server and Database Server are installed on separate hosts on the network.

Launch the SQL Server Configuration Manager from the Start Menu. You need to make changes in the TCP/IP properties under:

  • SQL Server Configuration Manager
    • SQL Server Network Configuration
      • Protocols for SQLEXPRESS (or other instance name, such as MSSQLSERVER)
Click Images to Enlarge

Set the following in the TCP/IP Properties:

  • Protocol Enable: Yes
  • External Interface IP Address: Activate and Enable, clear TCP Dynamic Ports, set TCP Port to 1433.
  • IPAll TCP Dynamic Ports: clear the field (even if the value is 0, delete it)
  • IPAll TCP Port: Set to 1433

Save your changes and procede to:

  • SQL Server Configuration Manager
    • SQL Server Services

Select the SQL Server service and restart it using the toolbar button or from the right-click menu.

3.3.3 Installing SQL Server Management Studio

If you are using Microsoft SQL Server Express, you may want to download and install the SQL Server Management Studio separately as an alternative to the command-line tools. The default install options are acceptable.

Note: as of the 2012 version, SQL Server Management Studio is a 1GB+ download and typically requires 30-60 minutes to install. If you are using Microsoft SQL Server 2012 or greater, you may wish to consider using the built-in command-line tools instead.

3.3.4 Creating the report42 Database

The report42 Web App installer configuration wizard creates several scripts for creating and backing up its database. Periodically, a Web App update will include an Update script to add back-end features to the system.

If necessary, copy these scripts to the database server from the web server's report42 scripts program directory. Run them using the SQL Server Management Studio or the sqlcmd command-line utility in this order:

  1. CreateDB.sql: Creates the report42 logical database. By default, it is named REPORT42DB.
  2. CreateClientDBLogin.sql: Creates a local Microsoft SQL Server ID with access rights to the report42 database.
  3. CreateDefaultAdmin.sql: Creates the report42 radmin login ID with administrative rights in the web app. You are strongly advised to change the default password after logging into report42 for the first time.

For example, using the command line (including a complete log file):

C:\> cd C:\report42\scripts
C:\report42\scripts> sqlcmd -S YOURDBHOSTNAME\SQLEXPRESS -i CreateDB.sql CreateClientDBLogin.sql CreateDefaultAdmin.sql -e -u -o sqlcmdlog.txt

3.4 License Installation

License installation must be performed on the system that report42 Basic or the Advanced-Mode Web Server is installed on — by logging on directly or using remote desktop.

Installation is performed with a web browser, but this operation is restricted to web browsers running on the Web Server itself (localhost).

  1. Connect to the system where report42 Basic or the Advanced-Mode Web Server is installed.
  2. If this is a first-time install, opening report42 will show the license interface.
  3. If this is a license replacement,
    • open the Install a report42 license shortcut from the Start Menu (Windows), or
    • open the address http://localhost:4280/license/ in a web browser (Mac).
  4. Fill in the license request form (Name, Email, Institution) and save the license request (.reqx file). Email this file to support@circlecvi.com.
  5. Circle Cardiovascular Imaging Inc. will produce a license file based on the license request and send it via email. Save it temporarily on your web server or on a drive accessible from the web server.
  6. Choose the license file in the licensing page and click the Install button.
  7. If the license file installed correctly, the web browser will be redirected to the report42 login page within five seconds.

4 Upgrading

Upgrades to report42 will occasionally come in the form of new installers. It is recommended that users be notified before the report42 server is updated, asked to log out of their sessions, and that the web server is taken offline before updating.

4.1 Upgrading Windows Basic-Mode or an Advanced-Mode Web Server

Run the updated report42 installer and follow the same steps as in section 3.1.1 (Basic-Mode) or section 3.2.1 (Advanced-Mode Web Server).

4.2 Upgrading a Mac Workstation

Run the updated report42 installer and follow the same steps as in section 3.1.2.

4.3 Upgrading an Advanced-Mode Database Server

If your Database Server is not your Web Server, copy the Updates.sql script from the report42 app's scripts directory to the Database Server. This should be under C:\report42\scripts.

Open SQL Server Management Studio, and do the following:

  1. connect to the database server using an ID with admin rights on the report42 database
  2. open the Updates.sql script
  3. Execute the script. You may see a few errors, however if they don't halt the script and there are successful updates after them), then they relate to columns that have been removed in a previous version of report42 and can be ignored.

Alternatively, using the command line:

C:\> cd C:\report42\scripts
C:\report42\scripts> sqlcmd -S YOURDBHOSTNAME\SQLEXPRESS -i Updates.sql -e -u -o updatelog.txt

Now try loading the web application and verify that:

  1. you do not get a blank page or license error, and
  2. you do not see a warning in red about a database version mismatch.

5 Troubleshooting

If your users can only see a completely blank white page when they access the site, the issue is most likely PHP is unable to run. Contact Circle Cardiovasular Imaging Inc. for a fresh license.

Examining the logs may help diagnose the issue.

5.1 Troubleshooting the Web Server

On Windows, the report42 installer configures the firewall. However if you are able to use the web application from the server but not the network, make sure the correct application and/or port is permitted on the firewall:

  • The web server executable for the firewall rule will be C:\report42\apache\bin\httpd.exe.
  • Port 4280/tcp is the default for the report42 Web Server.
  • Port 80/tcp is the default for HTTP and is recommended for Advanced-Mode.
  • Port 443/tcp is the default for HTTPS (if you use SSL at your site).
  • Generally it's acceptable to allow all traffic for this executable, unless your network security policy requires more precise rules.

On Mac, if you intend to act as a server, you must configure the firewall manually to pass incoming traffic to port 4280/tcp.

5.2 Troubleshooting PHP

Temporarily add a file to the web root (report42\www) called info.php. Paste in the following code and save it.

<?php
    phpinfo();
?>

Next, try to open it with a web browser. The address will be http://<yourserveraddress>/info.php

If you receive the message 404 Page Not Found, ensure that the Web App is running.

5.3 Troubleshooting an Advanced-Mode Database Connection

Problems connecting to the database server typically show up as black pages while trying to access the product. The PHP error log C:\report42\logs\php-errors.log can often indicate where the problem lies.

Here is a list of common issues.

  • If the web app and database are on separate hosts, has the Microsoft SQL Server 2012 Native Client (sqlncli.exe) been installed on the web app host?
  • If the web app and database are on separate hosts, has the database server been configured to use the TCP/IP protocol on port 1433, as in section 3.3.2?
  • Has the Microsoft SQL Server instance been configured to allow Mixed Mode Authentication?