In this section we will guide you through the setup and configuration of the i-refactory server, the web application and optionally the OAuth2 server. The Solution Overview briefly introduces what these components do and how they interact.
Before you continue installing i-refactory server please make sure the following prerequisites are met.
You should have system administrator access to a host system on which NodeJS is supported. The host system should have at least the following minimal resources.
{info} As a best practice you should install a single i-refactory server per (virtual) host.
Our i-refactory servers run as HTTPS servers. You need to have a valid SSL certificate and SSL key file available. Our servers need read access to these files. You should check with your security officer regarding the policies of generating SSL certificates.
For development and testing you could create a self signed certificate. If you have openssl available here is an example how to create a certificate for the localhost domain.
openssl req \
-newkey rsa:2048 \
-x509 \
-nodes \
-keyout server.key \
-new \
-out server.crt \
-subj /CN=localhost \
-reqexts SAN \
-extensions SAN \
-config <(cat /System/Library/OpenSSL/openssl.cnf \
<(printf '[SAN]\nsubjectAltName=DNS:localhost')) \
-sha256 \
-days 365
This command generates two files server.key
and server.crt
.
The client operating system or browser now needs to have the CA certificate added to its list of trusted root authority certificates. The instructions vary by operating system and browser but instructions for a few major clients are listed below. For all these steps the 'certificate' referred to is the 'server.crt'.
Client | Instruction |
---|---|
Windows | Right click the server.crt certificate file and select 'Install Certificate'. Follow the prompts to add the certificate to the trust store either for the current user only or all users of the computer. |
Mac | Open KeyChain and drag the file server.crt into KeyChain. Set the certificate to trusted. |
Linux - Ubuntu | sudo cp ~/server.crt/usr/local/share/ca-certificates/ sudo update-ca-certificates See Ubunbtu help for more information. |
Your DBA should provide you with:
If you will be using your own OAuth2 server you will need to have the following information available:
If you are going to use our i-refactory OAuth2 server we need to have read access to a private and public RSA key pair.
There are many ways to create RSA keys. OpenSSL is one of the most popular libraries for key creation and management:
# Generate a private key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
# Derive the public key from the private key
openssl rsa -pubout -in private_key.pem -out public_key.pem
The private key file private_key.pem
will be used in our OAuth2 server to sign the JWT token.
The publicy key file public_key.pem
will be used in our i-refactory server to check if the generated JWT token is not tampered with.
The i-refactory server, i-refactory OAuth2 server and i-refactory web application are all build in NodeJS. NodeJS applications can be run on almost any platform. All of these components run as HTTPS servers.
The i-refactory servers always run against a Long Term Support release of NodeJS. In our Release Notes Overview you can see which NodeJS version is required for the given i-refactory server release.
You can download the LTS version of NodeJS at Download NodeJS. To download a previous LTS version check this Download Previous Releases of NodeJS.
Follow the install instructions for your platform.
You can check if NodeJS is available by entering the following command in your terminal:
node --version
It should return the installed LTS version, for example: v12.14.1
.
You should create a folder on your host filesystem where we are going to install the i-refactory server software and where you can store your configuration files and optionally store your SSL certificates and required key files.
The folder structure we suggest:
i-refactory\
config\
crypto\
dist\
In the config folder you should store you configuration files which will be explained in Step 4: Create a configuration file.
In the crypto folder you should store the SSL certificate and key file and the public RSA key file.
From the provided installation zip file unpack the folder i-refactory-engine
to the folder i-refactory\dist
.
Our i-refactory server requires a configuration file. The configuration file is a JSON document which contains mandatory and optional configuration settings.
We have provided two sample configuration files which you can find in i-refactory\dist
.
config.example.json
: This configuration file can be used as a template. Copy it to a convenient location and filename.With a text editor of choice edit your configuration file. When you have opened the file you will see something like this:
{
"boot": {
"database": {
"code": "IREFACTORY",
"description": "i-refactory metadata repository",
"connection": {
"driverConnectionProperties": {
"server": "",
"authentication": {
"options": {
"userName": "",
"password": ""
}
}
}
}
}
},
"httpRestApi": {
"enabled": true,
"https": {
"port": 3000,
"host": "localhost",
"key": "crypto/ssl.key",
"cert": "crypto/ssl.crt"
},
"accessToken": {
"publicKey": "crypto/key_public.pem",
"signatureAlgorithm": "RS256"
}
},
...
The configuration file is in JSON format.
Follow the steps below to change your configuration setting.
Set the connection parameters for SQL Server
In your editor go to the section "boot". You should see something similar like below.
{
"boot": {
"database": {
"code": "IREFACTORY",
"description": "i-refactory metadata repository",
"connection": {
"driverConnectionProperties": {
"server": "",
"authentication": {
"options": {
"userName": "",
"password": ""
}
}
}
}
}
}
}
Change the following configuration settings:
parameter | instruction |
---|---|
code |
Change the default value to the name of the database where the i-refactory metadata repository is installed. |
server |
Set the value to hostname where your SQL Server Instance is running. |
userName |
Set the value to the SQL Server login name who is authorized to access the i-refactory metadata repository. |
password |
Set the value to the SQL Server login password. |
Configure the i-refactory rest API server settings
In your editor go to section "httpRestApi" You should see something similar like below.
{
"httpRestApi": {
"https": {
"host": "localhost",
"port": 3000,
"key": "",
"cert": ""
},
"accessToken": {
"publicKey": "crypto/key_public.pem",
"signatureAlgorithm": "RS256"
}
}
}
Change the following configuration settings:
parameter | instruction |
---|---|
host |
Set the hostname of the i-refactory rest API server. Defaults to localhost . |
port |
Set the port number of the i-refactory server. Defaults to 3000 . |
key |
Specify the file location including the filename of the SSL key. You should use your generated or provided SSL key filename. |
cert |
Specify the file location including the filename of the SSL certificate. You should use your generated or provided SSL certificate filename. |
publicKey |
Specify the file location including the filename of the public key filename with which we can verify the validity of the OAuth2 token provided. You should use your generated public key filename for this. |
signatureAlgorithm |
Specify the signature algorithm used. If you use the i-refactory provided OAuth2 server you should keep the default setting RS256 . |
Configure the Swagger server settings
In your editor go to section "httpRestApi" You should see something similar like below.
{
"swaggerServer": {
"enabled": true,
"https": {
"host": "localhost",
"port": 3001,
"key": "",
"cert": ""
}
}
}
Change the following configuration settings:
parameter | instruction |
---|---|
enabled |
If you set this value to true a Swagger server is started. You can access the Swagger documentation of our i-refactory Rest API via the browser. If you set this value to false we do not start a Swagger server and you cannot use your browser to view the i-refactory Rest API specification. |
host |
Set the hostname of the Swagger server. Defaults to localhost . |
port |
Set the port number of the i-refactory server. Defaults to 3001 . |
key |
Specify the file location including the filename of the SSL key. You should use your generated or provided SSL key filename. You can use the same SSL key as for the i-refactory Rest API server or opt for a different one. |
cert |
Specify the file location including the filename of the SSL certificate. You should use your generated or provided SSL certificate filename. You can use the same SSL key as for the i-refactory Rest API server or opt for a different one. |
Configure the UI server settings
In your editor go to section "httpRestApi" You should see something similar like below.
{
"uiServer": {
"enabled": true,
"https": {
"host": "localhost",
"port": 3002,
"key": "",
"cert": ""
},
"apiUrl": "https://localhost:3000",
"authorizationServer": {
"clientId": "i-refactory-ui",
"authorizationEndPointUri": "https://localhost:3003/authorize",
"tokenEndPointUri": "https://localhost:3003/token"
}
}
}
Change the following configuration settings:
parameter | instruction |
---|---|
enabled |
If you set this value to true a UI server is started. You can access the i-refactory web application via the browser. If you set this value to false we do not start a UI server and you cannot use our i-refactory web application. |
host |
Set the hostname of the UI server. Defaults to localhost . |
port |
Set the port number of the UI server. Defaults to 3002 . |
key |
Specify the file location including the filename of the SSL key. You should use your generated or provided SSL key filename. You can use the same SSL key as for the i-refactory Rest API server or opt for a different one. |
cert |
Specify the file location including the filename of the SSL certificate. You should use your generated or provided SSL certificate filename. You can use the same SSL key as for the i-refactory Rest API server or opt for a different one. |
apiURL |
The web application sends request to the i-refactory Rest API server. It needs to know the URL where to reach the i-refactory Rest API server. Set the value to https:\\ + the host you specified in httpRestApi + ':' + the port you specified in httpRestApi . |
clientId |
The web application needs to be identified by a unique id. This is required for OAuth2. Use the default value i-refactory-ui or change the value to a new string value. You will need this unique id later on when configuring OAuth2. |
authorizationEndPointUri |
Specify the url of the OAuth2 server authorization end point. |
tokenEndPointUri |
Specify the url of the OAuth2 server token end point. |
The main purpose of the Logical Validation Layer (LVL) is to transform the data received from external data sources to fit into the logical data model structure. It is also responsible for validating deliveries. The Logical Validation Layer is also known as the Historical Staging In (HSTGIN) Layer.
A schema is a set of database objects, such as tables, views, triggers, stored procedures, etc. In some databases a schema is called a namespace
. A schema always belongs to one database. However, a database may have one or multiple schema's. A database administrator (DBA) can set different user permissions for each schema.
Each database represents tables internally as <schema_name>.<table_name>
, for example tpc_h.customer
. A schema helps to distinguish between tables belonging to different data sources. For example, two tables in two schema's can share the same name: tpc_h.customer
and complaints.customer
.