Azure Cloud Installation Instructions

1. Overview

Ursa Studio supports Azure as a first-class deployment environment, using the following resources:

• App Service for Containers
• Azure Database for Postgres
• Azure Synapse Analytics (big-data deploys only)
• Storage Account
• Data Factory

2. Preflight Questions

The following questions should be answered before beginning Azure setup

• What is the domain name? By default, the domain name of the application will look something like https://my-ursa-implementation.azurewebsites.net. Custom domains can be set up if the default domain is not desirable.
• Is the implementation large enough to necessitate the use of the columnar, “big-data-capable” Azure Synapse Analytics, or will PostgreSQL suffice?
• Do we need to set up an export container for drawdown of files?
• Which admin users, if any, will require direct access to the database?

3. Create a New Subscription

For the sake of cost management and separation of control we recommend that all the Ursa-related resources be set up with their own dedicated subscription and resource group (within the subscription). You’ll then be selecting this new subscription and resource group for every resource you create in the process.

Cost Management -> Subscriptions -> New subscription
  Pay as you go
  Rename e.g. “Ursa Health”
  IAM -> Add Role Assignment
    Add any highly trusted principals as owners
    Add any other necessary users as readers

4. Create a Resource Group

Group name: <Enter group name e.g. “ursahealth-resources”>
Resource group location: Pick the closest Azure datacenter and use it consistently for all your resources

Pin it to the dashboard.

5. Create a Storage Account

Add a “Storage account” resource
  Name e.g. “ursahealthdemostorage” (no dashes allowed)
  Deployment model: Resource manager
  Account kind: StorageV2
  Performance: Standard
  Access tier: Cool
  Secure transfer required: Enabled
  Minimum TLS Version: 1.2

Direct user downloads of raw table data is disabled by default in the Ursa Health platform due to HIPAA considerations. If you have a need to access the data in its raw form, it is possible to configure the Ursa application to export the data to a storage container, whereupon it can be picked up by trusted individuals.

In Azure this is a three-step process.

5.1 Creating a Blob Storage Container

Create a new Blob storage container for these export files. This can be done via the Storage Accounts area of the Azure Portal. The storage container should be within the same Azure Storage Account that you have already linked to your Ursa Health application. You can name this container whatever you like.

5.2 Referencing the Container from your App

Add a new Application Setting to your application to reference the new storage container. Note that you should use the name of the container itself, not the name of the Azure Storage Account. This can be done via the Configuration blade of the App Services area of the Azure Portal. The name of the setting should be EXPORT_STORAGE_CONTAINER and the value of the setting should be the name of the container you just set up.

5.3 Granting Access

The last step is to grant access to the storage container to trusted individuals. There are many ways to do this, and you can use whichever method you are comfortable with. One method that we recommend is to set up a read-only access policy with an expiration date of one year via the “Access policy” blade of the new storage container.

You can then create a “Shared Access Signature” via the Azure Storage Explorer to send out. The URL version of the signature, rather than the Query String version, is the key to accessing the container in Azure Storage Explorer.

Now your users should be able both to export raw table data to the designated export storage container, and then fetch the data once the export is complete.

6. Set up PostgreSQL Database

All implementations will require a PostgreSQL database to handle application metadata. For implementations that do not need the processing capacity of a next-generation columnar database, this same PostgreSQL database can also handle all of the data.

Add an “Azure Database for PostgreSQL” resource (NB not the various third-party options that come up when you search for postgres). Choose the “Single Server” option.

Server name: <Enter server name e.g. “ursahealth-pg”>
Admin Login Name: postgres
Password: <Choose a strong password and write it down. Avoid using the hashtag character or any other character that would require URI escaping. Dash and underscore are safe.>
The default pricing tier is fine for Big Data implementations. For pg-only, bump the storage to 200GB (or more if you know you’ll need more space)
Use Locally Redundant backup

Connection security:
  Allow access to Azure applications: Yes
  Enforce SSL: Enabled
  Minimum TLS Setting: 1.2

