Deployment topology#

Reportworq runs in more than one shape, and for high throughput an on-premises instance can be scaled out across several servers. Read this page first, before you install: it helps you choose a deployment, summarizes what each one needs, and explains how a load-balanced cluster is put together, including the handful of network and configuration facts that make the difference between a cluster that forms and one that silently does not.

Choose your deployment#

The full hardware, browser, and network requirements are the same across shapes and live on one page, see System requirements.

Whichever shape you choose, Reportworq 5 and Reportworq 6 can run side by side on the same server. Version 6 installs into its own folder and listens on its own default port, so it does not disturb a running version 5, which keeps its own folder and port. That makes a staged migration practical: stand version 6 up alongside version 5, bring content across, and validate before you decommission anything.

On-premises (Windows)#

The customer hosts and runs Reportworq on their own Windows servers and activates against the licensing service. The MSI installer registers the Reportworq 6 Bootstrap Service, which hosts the web application and the job runtime. The default web port is 8600 (with the Real-time Event Hub on 8601), and a fresh install serves over HTTPS out of the box. See Install Reportworq.

On-premises (Linux)#

The same application ships as a Linux tarball that runs the web binary directly on .NET 10. There is no MSI and no Windows service. Because the automatic first-boot certificate is Windows-only, enable HTTPS on Linux through configuration or a TLS-terminating reverse proxy (see below).

Single-tenant cloud (Azure container)#

The runtime tier is platform-neutral, so a single-tenant instance can be containerized and run on Azure App Service or Container Apps:

• The application runs from a read-only container image and takes its boot settings (repository path, port, HTTPS, instance identity) from the environment rather than a writable settings file.
• The Repository lives on an Azure Files mount; that mounted storage is the only durable state. Azure Files is the supported storage today. An Azure Blob storage backend is planned for a future release.
• Sign-in runs behind Entra / OIDC, and stored credentials are portable, so a lift-and-shift keeps them without re-entry.
• Because the image is read-only, you update by swapping the container image tag or the App Service container setting and restarting, not with the in-product updater.
• One web instance owns the UI and the scheduler; you scale throughput by adding worker nodes against the same shared repository. The web tier itself is not horizontally scaled today.

Sizing and moving to Azure#

Moving an existing on-premises instance into an Azure container is the change customers most often ask for help with, so this section is deliberately concrete.

Sizing the App Service plan. The hardware guidance is the same as any other deployment: allow for the base footprint plus roughly 2 GB of RAM per concurrent job, see System requirements. Translating that to a plan:

Size the plan against your peak concurrency, not your average. Peak memory tracks the number of jobs in flight, so the plan has to hold the busiest moment rather than the typical one, and the Parallel Job Execution limit is what you use to keep that ceiling predictable, see Server configuration.

What the deployment consists of. An App Service plan and App Service running the container image, a storage account with an Azure Files share for the repository, and log storage. The Files share is the only durable state, so it is the thing to back up and the thing to size for growth.

What to expect when you move. Three differences catch people who are used to the Windows install:

• Stored credentials travel. Secrets are encrypted with a portable key rather than tied to a Windows machine, so a lift and shift keeps them without re-entry.
• Configuration moves from a settings file to the environment. The container will not rewrite its own settings, so the repository path, port, HTTPS and instance identity all arrive as environment variables.
• Certificates and custom fonts come from the repository, not from the host filesystem, because the image is read only.

Two things you cannot do on this path, both worth knowing before you commit to it: the in-product updater is disabled, so you update by swapping the image tag, see Update Reportworq; and a v5 repository import is not available, so migrate a v5 repository with a Windows or Linux install first and point the container at the resulting v6 repository.

Scaling. Run exactly one web instance, which owns the UI and the scheduler, and add worker nodes against the same repository for throughput. The web tier is not horizontally scaled today.

For the step-by-step install, see Install Reportworq.

CloudHub#

CloudHub is a Reportworq-operated relay, not a hosting tier. It lets external clients reach an on-premises instance without exposing its direct API surface. Two kinds of client use it:

• AI clients, such as Copilot and desktop MCP clients, reaching your curated reports.
• External services calling the REST API, so a system outside your network can start a Reportworq job. This is how integration and automation platforms such as Workato, and other cloud-hosted services, trigger reporting without a VPN or an inbound firewall rule into your network.

Registering an on-premises instance with CloudHub is itself the approval for that channel, and it is not coupled to the Local API switch: locking down the direct API does not disable CloudHub-relayed access, and vice versa. Keep the two mental models distinct.

Calling the REST API through CloudHub still requires the API capability on your license, see Licensing and entitlements.

HTTPS, first boot, and reverse proxies#

Reportworq serves over HTTPS, which the Excel add-in and every Microsoft 365 integration require. How HTTPS comes on depends on the deployment shape.

• HTTPS out of the box. A fresh Windows on-premises install generates a self-signed certificate, trusts it on the server, and turns on HTTPS at first boot, so the first browse to the server is https://. This applies only to a genuinely new Windows on-premises install: it never changes an existing HTTP deployment, a load-balancer node, or a Linux or container host. For the certificate actions, and how to let client machines trust the certificate, see Server configuration.
• Behind a reverse proxy. When Reportworq runs behind a TLS-terminating reverse proxy (such as Caddy, nginx, or IIS ARR) that forwards plain HTTP to it, set BehindReverseProxy to true in settings.json and restart. There is no screen for this setting, so hand-edit the file. With it set, Reportworq honors the X-Forwarded-Proto header and builds its absolute links, including OAuth redirect URIs and Office add-in callbacks, with the correct https scheme instead of http.
• HTTP to HTTPS redirect. When HTTPS is on and port 80 is free, Reportworq also listens on port 80 and redirects those requests to HTTPS.

