inrule/catalog-service repository overview

⁠InRule Catalog Service

The InRule Catalog Service is the interactive API to the SQL-backed repository that stores and versions your rule applications.

Note: This image can be deployed as a self-hosted Docker container locally or in Azure/AWS cloud platforms. The following instructions detail the steps for installing locally via Docker Desktop. For cloud-based deployment, please contact InRule Customer Support for assistance.

⁠Consumers of the Catalog Service

• irAuthor⁠ - desktop rule authoring environment
• Catalog Manager⁠ - Catalog Management UI (Docker image⁠)
• Decision Services⁠ - Decision API and Rule Execution API (Docker image⁠)

⁠What You Need

• An InRuleLicense.txt file (provided by InRule Support)
• A reachable SQL Server database, initialized with the InRule catalog schema (see Database⁠)
• Docker installed and running

⁠Required Configuration

The container requires these environment variables:

• inrule__license
• CatalogService__SqlServerConnectionString
• CatalogService__Hostname
• CatalogService__AuthenticationType

Note: Since custom parameters are required, the initial running of the container must be done via Bash or PowerShell.

⁠Optional Configuration

This service supports the following additional settings:

• Catalog Service Config File Settings⁠
• Additional Catalog Service Config Settings⁠

Note: These settings will need to be provided in the cross-platform __ formatted equivalent of the documented settings.

⁠License Requirement

Set the inrule__license environment variable to the contents of your InRuleLicense.txt file.

⁠Run the Container

Before running the container make sure you have completed the steps to setup the database⁠ first.

⁠Bash Example

docker run --rm -p 8080:8080 \
  -e inrule__license="your-inrulelicense.txt-contents" \
  -e CatalogService__Hostname="localhost:8080" \
  -e CatalogService__SqlServerConnectionString="Server=<server>,1433;Initial Catalog=InRuleCatalog;User Id=<user>;Password=<password>;TrustServerCertificate=True;" \
  -e CatalogService__AuthenticationType="Database" \
  inrule/catalog-service:latest

Note: The above multi-line command can also be run using Windows PowerShell ISE by substituting the \ end-of-line delimiter with a backtick.

⁠Verify the Container Started

• http://localhost:8080/api/status/readiness - returns 200 when the irCatalog license is valid and the catalog is reachable, otherwise 503

⁠Database Setup

The service does not create its database. Before the readiness probe reports healthy, the target SQL Server database must already exist and be initialized with the InRule catalog schema. Point the container at the database using CatalogService__SqlServerConnectionString.

Choose one of the following approaches to create and initialize the catalog database:

• Azure SQL BACPAC⁠ - import a prebuilt database into Azure SQL
• Azure SQL Database.exe⁠ - create an empty Azure SQL Database, then set up the catalog schema with InRule.Catalog.Service.Database.exe
• Manual DbBuildScripts⁠ - run SQL scripts against a new SQL Server database (e.g. AWS RDS for SQL Server, Azure SQL, or self-hosted SQL Server)

⁠Azure SQL BACPAC

Deploy the InRule Catalog database to Azure SQL Database by importing the provided BACPAC file through the Azure Portal. The steps below can be followed end to end.

Prerequisites

• Access to the target Azure subscription and permission to import an Azure SQL Database
• SQL Server administrator login and its current password
• BACPAC file⁠ to import (see below)

The BACPAC must be downloaded then stored to Azure Blob Storage in your subscription. The Portal import wizard reads the BACPAC using your subscription's blob storage link.

⁠1. Start the import (server level)

The Import database action lives on the SQL Server resource, not on an individual database.

1. Azure Portal -> SQL servers -> select the target server.
2. On the server Overview toolbar, select Import database.

⁠2. Select the BACPAC

1. Confirm the Subscription matches the target server.
2. Under Storage, choose Select backup, then select the storage account, blob container, and InRule.Catalog.Service.Database.bacpac.
3. Leave Use managed identity for storage authentication unchecked unless your environment specifically requires it.

⁠3. Configure the database

1. Under Pricing tier, select Configure database and choose settings appropriate for your environment. Production environments may require different compute, storage, and availability settings.
2. Database name - enter a unique name, for example InRuleCatalog.
3. Collation - SQL_Latin1_General_CP1_CI_AS (default).

⁠4. Authenticate and submit

1. Set Authentication type to SQL Server.
2. Enter the SQL Server administrator login and its current password.
3. Select OK to start the import. The operation can take several minutes.

⁠5. Monitor the import

Track progress on the server's Import/Export history, or on the new database's Activity log. Wait for the operation to report success - the database resource can appear before the import actually completes.

⁠Azure SQL Database.exe

Use this approach when you want to create an empty Azure SQL Database and install the InRule catalog schema with the published InRule.Catalog.Service.Database.exe utility.

Prerequisites

• Access to the target Azure subscription and permission to create an Azure SQL Database.
• An existing Azure SQL server, or permission to create one.
• The SQL Server administrator login and its current password.
• A Windows machine that can reach the Azure SQL server (you will run Database.exe locally).

