Scroll

Installing Exago on Azure

Microsoft® AzureTM is a cloud infrastructure for hosting files, databases, virtual machines, and web applications. Exago supports various forms of integration with Azure.

Apps: The Exago core and .NET API apps can be hosted as native Azure web apps.

VM: Exago can be hosted on a Windows-based virtual machine on Azure.

Files: Exago live data can be stored and accessed from Azure storage containers.

These methods can be implemented independent of each other. However, Web App integration and VM integration are usually redundant with each other, and most Web App solutions should also implement Azure file storage. This guide will walk through how to set up each of these solutions.

Web Application

Exago can run as a native Azure web application. This is necessary in order to run a custom .NET API application in Azure. The following Azure resources are required:

 App Service plan

 App Service (Web app)

NOTE. You may require a Storage Account to run Exago as a scalable app. See File Storage for details.

This section is divided into two parts: Hosting Exago as a Web app and Using the Exago API with Azure. If you are not implementing a custom API application, you can ignore the second part.

Hosting Exago as a Web app

NOTE. This walkthrough requires a local Exago installation. If you need to set this up, see the Exago Installation Guide. The Exago Scheduler is currently unsupported.

In your Azure Dashboard, begin by creating a new Web app container or navigating to an existing one.

In the Web app, navigate to  Settings >  Deployment credentials. Create or ensure that you've created a deployment credential. This will allow you to FTP into your web app to transfer files.

Navigate to  Settings >  Application settings. Set and save the following settings:

.NET Framework version: v4.0 or Later

Managed Pipeline Version: Integrated

Next, you'll need an FTP app. WinSCP and FileZilla are popular free apps. After running your app of choice, open a connection with your Azure app using the deployment credential you just created.

Copy your local Exago install directory to a directory in the path "/site/wwwroot/".

Finally, in the Web app, navigate to  Settings >  Application settings.

Under Virtual applications and directories create a virtual directory path for "site\wwwroot\your\exago\directory" and check the box for Application.

Test your installation by navigating a web browser to "your/app/path/virtual/path/Admin.aspx".

Make sure to configure your Config file, Reports and Temp paths.

Additional configuration may be necessary depending on your individual setup. For assistance, please file a support ticket.

Using the Exago API with Azure

Exago .NET applications must be compiled locally before being uploaded to the Azure app container. References to the WebReports dll libraries should be updated manually, and the program recompiled, when upgrading to a new Exago version.

Set your API constructor to use the previously set Exago virtual path:

Api myApi = new Api(@"/exago/virtual/path");
NOTE. Exago API apps can only access virtual paths (and not URL paths). Therefore they must be located in the same Web app container as the Exago host app.

File Storage

Exago can be integrated with Azure cloud storage for storage and live access to reports, templates, config, and other data files. The following Azure resources are required:

 Storage account

 Blob storage

The following Azure resource is optional:

 Files storage

Blob storage is a "flat" file system, which stores every file at the root level. To make use of this system, Exago emulates a directory structure using file names.

File storage is a directory-based system. Files are placed into directories, which can have sub-directories.

Reports can be stored in File storage or Blob storage. Config files, templates, themes, and temp files can only be stored in blob storage.

In your Azure Dashboard, begin by creating a new Storage account or navigating to an existing one.

This section is divided into three parts: Config file storage, Reports storage, and Temporary files storage (which includes themes and templates). If you are implementing Exago as a scalable app, you must set all three to static locations.

Config File

An Exago installation contains a configuration file, usually called WebReports.xml, which tells the application where to store Reports and Temp files.

First, in the Storage account, navigate to  Keys. Take down the account name and one of the two access keys.

You'll need an app which can give you direct access to the blob. The Azure Web Storage Explorer is a free web-based app. Use the app to upload the config file xml to a container in the blob.

Now you'll need to take down your Azure Credentials Connection String.

Azure Credentials Connection String

An Azure Credentials Connection String is a formatted string which contains your Azure account name and a unique alphanumeric key. It is used to give applications access to your storage account. The string uses the following format:

DefaultEndpointsProtocol=https;AccountName=acctName;AccountKey=encryptedalphanumerickey;
NOTE. See ConnectionStrings.com for more information on Azure connection strings. (This website is an independent resource, unaffiliated with Exago Inc.).

To obtain a connection string, in your Storage account, navigate to  Keys. Then press the ellipsis (...) to the right of one of the two keys and select View Connection String:

Next, there are two ways which you can specify to Exago the location of the configuration file:

  1. A file in the Exago install directory called appSettings.config.
  2. If you're using a .NET API app, a parameter in the API constructor method.

appSettings.config

Exago contains an xml file called appSettings.config in the root folder of the install directory. If it does not exist, create it as a text file with the following content:

<?xml version="1.0"?>
<appSettings> </appSettings>

This file is used for custom app settings which are automatically imported into Web.config during runtime.

NOTE. Do not edit the Web.config file directly. It is automatically generated by Exago, and any changes to it will be overridden.

