Quick start - install Fusion Registry

From Metadata Technology Wiki
Jump to navigation Jump to search

Fusion Registry is a Java web application. Here's how to install it.

Overview

Applicability:

  • Fusion Registry Data Essentials
  • Fusion Registry Enterprise Edition

The Fusion Registry Software Stack

FR10 minimum software stack.png

Step 1: Set up the computing environment

Start by setting-up the computing environment. Here's what's required:

Computing Platform Windows 10 or Linux.
Computer Memory Minimum of 4GB of memory for a simple installation, but more memory will be required when handling larger datasets. Plan for at least 8GB if using the Fusion Datastore in-memory database in a production environment.
Java Runtime Environment Java 1.8 or 1.10 JRE or JDK. Amazon Corretto 8 is a good free-to-use choice.
Database Fusion Registry needs a SQL database service to store its metadata content and configuration, but the same database can also be used for data storage. MySQL, SQL Server and Oracle are supported. For a quick-start installation, install a local copy of MySQL, although existing database services can be used if you have them. Data Essentials requires two databases, one to contain the metadata content (structures) and configuration and one for the data. Existing database services can be used BUT the Data Essentials Registry must be able to manage the database.
Web Application Server The Fusion Registry software runs under the control of a Web Application Server. Options include Apache Tomcat, Jetty, JBOSS and IBM Websphere. Apache Tomcat 8.5 or 9.0 are recommended.
Authentication Directory Service (optional) Fusion Registry can operate in single-user mode. But if you need to allow multiple users to login with different privileges then an external directory service is required. Microsoft Active Directory or LDAP (OpenLDAP is a free-to-use LDAP implementation) are recommended. Alternatively, Metadata Technology's Fusion Security provides a simple directory service that can be installed alongside Fusion Registry.

Step 2: Configure the Java Web Application environment (Apache Tomcat example)

Web application server products have different procedures for configuration and deploying applications. The example here uses Apache Tomcat. If you're using a different web application server, refer to its documentation for guidance.

Configuration for Fusion Registry is principally set by creating a setenv.bat or setenv.sh script in the Tomcat bin directory.

Below are examples for Windows and Linux.

Windows

tomcat\bin\setenv.bat
set "JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx4G -server -DRegistryProperties=file:///C:/Tomcats/Environments/fusion_registry.properties"
set CLASSPATH=c:\oracle\ojdbc8.jar

Linux

tomcat/bin/setenv.sh
#!/bin/sh
export JAVA_OPTS="-Xms128m -Xmx4G -server -DRegistryProperties=file:\\opt\tomcats\environments\fusion_registry.properties"
export CLASSPATH="/opt/oracle/ojdbc8.jar"

JAVA_OPTS Configuration Parameters

JAVA_OPTS parameters configure the Java virtual machine, and also allow system parameters to be passed to the Fusion Registry application to alter its behaviour.

Parameter Purpose Example
-Xmx Sets the maximum amount of memory that can be allocated to the Java heap. This should be a minimum of 4GB and ideally about 75% of available memory on the machine. Setting too low may result in Java 'out of memory' errors. -Xmx4GB
sets the maximum heap size to 4GB
-Xms Sets the initial amount of memory to be allocated to the Java heap. When running in production, there may be a performance benefit to setting this to the same value as -Xmx which avoids the need to grow the heap as memory demand grows. -Xms128m
sets the initial heap to 128MB
-server Improves performance by optimising the way the Java Virtual Machine works.
-DRegistryProperties System Property: Sets a specific path for the Fusion Registry properties file. If not set, the default location is used -DRegistryProperties=file:\\opt\tomcats\environments\fusion_registry.properties
In Linux, sets the properties file location to the path specified.
-Djson.legacy.enabled=true
or
-Djson.legacy.enabled=false (default)
System Property: Sets whether the Fusion Registry instance uses the legacy Metadata Technology JSON dialect, or the official SDMX-JSON version 1.0 Structure and Data Exchange format.

By default, or if the property is explicity set to false, JSON returned will conform to the official SDMX-JSON specification when:

  • JSON is chosen as a format in the web user interface when exporting data or structures;
  • The HTTP 'Accept' header is set to 'application/vnd.sdmx.json' when making a REST web service call; or
  • The URL format parameter is set to 'sdmx-json' when making a REST web service call.

If the property to true, JSON returned will conform to Metadata Technology's legacy JSON format for structures and data. Use this for backward compatibility where existing client-side applications rely on the legacy JSON format.

-Djson.legacy.enabled=true
Force Fusion Registry to produce and accept structures and data in the legacy Metadata Technology dialect
-DLicenseFile= (Data Essentials only) Sets the location of the License file and the Public key which is used in Data Essentials. -DLicenseFile=file:///C:/tomcats/RegistryProperties/8080_LICENSE/fusionLicense.fl sets the location to a specific location on the C drive

