SimpliLoad Azure Deployment Guide


Overview

SimpliLoad is a lightweight, Docker-based utility that enables IBM Cognos Analytics users to run reports through the REST API using a clean, modern interface. This guide explains how to deploy SimpliLoad using the Azure Marketplace offering, including VM provisioning, configuration, access, and connectivity to Cognos Analytics.

Prerequisites

IBM Cognos Analytics

SimpliLoad requires IBM Cognos Analytics 12.1.3 or later. Earlier versions are not supported because required REST API endpoints are unavailable.

Azure Requirements

User Requirements

Deployment Steps in Azure Portal

1. Start the Deployment

Open the Azure Marketplace listing for SimpliLoad, select your desired plan (Trial, Single, or Unlimited), and click Create to launch the Azure deployment wizard.

2. Basics

Configure the foundational Azure resource settings for your virtual machine:

VM Size

Select the hardware tier appropriate for your workload capacity:

3. SimpliLoad Configuration

Configure initial application credentials and network access parameters:

4. TLS Certificates

SimpliLoad secures all web traffic using HTTPS. You must choose how application and CA certificates are provisioned during deployment:

Organization-Provided Certificates (Recommended for Production)

If your enterprise uses internally signed or enterprise CA certificates, upload the corresponding PEM-encoded files:

SimpliLoad automatically mounts these credentials into /opt/simpliload/deploy/certs/ for the NGINX reverse proxy container to ensure secure, trusted connections.

Automatically Generated Self-Signed Certificate (Default)

If you leave the certificate upload fields blank, SimpliLoad automatically generates a secure self-signed certificate upon first boot. While fully encrypted, your browser will display an initial security warning until you trust the certificate locally or replace it later. If a public IP address is configured, it is automatically injected as a Subject Alternative Name (SAN).

5. Networking & Public IP

Configure networking settings for your deployment:

6. Review + Create

Azure runs a final automated validation check against your parameter inputs. Once validation passes, click Create to provision the infrastructure and trigger the automated installation script.

Post-Deployment Steps

Accessing & Network Configuration

SimpliLoad enforces an allowed-hosts list for security. During deployment, the VM's hostname and any provisioned public IP address are automatically added to ALLOWED_HOSTS.

1. Inbound Access (Reaching SimpliLoad)

To reach the SimpliLoad interface, inbound traffic on Port 443 (HTTPS) or Port 80 (HTTP) must be permitted:

2. Outbound Access (Connecting to Cognos)

Regardless of whether SimpliLoad is deployed with a Public or Private IP, it acts as a load generator that must initiate outbound connections to your Cognos Analytics environment.

Ensure your Network Security Groups (NSGs) and corporate firewalls allow outbound traffic from the SimpliLoad VM to your Cognos server:

Administrative SSH Access

Direct SSH access is completely optional and disabled by default. If your team requires SSH access, you must first open Port 22 via an inbound Network Security Group (NSG) rule or connect through an Azure Bastion / private VPN.

Once network access is established, authenticate using the RSA key created during deployment:

ssh <admin-user>@<hostname-or-private-ip>

Note: If you generated your key using the default path ($env:USERPROFILE\.ssh\id_rsa), your SSH client will use it automatically without requiring additional flags.

Docker containers are located under:

/opt/simpliload/

Connecting to Cognos

All Cognos configuration is performed inside the SimpliLoad UI.

On the Settings page, enter:

Click Test to verify connectivity.

Updating SimpliLoad

To update SimpliLoad:

docker compose pull
docker compose up -d

Troubleshooting

This section provides practical guidance for diagnosing and resolving common issues encountered during deployment or operation in Azure. Each item includes likely causes, recommended fixes, and steps for reviewing logs inside the SimpliLoad VM.

Invalid Certificate Errors

Common Causes:

Fixes:

Connection Failures to Cognos

Common Causes:

Fixes:

Authentication Issues

Common Causes:

Fixes:

Important: If an API key is locked, expired, or deleted in Cognos Analytics, it cannot be recovered. A new key must be generated and updated in the SimpliLoad Settings page.

Slow or Stalled Report Execution

Common Causes:

Fixes:

Container Startup Errors

Common Causes:

Fixes:

Important File Locations

The SimpliLoad VM stores all configuration files, certificates, and Docker resources under a single directory. These files are useful when troubleshooting, enabling DEBUG logging, or verifying certificate installation.

These locations are consistent across all Azure plans and do not change when resizing the VM or updating SimpliLoad.

Recommended Diagnostic Workflow:

  1. Start with docker compose logs -f simpliload-web-1 to identify application-level errors.
  2. Check docker compose logs -f simpliload-nginx-1 for certificate or routing issues.
  3. Review docker compose logs -f simpliload-db-1 for database initialization or storage issues.
  4. Temporarily set LOG_LEVEL=DEBUG in .env for deeper insight into Cognos REST interactions, then run docker compose up -d to apply changes.
Note: Always return LOG_LEVEL to INFO after troubleshooting to avoid excessive log output.