Installing Omara CDR

This topic shows you how to install Omara CDR. The install has four parts:

1. Deploying the Omara CDR Operator
2. Preparing a PostgreSQL database
3. Creating an administrative interface
4. Creating one or more FHIR repositories

Typically, when you deploy the administrative interface you define:

• basic infrastructure parameters, such as the database location, service ports and api paths through the Kubernetes CR

When you deploy a CDR repository you define:

• basic infrastructure parameters and repository settings such as the database location, service ports, pod replication, FHIR version, externally loaded JARs and API paths through the Kubernetes CR
• Smile module specific configurations such as MDM configuration, validation rules, interceptor settings, authentication methods, partitioning and consent rules through the Smile API or administrative console

Note: This topic shows you how to perform a manual install of Omara CDR. We also provide a number of deployment patterns that you can use to deploy CDR with other common Omara modules including databases, Ingress, and Kafka.

Prerequisites

Omara Modules are supplied using an Operator Lifecycle Manager (OLM) catalog. You must install OLM and the Omara catalog before you will be able to follow the steps documented here.

Omara CDR requires a PostgreSQL database. You must already have one running. You can use the Omara PostgreSQL operator to deploy PostgreSQL. You can also use any other network-reachable instance of PostgreSQL, including those database as a service instance provided by the cloud providers.

To create an in-cluster database please refer to Modules > Omara PostgreSQL for instructions on deploying the operator DB cluster creation.

To create a simple database suitable for a development instance of Smile CDR, execute the following script to create a simple database:

kubectl apply  -f - << EOF
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: omara-cdr-db
spec:
  image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:ubi8-13.7-1
  postgresVersion: 13
  instances:
    - resources:
        limits: 
          memory: 500M
          cpu: 500m
        requests: 
          memory: 250M 
          cpu: 250m
      dataVolumeClaimSpec:
        accessModes:
        - "ReadWriteOnce"
        resources:
          requests:
            storage: 40G
  backups:
    pgbackrest:
      image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:ubi8-2.38-2
      repoHost: 
        resources: 
          limits: 
            memory: 500M
            cpu: 500m
          requests: 
            memory: 150M 
            cpu: 150m
      repos:
      - name: repo1
        volume:
          volumeClaimSpec:
            accessModes:
            - "ReadWriteOnce"
            resources:
              requests:
                storage: 20G
EOF

The script below prepares the newly created database (create a database user and role). If you modify the script (for example, provide a different password), your changes must also be reflected in the CDR admin and repo CRs.

Note: Please ensure that the database is “ready” before running this script.

kubectl exec -i $(kubectl get pod |grep omara-cdr-db | grep -v backup | grep -v repo-host | cut -d " " -f1) -- psql -U postgres omara-cdr-db <<EOF
CREATE ROLE cdr LOGIN password 'smilecdr';
CREATE DATABASE cdr ENCODING 'UTF8' OWNER cdr;
GRANT ALL PRIVILEGES ON DATABASE cdr TO cdr;
CREATE DATABASE cdr_deleted ENCODING 'UTF8' OWNER cdr;
GRANT ALL PRIVILEGES ON DATABASE cdr_deleted TO cdr;
Commit;
EOF

The script:

• Creates a new role called CDR and sets your password as smilecdr.
• Creates a database called CDR.
• Assigns the role to the CDR database.

Installing Omara CDR Operator

This section shows you how to manually deploy CDR using the Operator Lifecycle Manager (OLM) and the Omara CDR operator. The process is roughly:

• determine where (the namespace) you wish to deploy CDR
• create a Subscription to the Omara CDR Operator
• manually approve the InstallPlan that is created when OLM ‘sees’ the Subscription

Subscribe to the Omara CDR Operator

This section shows you how to create a subscription for the Omara CDR operator and approve the install plan.

Use VS Code or kubectl config set-context --current --namespace=$NAMESPACE to change context to the target namespace. This is the Kubernetes namespace where you wish to deploy the Omara CDR Operator and instance of CDR that the operator manages. You may need to create the namespace first with kubectl create namespace $NAMESPACE.

If not previously performed for this namespace, create an OperatorGroup to inform the installed operators to monitor custom resources in this namespace:

kubectl apply -f - << EOF
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: $NAMESPACE-ns-operators
spec:
  targetNamespaces:
  - $NAMESPACE
EOF

Now subscribe to the Omara CDR Operator by creating a Subscription with:

kubectl apply -f - << EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: omara-cdr
spec:
  channel: stable
  name: omara-cdr
  source: omara-catalogsource
  sourceNamespace: olm
  installPlanApproval: Manual
EOF

where source: omara-catalogsource specifies the name that you used when you installed the Omara catalog

This Subscription instructs OLM to install the latest version of the omara-cdr operator available in the Catalog Source. The installation is set to Manual to avoid automated installation of new versions, including the first installation.