To download, navigate to the latest InRule Release Assets on GitHub⁠. On that page, download InRule.Catalog.Service.Database.zip. The zip file contains InRule.Catalog.Service.Database.exe and appsettings.json.

⁠1. Create an empty Azure SQL Database

Database.exe does not create the Azure SQL Database. Create an empty database first, then the exe installs the catalog schema into it.

1. Azure Portal -> SQL servers -> select the target server.
2. On the server Overview toolbar, select Create database (or SQL databases -> Create).
3. Database name - enter a unique name, for example InRuleCatalog.
4. Under Compute + storage, choose settings appropriate for your environment. Production environments may require different compute, storage, and availability settings.
5. Leave Want to use SQL elastic pool? set to No unless your environment uses a pool.
6. Select Review + create, then Create. Wait until the database status is Online.

⁠2. Provide your local machine access through the SQL Server firewall

Database.exe runs on your computer, so the Azure SQL server must allow your public IP address.

1. Azure Portal -> SQL servers -> select the same server.
2. Left menu -> Networking.
3. Under firewall rules, select Add your client IPv4 address (or Add a firewall rule).
4. Azure fills in your current public IP. If it does not, look up your IP at https://www.google.com/search?q=what+is+my+ip⁠ and enter that value as both the start and end IP.
5. Give the rule a name, for example MyLocalMachine.
6. Select Save.

To confirm the rule later, return to Networking and check that a firewall rule exists for your current public IP.

⁠3. Set the connection string

1. Azure Portal -> open the empty database -> Connection strings.
2. Copy the ADO.NET connection string.
3. Replace {your_username} and {your_password} with the SQL Server administrator login and its current password.
4. In the unzipped package folder, open appsettings.json and set ConnectionString to that value:

{
  "ConnectionString": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;User ID=<user>;Password=<password>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
}

⁠4. Run Database.exe

Open PowerShell, change to the unzipped package folder, and run:

.\InRule.Catalog.Service.Database.exe

Wait until the command returns Success!. If it fails with a network or login error, confirm the firewall rule is saved, the database is Online, and the administrator password in appsettings.json is current.

⁠Manual DbBuildScripts

Use this approach for AWS RDS and other SQL Server environments that cannot use the Azure BACPAC import or Database.exe. You create (or use) a SQL Server database, then run the InRule catalog build scripts in order.

Prerequisites

• A reachable SQL Server instance (AWS RDS for SQL Server, Azure SQL, or a self-hosted SQL Server).
• Permission to create a database, or an empty database already created for you.
• A SQL client such as SQL Server Management Studio (SSMS) or Azure Data Studio.
• Download InRuleDbBuildScripts.zip⁠. The scripts within the zip are named so they run in order.

⁠1. Set the database name in every script

Every script contains the placeholder INSERT_DB_NAME_HERE. Replace that text with your database name in all of the install scripts, for example InRuleCatalog.

⁠2. Create the database

If the database does not already exist, run:

1. Repository_000_CreateDatabase.sql

This script runs against master and creates the database. On some hosted platforms the DBA must create the empty database for you. If the database already exists, skip this file and start with Repository_001_CreateRoles.sql.

⁠3. Run the remaining install scripts in order

Connect to the new database (or to the server, if the script begins with USE) and run these files one at a time, in this order:

1. Repository_001_CreateRoles.sql
2. Repository_002_AddDbUsersToDbRoles.sql (see the AWS note below before you run this one)
3. Repository_003_TableBuild.sql
4. Repository_070_PopulateTables.sql
5. Repository_080_GrantPermissions.sql

In SSMS, open each file, make sure the database name replacement is correct, and select Execute. Wait for each file to finish successfully before opening the next.

If you run the scripts from sqlcmd instead of SSMS, enable quoted identifiers (sqlcmd -I). Repository_070_PopulateTables.sql fails when quoted identifiers are off.

Repository_002_AddDbUsersToDbRoles.sql is optional if you will connect with an existing administrator login such as sa. Leave @DbAccountName and @DomainAccountName as NULL unless you need the script to create a SQL or Windows login and add it to the ServiceAccess role.

⁠4. AWS RDS change

Amazon RDS for SQL Server often blocks the CREATE LOGIN / server-principal steps in the stock Repository_002_AddDbUsersToDbRoles.sql.

On AWS RDS, do not run the stock 002 file. Use the RDS variant instead. Before you run it, replace INSERT_DB_NAME_HERE and set @LoginName (set @CreateSqlLogin = 1 and @LoginPassword only if the SQL login does not already exist on the RDS instance):

https://inruleintegrations.blob.core.windows.net/catalog/Repository_002_RDS_AddDbUsersToDbRoles.sql

Run that RDS file in the 002 position. All other scripts stay the same.

⁠Documentation

• irCatalog for Rule Management⁠
• InRule Catalog Service Config File Settings⁠
• Connecting to an irCatalog Service and Configuration⁠