• What is Cromwell on Azure?
  
• Deploy Cromwell on Azure now using this guide
  
• A brief demo video on how to run workflows using Cromwell on Azure
  

• Prepare, start or abort your workflow using this guide
  
• Here is an example workflow to convert FASTQ files to uBAM files
  
• Have an existing WDL file that you want to run on Azure? Modify your existing WDL with these adaptations for Azure
  
• Want to run commonly used workflows? Find links to ready-to-use workflows here
  

• See our Troubleshooting Guide for more information.
  
• Known issues and work-arounds are documented here
  

If you are running into an issue and cannot find any information in the troubleshooting guide, please open a GitHub issue!

Cromwell is a workflow management system for scientific workflows, orchestrating the computing tasks needed for genomics analysis. Originally developed by the Broad Institute, Cromwell is also used in the GATK Best Practices genome analysis pipeline. Cromwell supports running scripts at various scales, including your local machine, a local computing cluster, and on the cloud.

Cromwell on Azure configures all Azure resources needed to run workflows through Cromwell on the Azure cloud, and uses the GA4GH TES backend for orchestrating the tasks that create a workflow. The installation sets up a VM host to run the Cromwell server and uses Azure Batch to spin up virtual machines that run each task in a workflow. Cromwell on Azure supports workflows written in the Workflow Description Language or WDL format.

1. You will need an Azure Subscription to deploy Cromwell on Azure.
2. You must have the proper Azure role assignments to deploy Cromwell on Azure. To check your current role assignments, please follow these instructions. You must have one of the following combinations of role assignments:
   1. Owner of the subscription
      
   2. Contributor and User Access Administrator of the subscription
   3. Owner of the resource group. . Note: this level of access will result in a warning during deployment, and will not use the latest VM pricing data. Learn more. Also, you must specify the resource group name during deployment with this level of access (see below).
   4. Note: if you only have Service Administrator as a role assignment, please assign yourself as Owner of the subscription.
3. Install the Azure Command Line Interface (az cli), a command line experience for managing Azure resources.
4. Run az login to authenticate with Azure.

Download the required executable from Releases. Choose the runtime of your choice from win-x64, linux-x64, osx-x64

Optional: build the executable yourself. Clone the Cromwell on Azure repository and build the solution in Visual Studio 2019. Note that VS 2019 and .NET Core SDK 3.0 and 2.2.x are required prerequisites. Build and publish the deploy-cromwell-on-azure project as a self-contained deployment with your target RID to produce the executable

1. Linux and OS X only: assign execute permissions to the file by running the following command on the terminal:
   chmod +x <fileName>. Replace <fileName> with the correct name: deploy-cromwell-on-azure-linux or deploy-cromwell-on-azure-osx.app
2. You must specify the following parameters:
   1. SubscriptionId (required)
      1. This can be obtained by navigating to the subscriptions blade in the Azure portal
   2. RegionName (required)
      1. Specifies the region you would like to use for your Cromwell on Azure instance. To find a list of all available regions, run az account list-locations on the command line or in PowerShell and use the desired region's "name" property for RegionName.
   3. MainIdentifierPrefix (optional)
      1. This string will be used to prefix the name of your Cromwell on Azure resource group and associated resources. If not specified, the default value of "coa" followed by random characters is used as a prefix for the resource group and all Azure resources created for your Cromwell on Azure instance. After installation, you can search for your resources using the MainIdentifierPrefix value.
         
   4. ResourceGroupName (optional, required when you only have owner-level access of the resource group)
      1. Specifies the name of a pre-existing resource group that you wish to deploy into.

Run the following at the command line or terminal after navigating to where your executable is saved:

.\deploy-cromwell-on-azure.exe --SubscriptionId <Your subscription ID> --RegionName <Your region> --MainIdentifierPrefix <Your string> 

Example:

.\deploy-cromwell-on-azure.exe --SubscriptionId 00000000-0000-0000-0000-000000000000 --RegionName westus2 --MainIdentifierPrefix coa 