Since this is the first installation of the Omara CDR Operator, OLM chooses the latest available version from the catalog and create an InstallPlan. Approve the InstallPlan as follows:

kubectl patch installplan `kubectl get installplans | grep omara-cdr | awk '{print $1}'` -p '{"spec":{"approved":true}}' --type merge

You can confirm that the install plan was correctly updated with:

kubectl get installplans

Upgrading the Documentation Operator

The process is roughly:

• Update the omara-catalogsource with new image
• Manually approve the install plan

Update the omara-catalogsource with new image

Take the latest codebase of Omara Documentation module and apply the latest omara-catalogsource CRD yaml using this command:

kubectl apply -f modules/omara-catalogsource/deployment/omara-catalogsource.yaml

This will update the omara catalog source and automatically create a new install-plan for omara-cdr v1.1.0. To verify, run this command:

kubectl get ip -n YOUR_NAMESPACE

The output should have newly created installplan as APPROVED false

Manually approve the install plan

Approve the InstallPlan as follows:

kubectl patch installplan `kubectl get installplans | grep omara-cdr | awk '{print $1}'` -p '{"spec":{"approved":true}}' --type merge

You can confirm that the install plan was correctly updated with:

kubectl get installplans

At this point, you should have an Operator that monitors all namespaces for the following Custom Resources:

(Optional) Install a CDR admin console and Ingress to enable access

You can deploy the CDR admin console using this command:

kubectl apply -f - << EOF
apiVersion: omara.io/v1
kind: CDRAdmin
metadata:
  name: omara-cdr-admin-basic
spec:
  admin_api_listener_contextpath: /fhir/admin
  admin_api_listener_port: 9000
  repo_db_password: smilecdr
  repo_db_url: jdbc:postgresql://omara-cdr-db-primary:5432/cdr
  repo_db_username: cdr
  resources:
    requests:
      memory: 1Gi
      cpu: 100m
    limits:
      memory: 1Gi
      cpu: 200m
EOF

Note: You should review and update the omara-cdr-admin-basic.yaml file to update any database connection changes you might have made.

You can create an Ingress route to the admin console using this command:

Note: Replace “DOMAIN_NOT_DEFINED” with your deployment domain.

kubectl apply -f - << EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    kubernetes.io/ingress.class: nginx
  name: omara-cdr-admin-basic
spec:
  rules:
  - host: data.DOMAIN_NOT_DEFINED
    http:
      paths:
      - backend:
          service:
            name: omara-cdr-admin-basic
            port:
              number: 9100
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - data.DOMAIN_NOT_DEFINED
    secretName: omara-cdr-admin-cert
EOF

After you install the admin console

After installing, login to your Admin URL to verify the install and change the password.

1. Launch the Omara CDR Admin Console (URL- https://data.YourDeploymentDomain) and login in with admin/password
2. Click on Config > User Manager. This will launch the User Manager page with a modify option for Superuser roles.
3. Select Modify for the Node: omara-cdr-default-repo under Module column and Superuser under roles and permission column. This will display the Edit user page for the admin user.
4. Scroll down in the page to the Security section and enter your new password in the Password tab.
5. Scroll up on the page and Click on Save. You will see a confirmation message as Password is updated successfully

Deploying a simple CDR repository

You can deploy a simple FHIR R4 repository using the following command:

Note: You can review and update the following to update any database connection changes you might have made, correctly set the replica count, and load any external Smile CDR interceptor files and jars. Additional parameters are described in the usage documentation.

kubectl apply -f - << EOF
apiVersion: omara.io/v1
kind: CDRRepo
metadata:
  name: omara-cdr-repo-basic
spec:
  admin_api_listener_contextpath: /fhir/admin
  admin_api_listener_port: 9000
  fhir_listener_contextpath: /fhir
  fhir_listener_port: 8000
  repo_db_password: smilecdr
  repo_db_url: jdbc:postgresql://omara-cdr-db-primary:5432/cdr
  repo_db_username: cdr
  resources:
    requests:
      memory: 1Gi
      cpu: 100m
    limits:
      memory: 1Gi
      cpu: 200m
EOF

You can create an Ingress route to the FHIR API endpoint of the repo by using this command:

Note: Again, you should replace “DOMAIN_NOT_DEFINED” with your deployment domain.

kubectl apply -f - << EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    kubernetes.io/ingress.class: nginx
  name: omara-cdr-repo-basic
spec:
  rules:
  - host: data.DOMAIN_NOT_DEFINED
    http:
      paths:
      - backend:
          service:
            name: omara-cdr-repo-basic
            port:
              number: 8005
        path: /fhir
        pathType: Prefix
  tls:
  - hosts:
    - data.DOMAIN_NOT_DEFINED
    secretName: omara-cdr-repo-cert
EOF

Next Steps

See usage for further information on using Smile CDR and the CDR operator.

References

• Smile CDR
• Smile CDR latest version docs
• FHIR v4.0.1
• HAPI FHIR - The Open Source FHIR API for Java