This document will describe how to configure mirror for a new deployment of Health Connect and how mirrored namespaces should be created. The architecture includes a ha_proxy deployment working as a load balancer, 2 web gateways that are mirror aware, 1 mirror pair and a dedicated web gateway for each node and the arbiter. For the sake of easy reproducibility, this guide uses a container deployment. However, with exception of specific docker commands, everything should work for different types of deployments.
Note that this document will not provide steps to installing Health Connect.
To fully execute this tutorial in containers:
- You must have a valid Health Connect container license key. Once you have the license, copy the file to
./license/iris/<architecture>/saved asiris.key- ./license/iris/amd64/* (example: ./license/iris/amd64/iris.key)
- ./license/iris/arm64/* (example: ./license/iris/arm64/iris.key)
- You must have access to containers.intersystems.com, simply log with your InterSystems credentials and copy & paste the Docker login command into the terminal.
Otherwise you can follow the steps on your local deployment.
To run the container using docker compose, first make sure to clone the repo, then execute below from the project root directory:
# for x64 architecture
docker compose up -d # to start the container detached
docker compose down -v # to stop and remove the container
# for arm64 architecture
docker compose --env-file=.env-arm64 up -d # to start the container detached
docker compose --env-file=.env-arm64 down -v # to stop and remove the containerWhen you environments are running, you can access it from the links below:
- SMP - primary (load balanced) - http://localhost:8080/csp/sys/%25CSP.Portal.Home.zen
- SMP - healthconnect-0 (dedicated) - http://localhost:8082/csp/sys/%25CSP.Portal.Home.zen
- SMP - healthconnect-1 (dedicated) - http://localhost:8084/csp/sys/%25CSP.Portal.Home.zen
- Username: SuperUser
- Password: SYS
This section follows the Configuring Mirroring documentation.
The mirror aware configuration is done via the CSP.ini parameter Mirror_Aware and can be found in CSP-000.ini and CSP-001.ini:
[REMOTE]
Ip_Address=healthconnect-0
TCP_Port=1972
Username=SuperUser
Minimum_Server_Connections=3
Maximum_Session_Connections=3
Password=]]]U1lT
Mirror_Aware=1There are different techniques that allow automatic mirror configuration at the instance level by leveraging the configuration merge (CPF merge). In this example we Deploy the Mirror Using Hostname Matching.
Looking at the architecture, we have two Health Connect instances:
- healthconnect-0
- healthconnect-1
The merge-mirror.cpf contains a line that can leverage the naming convention and automatically deploy mirror. The same CPF merge is applied to both instances and they get configured following the behavior described in the documentation with a mirror set named HEALTHCONNECT. In addition to that, another line to enable ECP is also part of the file.
ConfigMirror:Name=HEALTHCONNECT,Map="primary,backup",Member=auto,Primary=auto,ArbiterURL=arbiter:2188
For more information on general CPF merge, see Automating Configuration of InterSystems IRIS with Configuration Merge.
To leverage the automation of mirrored namespaces creation from HealthShare products (including Health Connect) on later stages, we need to mirror HSSYS database. See Configuring Mirroring for Healthcare Products.
HSSYS database comes with all healthcare products and, as of the date of this guide, there is no automated way of mirroring it without having to move database files at the OS level, which requires manual or scripted intervention.
-
Added HSSYS to mirror set on the primary node
Go to HSSYS Database Properties on System Administration → Configuration → System Configuration → Local Databases → HSSYS and click Add to Mirror HEALTHCONNECT, after you are done you should see the mirror set assigned to HSSYS (second screenshot).
-
Dismount HSSYS on the primary node
Go to HSSYS Database Details on System Operations → Databases → HSSYS and click Dismount.
-
Copy HSSYS.DAT from the primary node to the backup node
From your operating system terminal execute the command below to enter the primary node container.
docker exec -it healthconnect-0 bashThe directory
/tmpis shared between healthconnect-0 and healthconnect-1, so we will copy the file there firstFrom the container terminal we just got access to, run the command below to copy the database.
cp -p /usr/irissys/mgr/hssys/IRIS.DAT /tmp/. && exit
-
Remount HSSYS on the primary node
Go to HSSYS Database Details on System Operations → Databases → HSSYS and click Mount.
-
Dismount HSSYS on the backup node
Go to HSSYS Database Details on System Operations → Databases → HSSYS and click Dismount.
-
Copy the primary HSSYS.DAT from the shared directory to the backup node
From your operating system terminal execute the command below to enter the backup node container.
docker exec -it healthconnect-1 bashFrom the container terminal we just got access to, run the command below to copy the database.
mv /tmp/IRIS.DAT /usr/irissys/mgr/hssys/IRIS.DAT && exit
-
Remount HSSYS on the backup node
Go to HSSYS Database Details on System Operations → Databases → HSSYS and click Mount.
-
Activate & Catchup HSSYS on the backup node
Go to Mirror Monitor on System Operations → Mirror Monitor and click Activate. Once is activated click on Catchup.
Still following Configuring Mirroring for Healthcare Products, we now need to update Network Host Name to be the VIP or the Load Balancer, in our case we have a load balancer called loadbalancer.
On the primary node, go to the Installer Wizard on Health → Installer Wizard and click Configure Network Host Name. Change the Network Host Name value to loadbalancer and save.
Make sure that HS_Services user is active and has a valid password when creating new namespaces. See Predefined User Accounts
The last step is to activate a task that keeps IRISSYS (which is not mirrored) synced on the backup member. For more, see Mirroring Considerations for Healthcare Products.
From your operating system terminal execute the command below to enter the IRIS terminal in the backup node container.
docker exec -it healthconnect-1 iris terminal iris -U HSLIBThen run the command to configure the task.
do ##class(HS.Util.Mirror.Task).Schedule("HSSYS")
hOnce the command above is executed you can see the task in the Task Schedule of the backup node.
Give it a couple of minutes for the task to run once is configured.
Now that mirror is configured, we can create namespaces that are automatically mirrored.
Go to the Installer Wizard on Health → Installer Wizard and click Configure Foundation. In there, update the Local Name to MIRRORED and tab out, the rest will be automatically populated. Make sure that Mirror Database is checked and save.
Still from the Installer Wizard screen, click in Activate for the MIRRORED entry that was just created. After the execution is complete, you should see that activation was successful.
When looking at the backup Mirror Monitor on System Operations → Mirror Monitor, you can confirm that the database is configured.
Play around with starting a production and failing over to observe the behavior.
To failover, from your operating system terminal execute the command below to enter the primary node container.
docker exec -it healthconnect-0 bashThen run the command to restart the instance.
iris restart irisYou should notice that when accessing the load balanced SMP healthconnect-1 became the primary and load balancing works fine.
For this container deployment, if you want to have everything configured in a scripted way, update Custom.Loader.cls by changing AUTOMIRROR from 0 to 1, save and restart your containers (down and up -d again). This will execute the exact same steps above (allow a few minutes for the script to run). To explore the script, see Custom.AutoMirror.cls.
/// Parameter AUTOMIRROR = 0;
Parameter AUTOMIRROR = 1;
...