Security Center:
  Turn on Azure Defender

7. Bootstrap the PostgreSQL Database

This is done via your local workstation, not via the Azure Portal, so you’ll want to whitelist your IP address from the Connection Security blade of the PostgreSQL database.

The Ursa Health team can supply you with an empty application database dump file appropriate to the version of the application you’ll be starting with.

If you’re using the PostgreSQL database for both the app database and the customer database, add a role and schema via psql

PGPASSWORD=mystrongpassword psql --set=sslmode=require -h ursahealth-demo-pg3.postgres.database.azure.com -p 5432 -U ursa@ursahealth-demo-pg3 -d postgres

# create role ursa_admin;
# create schema ursa;

Then restore the database with

PGPASSWORD=mystrongpassword pg_restore -h ursahealth-demo-pg3.postgres.database.azure.com -p 5432 -U ursa@ursahealth-demo-pg3 -c -d postgres ~/Downloads/ursa-app-db-blank-v2.5.50.backup

There might be some errors about dropping schemas and tables that do not yet exist, or assigning to a user that does not exist, but these can be ignored.

After performing these steps, remove your IP address from the Connection Security blade of the PostgreSQL database.

8. Set up Azure Synapse Analytics (if applicable)

The use of an Azure Synapse Analytics is only necessary for big-data implementations that surpass the capacity of PostgreSQL.

Add “Azure Synapse Analytics”

Workspace name: <Enter workspace name e.g. “ursahealth-synapse-workspace”>
Add a Data Lake from subscription
  Create a new account name e.g. ursahealthsynapseaccount
  Create a new file system name e.g. ursahealth-synapse-fs
Security
   Admin username: sqladminuser
   Admin password: <Choose a strong password and write it down>
Do not allow connections from all IP addresses
Otherwise the default settings are fine

Add a new dedicated SQL pool
  Name e.g. ursahealthsynapsedw
  Performance level: <Choose an appropriate tier>

Turn on auditing and threat detection for both the database and the dbserver resources.
Turn on transparent data encryption for the database resource.
Auditing -> Storage Details ->
    Set storage account to the one you set up earlier
    Set retention to 3285 days
    This will create a container named sqldbauditlogs
        Make this container immutable
        Blob container -> Access Policy -> Immutable blob storage
           Time-based retention of 3285 days in a “locked” state

Database server “Firewalls and Virtual Networks” tab
  Allow access to Azure applications: Yes
  Minimum TLS Setting: 1.2

9. Set up Application

Add a “Web App for Containers” resource
App name: <App name e.g. “ursahealth-app”>
App Service Plan: Create new
  Name: e.g. “ursahealth-app-plan”
  The P2V2 plan is a good fit for most workloads
Configure container: Docker Hub
  private
  ursahealthhub/ursa-app:v5.16.0

The Ursa Health team can let you know the version to enter (instead of v5.16.0). You’ll want to create a login on Docker Hub and Ursa can grant it read access to our docker images. You’ll enter your Docker Hub username and password into this blade as well.

Configuration -> General Settings:
  Web sockets: On
  Always on: On
  ARR affinity cookie: Off
  FTP Access: Disable

App Service Logs:
  Docker container logging to File System
  100 MB quota
  1000 days retention

SSL Settings
   HTTPS only: change to On
   Minimum TLS version: 1.2

Diagnostic Settings
   Add diagnostic setting
   Name: e.g. ursahealth-demo-app-logs
   Choose AppServiceConsoleLogs
   Destination: "Archive to a storage account", and choose the storage account you set up earlier
   Retention days = 0 (means forever)
   A new blob storage container called insights-logs-* will soon appear in the storage account