To set the config file location, place the following key in the appSettings.config file:

<add key="ExagoConfigPath" value="pathtype=azure;credentials='My Azure Credentials Connection String';storagekey=config"/>

credentials: Your Azure Credentials Connection String.

storagekey: The prefix of the blob container used to store the config file.

API

Exago API apps cannot access the appSettings.config file. Instead, you must use one of the following two methods to specify a config file location:

  1. Place the config key within the host application's web.config or app.config.
  2. Or pass the connection string in the API constructor method:
Api myApi = new Api("/exago/virtual/path", "WebReports.xml", "pathtype=azure;credentials='My Azure Connection String';storagekey=config");

storagekey: The prefix of the blob container used to store the config file.

WebReports.xml: The name of the config file.

Reports Storage

To use an Azure storage resource for report and folder management, input a formatted connection string in the Report Path field in your config file.

NOTE. This is different from (but contains) an Azure Credentials Connection String.

The connection string uses the following format:

pathtype=azure;credentials='DefaultEndpointsProtocol=https;AccountName=acctName;AccountKey=encryptedalphanumerickey';storagekey='reports';usefilestorage=false

credentials: Your Azure Credentials Connection String.

storagekey: The prefix of the container used to store report files. Reports are stored in "storagekey-reports", templates in "storagekey-templates", and themes in "storagekey-themes". This key is optional and defaults to "wrreports".

usefilestorage: If true, Reports are stored in File storage. If false, Blob storage is used. Templates and themes always use blob storage. This key is optional and defaults to false.

NOTE. Templates are automatically stored in blobs when the template upload button is used in Exago. Themes need to be manually uploaded to blob storage.

Temporary Files Storage

Azure allows a Web app to be scaled up to multiple instances on separate servers. If you are implementing this configuration, you must take the following safeguards in order to prevent loss of user data.

Each instance of Exago has its own local temp directory, whose path you can (optionally) specify in the Temp Path setting in the config file (defaults to %INSTALLDIR%\Temp).

This is Exago's working directory — setup data for most user activity is stored and queried from here.

In a scalable configuration, initial user calls will reach one instance of Exago, storing temp files on that server, but subsequent calls may reach a separate instance, which will not have those temp files in its local directory. There are two solutions to resolve this issue: Temp Cloud Service and Azure Affinity Cookie.

Temp Cloud Service

This is Exago's built-in solution for handling multiple instances. Specifying a Temp Cloud Service causes each instance to push its temp files a shared Blob container whenever necessary. Then if a subsequent user call reaches a separate instance, that instance will pull the relevant files from the blob to its local temp directory.

To set up an Azure storage resource for temporary files, input a formatted connection string in the Temp Cloud Service field in your config file.

NOTE. This is different from a Report Path string. This is different from (but contains) an Azure Credentials Connection String.

The connection string uses the following format:

type=azure;credentials='DefaultEndpointsProtocol=https;AccountName=acctName;AccountKey=encryptedalphanumerickey'

The Temp files container name defaults to "wrtemp". Currently this cannot be changed. Temp files can only be stored in blob storage.

Azure Affinity Cookie

WARNING. This solution is UNTESTED. You should implement Temp Cloud Service as a backup.
NOTE. Your users must enable cookies.

Azure supports setting Affinity Cookies, which track which server instance each user is connected to and cause all calls within the session to reach the same instance.

In your Web app, navigate to  Settings >  Application settings. Toggle ARR Affinity to On.

Virtual Machine

Exago can be hosted on a Windows-based Azure Virtual Machine. Installing Exago on a VM differs only marginally from installing it on a local machine. Therefore, this guide will not go into depth on this method. For a full installation and setup guide, see the Exago Installation Guide.

You can interact with a VM using either a remote desktop application or a command shell application.

Using a Remote Desktop application:

  1. Using Remote Desktop Connection or another remote desktop application, view your VM as a desktop environment.
  2. Use a Web Browser to download the Exago Installer from our support site.
  3. Run the installer as Administrator and install Exago.
  4. Configure Exago (see Install and Configure).

Using a command shell:

  1. On a local machine, use the above steps 2-4 to create a temporary Exago installation.
  2. Remote into your VM using Windows PowerShell or another command shell application.
  3. Copy the Exago directory to a directory on your VM.
  4. Configure Windows and IIS (see Manual Application Installation).

After configuring IIS, open up the Exago port using a Windows Firewall inbound exception rule. You can then access Exago through the VM's IP address. Set up DNS and data security as desired.


Hidden Article Information

Article Author
Exago Development
created 2016-06-14 18:40:26 UTC
updated 2017-05-09 15:48:43 UTC

Labels
microsoft azure, azure, report management, Installation, Installing Exago, How Do I, API, AppSettings.config, Install, WebReports.xml, config file, configuration file, configuration, config, How-To, report path, report tree, cloud service, temp cloud service, temporary files, temp files, virtual machine, VM, web app, web application, cloud app, cloud application,
Have more questions? Submit a request