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:
- Completed all Common Prerequisites
- Completed all Azure-specific requirements
Deployment Options
The XMPro Terraform module provides several deployment examples:
Option 1: Basic Deployment (Recommended for Getting Started)
Clone the repository and use the basic example:
git clone https://github.com/XMPro/terraform-xmpro-azure.git cd terraform-xmpro-azure/examples/basic
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
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:
- Required Variables: See Required Variables
- Basic Configuration: See Basic Configuration
- Database Options: See Database Configuration
- Container Registry: See Container Registry
- Service Sizing: See Service Configuration
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:
- 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"
- Subscription Manager will automatically use the Redis configuration from Key Vault
- 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
- Navigate to Subscription Manager URL
- Login with admin credentials
- Configure company settings
- Set up additional users and roles
- 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:
- Login using the Super Admin account
admin@xmpro.onxmpro.com
- Navigate to Company → Subscriptions
- Click "Update License" for each product (AD, DS)
- Generate license requests and submit to XMPro support
- 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:
- Troubleshooting Guide in this documentation
- Troubleshooting section in the GitHub README
Cleanup
To remove all deployed resources:
terraform destroy
Next Steps
After successful deployment:
Access Applications
- Navigate to the URLs from terraform output
- Log in with admin credentials
Configure Applications
- Set up users and permissions
- Configure data streams
- Create applications
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