--- title: "Azure Cloud Installation Instructions" slug: "azure-cloud-installation-instructions" updated: 2024-06-04T13:51:37Z published: 2024-06-04T13:51:37Z canonical: "docs.ursahealth.com/azure-cloud-installation-instructions" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.ursahealth.com/llms.txt > Use this file to discover all available pages before exploring further. # 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: 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: Admin Login Name: postgres Password: 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) Azure Synapse Analytics is only one of several options for the customer database. Snowflake, MSSQL, Databricks, and PostgreSQL are other options supported by Ursa Studio in Azure. ``` Add “Azure Synapse Analytics” Workspace name: 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: 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: 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 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= AZURE_STORAGE_ACCOUNT_KEY= or AZURE_STORAGE_ACCOUNT_SAS_TOKEN= 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 Data Factory is the mechanism by which Azure can move data from storage containers into MSSQL, PostgreSQL, or Synapse databases. As such, this section is unnecessary for Snowflake or Databricks deployments. ``` 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= AZURE_RG_NAME= AZURE_DFSP_ID= AZURE_DFSP_PASSWORD= AZURE_DFSP_TENANT_ID= ADO_CLIENT_DATABASE_CONNECTION_STRING= ``` ## 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.