Table of Contents

Implementation Guide

Introduction

This guide provides step-by-step instructions for deploying XMPro on Azure using the Terraform module. For detailed technical specifications, configuration options, and module documentation, please refer to the GitHub README.

Prerequisites

Before starting, ensure you have:

Deployment Options

The XMPro Terraform module provides several deployment examples:

  1. Clone the repository and use the basic example:

    git clone https://github.com/XMPro/terraform-xmpro-azure.git
    cd terraform-xmpro-azure/examples/basic
    
  2. Copy and customize the configuration:

    # Linux/Mac:
    cp terraform.tfvars.example terraform.tfvars
    
    # Windows:
    copy terraform.tfvars.example terraform.tfvars
    
    # Edit terraform.tfvars with your values
    
  3. Review the example configuration in the Basic Usage section of the README.

Option 2: Production Deployment

For production deployments, refer to the Using Custom Company Name for Production Workloads section in the README which covers:

  • Production-grade App Service SKUs
  • Custom domain configuration
  • Email notification setup
  • Existing database integration

Option 3: Custom Implementation

Create your own Terraform configuration using the module directly. See the Module Source Options in the README for different ways to reference the module.

Deployment Process

Step 1: Initialize Terraform

terraform init

Step 2: Plan Your Deployment

terraform plan

Step 3: Apply Configuration

terraform apply

Step 4: Access Your Applications

After deployment, retrieve the application URLs:

terraform output
Tip

For detailed deployment instructions and troubleshooting, see the GitHub README.

Configuration Reference

The module supports extensive configuration options. Key areas include:

Deployment Scenarios

Evaluation Mode vs For Production Workloads

The module supports two deployment modes. See Evaluation vs For Production Workloads in the README for detailed explanation.

Using Existing Database

For scenarios where you have an existing SQL Server, see Existing Database Support.

Custom Domain Configuration

To configure custom domains with automatic SSL certificates, refer to the DNS and Domain Configuration section.

Configure Autoscale

The module supports distributed caching via Redis for improved performance and scalability. Autoscale is disabled by default.

Note

Currently, autoscale functionality is only available for Subscription Manager (SM). Support for Application Designer (AD) and Data Stream Designer (DS) will be added in future releases.

Prerequisites

Before enabling autoscale, you need:

  • An existing Azure Cache for Redis instance or compatible Redis service
  • Redis connection string with authentication credentials
  • Network connectivity between App Services and Redis instance

Enabling Autoscale

Autoscale with Redis is configured through two simple variables:

# In your terraform.tfvars
enable_auto_scale = true
redis_connection_string = "your-redis.redis.cache.windows.net:6380,password=your-password,ssl=True,abortConnect=False"

When enable_auto_scale = true:

  • The module sets AutoScaleEnable = "true" in the SM Key Vault
  • The Redis connection string is stored securely in Key Vault as REDIS secret
  • Currently, only Subscription Manager (SM) uses the Redis configuration via Key Vault

Creating Azure Cache for Redis

To create an Azure Cache for Redis instance, see the Azure Cache for Redis documentation.

Once created, use the connection string in your Terraform configuration:

enable_auto_scale = true
redis_connection_string = "mycompany-redis.redis.cache.windows.net:6380,password=<primaryKey>,ssl=True,abortConnect=False"

Post-Deployment Configuration

After enabling autoscale:

  1. Verify Key Vault secrets are configured:
    az keyvault secret show --vault-name "kv-sm-xmpro-xxx" --name "AutoScaleEnable"
    az keyvault secret show --vault-name "kv-sm-xmpro-xxx" --name "REDIS"
    
  2. Subscription Manager will automatically use the Redis configuration from Key Vault
  3. Monitor Redis metrics in Azure Portal for performance
Important

The module does not create or manage Redis instances. You must provide an existing Redis connection string.

Tip

To learn more about Redis configuration and its impact on XMPro performance, see the Redis Cache Implementation.

Health Checks Configuration

The module automatically configures comprehensive health checks for Application Designer (AD) and Data Stream Designer (DS) services. Health checks are enabled by default via feature flags.

Automatic Health Check Configuration

Health checks are automatically enabled by default for Application Designer (AD) and Data Stream Designer (DS) services.