Deployment can take up to 25 minutes to complete. At installation, a user is created to allow managing the host VM with username "vmadmin". The password is randomly generated and shown during installation. You may want to save the username, password and resource group name to allow for advanced debugging later.

Prepare, start or abort a workflow using instructions here.

Once deployed, Cromwell on Azure configures the following Azure resources:

• Host VM - runs Ubuntu 16.04 LTS and Docker Compose with four containers (Cromwell, MySQL, TES, TriggerService). Blobfuse is used to mount the default storage account as a local file system available to the four containers. Also created are an OS and data disk, network interface, public IP address, virtual network, and network security group. Learn more
• Batch account - The Azure Batch account is used by TES to spin up the virtual machines that run each task in a workflow. After deployment, create an Azure support request to increase your core quotas if you plan on running large workflows. Learn more
• Storage account - The Azure Storage account is mounted to the host VM using blobfuse, which enables Azure Block Blobs to be mounted as a local file system available to the four containers running in Docker. By default, it includes the following Blob containers - cromwell-executions, cromwell-workflow-logs, inputs, outputs, and workflows.
• Application Insights - This contains logs from TES and the Trigger Service to enable debugging.
• Cosmos DB - This database is used by TES, and includes information and metadata about each TES task that is run as part of a workflow.

All of these resources will be grouped under a single resource group in your account, which you can view on the Azure Portal. Note that your specific resource group name, host VM name and host VM password for username "vmadmin" are printed to the screen during deployment. You can store these for your future use, or you can reset the VM's password at a later date via the Azure Portal.

You can follow these steps if you wish to mount a different Azure Storage account that you manage or own, to your Cromwell on Azure instance.

Cromwell on Azure uses managed identities to allow the host VM to connect to Azure resources in a simple and secure manner. At the time of installation, a managed identity is created and associated with the host VM. You can find the identity via the Azure Portal by searching for the VM name in Azure Active Directory, under "All Applications". Or you may use Azure CLI show command as described here.

To allow the host VM to connect to custom Azure resources like Storage Account, Batch Account etc. you can use the Azure Portal or Azure CLI to find the managed identity of the host VM and add it as a Contributor to the required Azure resource.

For convenience, some configuration files are hosted on your Cromwell on Azure Storage account, in the "configuration" container - containers-to-mount, and cromwell-application.conf. You can modify and save these file using Azure Portal UI "Edit Blob" option or simply upload a new file to replace the existing one.

See this section in the advanced configuration on details of how to connect a different storage account, batch account, or a private Azure Container Registry.

For these changes to take effect, be sure to restart your Cromwell on Azure VM through the Azure Portal UI or run sudo reboot.

As part of the Cromwell on Azure deployment, a "Hello World" workflow is automatically run as a check. The input files for this workflow are found in the inputs container, and the output files can be found in the cromwell-executions container of your default storage account. Once it runs to completion you can find the trigger JSON file that started the workflow in the workflows container in the succeeded directory, if it ran successfully.

Hello World WDL file:

task hello {
  String name

  command {
    echo 'Hello ${name}!'
  }
  output {
	File response = stdout()
  }
  runtime {
	docker: 'ubuntu:16.04'
  }
}

workflow test {
  call hello
}

Hello World inputs.json file:

{
  "test.hello.name": "World"
}

Hello World trigger JSON file as seen in your storage account's workflows container in the succeeded directory:

{
  "WorkflowUrl": "/<storageaccountname>/inputs/test/test.wdl",
  "WorkflowInputsUrl": "/<storageaccountname>/inputs/test/test.json",
  "WorkflowOptionsUrl": null,
  "WorkflowDependenciesUrl": null
}

Run Broad Institute of MIT and Harvard's Best Practices Pipelines on Cromwell on Azure:

Data pre-processing for variant discovery

Germline short variant discovery (SNPs + Indels)

Somatic short variant discovery (SNVs + Indels)