CLASSPATH Settings for Oracle

The CLASSPATH environment variable tells the Java Virtual Machine where to look for additional classes.

If you want to use an Oracle database, you must download the JDBC driver directly from Oracle and reference the location of the jar by setting the CLASSPATH variable as illustrated in the examples.

Step 3: Extract the Fusion Registry WAR file from the software distribution

Fusion Registry is a Java web application so deployment and upgrade of the software is different to Linux packages or native Windows applications that come with installation wizards.

The Fusion Registry Core server is distributed as a single ZIP archive that contains a number of files and sub-directories. For instance:

FusionRegistry-10.0.0.zip

Distribution.PNG

The FusionRegistry.war file is the 'web application archive' (WAR) which encapsulates the entire Fusion Registry application in one file.
Extract this file.

Data Essentials

You can download a PDF version of the Data Essentials User Guide here

Step 4: Deploy the WAR file to the Web Application Server

Web application server products have different procedures for deploying applications.

The procedure here applies to Apache Tomcat. If using a different web application server, you'll need to refer to the appropriate product guide.

  1. Stop the Tomcat process or service, if it is running.
  2. Copy the Fusion Registry WAR file to the Tomcat webapps directory.
  3. Restart the Tomcat process.

The Tomcat service should start and automatically deploy the Fusion Registry application to a URL under the same name as the WAR file.

If the WAR file FusionRegistry.war is deployed as provided in the distribution folder, the Fusion Registry service should be accessible on a URL similar to the following examples:
http://localhost:8080/FusionRegistry
http://myserver.mydomain.local:8080/FusionRegistry
http://192.168.1.27:8080/FusionRegistry

The hostname is dependent on the configuration of the machine on which Fusion Registry has been installed. The port 8080 is the Tomcat default, and may be different if you have altered the Tomcat settings.

If the name of the deployed WAR file has been changed to something other than FusionRegistry.war, Tomcat will use that name in the URL. For instance, renaming the WAR file to TestRegistry.war will result in a URL similar to the following:
http://localhost:8080/TestRegistry

Step 5: Fusion Registry Basic Configuration

Once Fusion Registry has successfully started, a one-time configuration process needs to be completed to set various core parameters including the operating database, appearance and security settings.

Use a web browser to navigate to the Fusion Registry URL, for example:
http://localhost:8080/FusionRegistry

Database Connection

Instal1.PNG
Provide the connection details to your chosen database service. Fusion Registry will use this as its main operating database.
The schema must already exist, but can be empty in which case Fusion Registry will create all of the necessary tables. If you specify an existing Fusion Registry schema here, the service will attempt to load the content and settings held there.

If your database service requires special parameters such as authentication details, use the Custom Database Type option which allows the JDBC connection string to be set.

Data Essentials The schema entered here will be used to store the structures. The schema to store data is linked to Data Essentials in another step once the installation is complete. Data Essentials - Connect to the data schema

Server Settings

Page 2.PNG
The basic operating settings for the Fusion Registry service:

Setting Detail
Server URL The URL through which the Fusion Registry service can be accessed. Generally, this can be the base URL from Step 3 such as http://localhost:8080/FusionRegistry. However, it's used by the web GUI to determine how to connect to the API.
Username The login name for the "root" user (super user).
Password The password for the "root" user (super user).
Max Login Attempts -1 means unlimited, enter a positive number to change this

Data Essentials

You should now:

  1. Open a browser
  2. Navigate to your Registry
  3. Log on
  4. Then create your database connection

Appearance

Fusion Registry Version 10.3 and above (including Data Essentials)

This page should be accessed from the Administration Area - Server Settings


Pre Version 10.3

FR10 Install Step 3.PNG

Set the appearance of the Fusion Registry web user interface.

Setting Detail
Registry Logo Optional. Upload an image file of maximum size 200 x 200 pixels which will replace the Fusion Star logo in the top left-hand corner of the Fusion Registry web user interface window.
Favicon Optional. Upload an ico file to set the favicon for the Fusion Registry web user interface this. This can be any image as long as it is 16 x 16 pixels.
Colour Scheme Choose a different base colour for the Fusion Registry web user interface. If you run multiple Fusion Registry environments, it's helpful to give them different colours to give users a visual clue as to which environment they are working on.


Fusion Registry Version 10.3 and above (including Data Essentials)

This page should be accessed from the Administration Area - Server Security


Pre Version 10.3

Security Settings

FR10 Install Step 4.PNG
Set the authentication details for the master superuser account which provides complete control over all Fusion Registry configuration settings and content.

Usernames 'root' or 'admin' are typically used, but otherwise there are no restrictions. Choose a cryptic password, particularly if the web interface or API will be exposed.

Step 6: Installation complete

FR10 Install Step 5.PNG

The installation is complete.
Log-in using the master superuser account to complete detailed configuration, create or load structural metadata and manage data.