Configuration -> Application Settings
  WEBSITES_ENABLE_APP_SERVICE_STORAGE… remove it if it’s preset to false
  WEBSITES_PORT=1337
  AZURE_STORAGE_ACCOUNT_NAME=<From storage account>
  AZURE_STORAGE_ACCOUNT_KEY=<From storage account>
    or AZURE_STORAGE_ACCOUNT_SAS_TOKEN=<From storage account, omitting prepended question mark>
  URSA_OUTPUT_DIR=/home/LogFiles

All other application settings are enumerated in the Ursa Health Software Platform Technical Documentation document. We recommend using Azure Key Vault to avoid entering sensitive credentials in plain text as environment variables.

10. Set up Data Factory

Name e.g. “ursahealth-factory”
Version V2
No git integration is necessary.

Create a service principal from cloud shell in PowerShell mode:

az ad sp create-for-rbac -n ursahealth-factory-service-principal --role contributor --scopes /subscriptions/{your-subscription-uuid}/resourceGroups/{your-resource-group-name}

Add the following to the app environment variables

AZURE_SUBSCRIPTION_ID=<Your subscription uuid>
AZURE_RG_NAME=<Your resource group name>
AZURE_DFSP_ID=<From service principal’s appID>
AZURE_DFSP_PASSWORD=<From service principal>
AZURE_DFSP_TENANT_ID=<From service principal>
ADO_CLIENT_DATABASE_CONNECTION_STRING=<If applicable, from Azure Synapse Analytics>

11. Set up a Custom Domain

By default, your Ursa Health application running as an App Service resource will be given a web address ending in azurewebsites.net. While this is perfectly secure, customers may prefer to set up a custom domain name.

11.1 Setting up your DNS Records

The first step needs to take place with your domain registrar, which is very likely not in Azure. Once you have decided on a subdomain, you should add a CNAME record for your preferred subdomain, such as ursa.yourdomain.com. The value of the record should be your default Azure web address, such as my-ursa-implementation.azurewebsites.net.

11.2 Adding the Custom Domain to your App Service

The remainder of the steps are all performed in the Azure Portal.

From within the Custom Domains blade of your App Service, choose the option to add a new custom domain. You should enter your chosen domain, such as ursa.yourdomain.com, into the custom domain field. If you’ve set up the DNS records properly and given it time to propagate, the validation step should work without a problem.

11.3 Create a Certificate

The next step is to create a new “App Service Certificate” resource. You can give it any name you want. In the “Naked Domain Host Name” field, put your full custom domain, such as ursa.yourdomain.com. Note that this is not the naked domain, and the input form is misleading. You really do want to enter the full custom domain name here.

Unless you are already using an Azure wildcard cert, we recommend using a standard cert for this process. This will cost some money! It should be less than $100 annually.

Once the resource is deployed, click into it to configure it. You will be prompted to add it to a new Key Value Store. You can name the Key Value Store anything you wish. Choose the standard pricing tier and the defaults for the other options.

Next, you will need to verify ownership of the domain. There are several options to do so, and you should choose whichever you think would be most straightforward for your organization.

11.4 Set the TLS/SSL Settings

Once the certificate has been verified, go back to your App Service and click into the TLS/SSL Settings blade. From the Private Certificates tab, click the option to “Import App Service Certificate”. You should see the certificate that you’ve just set up.

Then, within the Bindings tab of the same TLS/SSL Settings blade, choose the option to add an TLS/SSL binding. Choose the custom domain you’ve just set up, and use the SNI SSL type.

That’s it! Your application should now be accessible through your new custom domain name.

12. Start Using Ursa Studio

Congratulations! If you’ve followed all of these steps you should be able to get to the login screen of the Ursa Application.

Before you move on you should familiarize yourself with the Ursa Health Software Platform Technical Documentation. In particular, you’ll need to have set up transactional e-mail integration for the next step.

After the initial setup is complete, the application will be in a liminal state in which it has no registered users. The first user--and the first user only--can and must be generated by the app. To do so, enter the first user’s email address as the username, and a specialized keyword as the password which can be supplied by the Ursa Health team. The first user will be created via a transactional email sent to this email address.

After the first user has been created this technique will not work.