Health Check Endpoints

The following services expose health check endpoints:

Service Health Check URL Health UI URL
Application Designer /health /health-ui
Data Stream Designer /health /health-ui
Note

Subscription Manager (SM) does not expose health check endpoints. It uses traditional Windows Web App monitoring. To verify SM is running, use the /version endpoint instead.

Cross-Service Monitoring

Each service (AD, DS) is automatically configured to monitor other services that expose health endpoints.

Monitoring Health Status

To verify service status:

# Check individual service health
curl "$(terraform output -raw ad_app_url)/health"
curl "$(terraform output -raw ds_app_url)/health"

# Check SM version (alternative to health check)
curl "$(terraform output -raw sm_app_url)/version"

# Access Health UI dashboard in browser
"$(terraform output -raw ad_app_url)/health-ui"

Expected response: 200 OK with health status JSON showing the status of all monitored services.

Health Dashboard

The Health UI provides a visual dashboard accessible at /health-ui on AD and DS services. The dashboard shows:

  • Real-time status of all XMPro services
  • Response times and availability metrics
  • Service dependency health status
  • Historical health data
Note

For detailed health check configuration and troubleshooting, see the Health Checks technical reference.

Third-Party Health Checks

Note

Configuration for third-party health check monitoring services (such as Azure Application Insights availability tests, external monitoring tools, or custom health check endpoints) is coming in a future release.

SSO Configuration

Note

SSO configuration for Azure Terraform deployments is coming in a future release.

Tip

For comprehensive SSO setup guides, troubleshooting, and best practices, see the technical references on SSO:

Post-Deployment Validation

Verify Deployment

After deployment, verify your applications are running:

# List deployed resources
az resource list --resource-group $(terraform output -raw resource_group_name) --output table

# Check application versions
curl -f "$(terraform output -raw ad_app_url)/version"
curl -f "$(terraform output -raw ds_app_url)/version"
curl -f "$(terraform output -raw sm_app_url)/version"

Access Applications

Navigate to the URLs provided by terraform output:

  • SM (Subscription Manager): Configure users and licenses
  • AD (App Designer): Build applications
  • DS (Data Stream Designer): Create data pipelines

Initial Configuration

  1. Navigate to Subscription Manager URL
  2. Login with admin credentials
  3. Configure company settings
  4. Set up additional users and roles
  5. Configure license keys

Admin Logins

After deployment, you can access the platform with these accounts:

User Type Password
admin@xmpro.onxmpro.com Super Admin Value from site_admin_password variable
{firstname}.{lastname}@{company_name}.onxmpro.com Company Admin Value from company_admin_password variable
Warning

The username format is critical: firstname.lastname@company_name.onxmpro.com

License Management

Evaluation Mode

When is_evaluation_mode = true, the deployment includes:

  • Automatic license provisioning via licenses container
  • Pre-configured evaluation product IDs and keys
  • No manual license requests required
  • Forces company name to "Evaluation" (overrides any company_name variable value)
Note

The examples/basic configuration uses is_evaluation_mode = true as default for quick evaluation deployments.

Note

To use a custom company name, you must set is_evaluation_mode = false and request licenses from XMPro for your specific company name.

For Production Workloads (Default)

When is_evaluation_mode = false (default), you need to manually request licenses:

  1. Login using the Super Admin account admin@xmpro.onxmpro.com
  2. Navigate to Company → Subscriptions
  3. Click "Update License" for each product (AD, DS)
  4. Generate license requests and submit to XMPro support
  5. Upload received licenses
Note

License requests require SMTP configuration to be enabled during deployment. See the Module Documentation for SMTP setup.

Troubleshooting

For common deployment issues and solutions, see:

Cleanup

To remove all deployed resources:

terraform destroy

Next Steps

After successful deployment:

  1. Access Applications

    • Navigate to the URLs from terraform output
    • Log in with admin credentials
  2. Configure Applications

    • Set up users and permissions
    • Configure data streams
    • Create applications
  3. Review Security

    • Enable Azure AD authentication
    • Configure network restrictions
    • Review audit logs

Support

For deployment issues:

  • Review the Troubleshooting Guide
  • Check Terraform logs: terraform show
  • Contact XMPro support with deployment details

Last modified: October 06, 2025