Scaling out with a load-balanced cluster#

When a single server cannot finish the job load inside its window, an on-premises instance can be scaled out into a load-balanced cluster. The nodes share one Repository, and the load balancer distributes whole jobs across them: each job runs atomically on a single node. A node that is not allowed to run a queued job re-queues it so another node picks it up. This spreads batch job execution, Excel reporting, and campaign-form load across the cluster.

Settings, Load Balancer is the screen that monitors and manages the nodes. It shows a grid with, per node, an enable switch, a max-jobs capacity spinner, and row actions Rename, Filter jobs, Restart, and Remove.

Load balancing is licensed as the Load Balancer node count, enabled per license on request; a count of 0 means it is off. A single-node install shows an empty node grid.

How a node joins the cluster#

A node joins through the setup wizard, not a button on the Load Balancer screen. On each new server:

1. Install Reportworq normally, see Install Reportworq.
2. Set the Reportworq 6 Bootstrap Service Log On As account to one that can reach the shared Repository and the source network folders.
3. In the setup wizard's Repository step, choose Add a load balancer to an existing web app and enter the UNC path to the shared Repository. (On a server whose Repository is already configured, reopen the wizard from Settings > Configuration > Web Server > Reconfigure and choose the same option.)
4. The node applies the choice, restarts into execution mode, and joins the cluster. No further node-side configuration is needed.

If a node does not join, the usual cause is that its Log On As account cannot reach the shared Repository UNC path.

Network prerequisites#

Two ports must be open in the firewall on the main server and on every load-balancer node:

Opening only the web port is the classic mistake. The cluster appears to connect, but its real-time coordination fails quietly because the Event Hub bus is blocked. Open both on every server.

The Repository must be a UNC network share reachable by every node, and any source report providers (especially network-folder providers) must be reachable by every node too. Finally, set Web App Host in the main server's Server configuration to a machine name, IP, or DNS name the nodes can resolve, before you start the load balancers. If it is left to coalesce to a bare machine name the nodes cannot resolve, they will not join.

Sizing per-node capacity and concurrency#

A load-balancer node, reached at its own address on port 8600, presents a reduced shell whose Execution category sets its own behavior: a Server Instance Name that identifies it in job screens, the Load Balancer monitor, and the node pivot on Settings ▸ Performance; an Enable Execution checkbox; and a Parallel Job Execution value from 0 to 128. These are the same three values as that node's row on the main server's Load Balancer grid, where they appear as the node name, the enable switch, and the max-jobs spinner, so you can edit them from either end.

Two controls share the name "Parallel Job Execution", and they are different settings.

Size them together. A node's max-jobs value should not exceed what its RAM can actually hold, since peak memory scales with the number of jobs in flight and the routing limit knows nothing about the machine's memory. See Server configuration for the concurrency settings.

Concentrating execution on dedicated nodes. A node's Parallel Job Execution accepts 0, and its Enable Execution checkbox can be cleared, so a node can stay registered in the cluster and take no work. That is how you drain a node before maintenance without removing it and having it re-register.

The main server's own Parallel Job Execution, on Settings ▸ Configuration ▸ Performance, accepts 1 to 50 and cannot be set to 0, so the main server always keeps some execution capacity of its own. To concentrate batch work on dedicated nodes, lower the main server's value and raise the nodes', rather than trying to zero the main server. Because interactive Excel add-in refresh is not distributed and runs on whichever node holds the analyst's session, leaving the main server a small amount of capacity is usually the split you want anyway.

Routing jobs to specific nodes with Filter jobs#

The per-node Filter jobs action opens the Filter Jobs dialog, where you decide which jobs a node is allowed to run. The dialog is a tri-state (include, exclude, or inherit) tree over the instance's workspaces, folders, and jobs, with two modes:

• Include all jobs and workspaces (the default), so the node runs everything.
• Include or exclude specified jobs and workspaces, so you can pin certain jobs to certain nodes.

Reportworq saves the filter on the node and enforces it when routing: for each queued job it checks the job, then walks up its parent folders, then its workspace, and re-queues any job the node is not allowed to run so another node picks it up. By default every node runs everything.

Reading the Load Balancer monitor#

• A node's Status reflects whether it made a successful job-dequeue attempt in the last two minutes.
• All servers in a cluster should run the same Reportworq version.
• Restart takes a minute or two to complete.
• Remove deletes a node entry, but a still-running server reappears, because nodes self-register autonomously. To retire a node for good, stop its service.

Notes and limits#

• Node management applies only to a real multi-node cluster. A single-node install shows the empty grid "No load balancer servers are registered."
• Load balancing requires a Load Balancer node count of 1 or more on your license; a count of 0 disables it. See Licensing and entitlements.
• Interactive Excel add-in refresh is not yet distributed across cluster nodes. An analyst's live refresh runs on whichever node holds their session, regardless of the load balancer's capacity settings. Distributing interactive refresh across nodes is planned for a later phase; today the cluster distributes batch job execution.

Going deeper. For the per-node install and service-account setup, see Install Reportworq. For the concurrency settings that pair with per-node capacity, see Server configuration. For sizing a cluster against a workload, and why job granularity decides whether extra nodes help, see Distribute the load.