Server configuration#

Settings, Configuration is the administrative editor for how a Reportworq instance runs. It is a single screen with a seven-tab strip, reached from the Configuration card on the Settings landing. Each tab edits its own view of the settings store, and most changes take effect only after you select Save Changes. A few settings (the web server port, SSL, and the Repository path) also require a service Restart.

This page is a reference for every tab, the individual settings each one holds, and the three operational rules that cause the most trouble if you get them wrong: how peak memory scales with parallel execution, how to relocate the Repository safely, and the SSL self-signed certificate traps.

The header and the unsaved-changes guard#

The screen mounts on the Web Server tab and shows three header actions:

• Close returns to the Settings landing.
• Save Changes stays disabled until the active tab has unsaved changes.
• Restart restarts the Reportworq service. This is destructive to any in-flight work, use it deliberately.

Editing a field enables Save Changes and marks the tab with an unsaved-changes dot. If you switch away from a tab that has unsaved edits, or close the screen, Reportworq prompts you to discard those edits. Switching tabs or closing re-reads the store, so unsaved edits are discarded rather than kept. Save what you change before you move on.

Note: administrator-level settings live here. Authentication is not on this screen, it moved to the Integrations hub. MCP and AI-agent access also live in the Integrations hub now, under AI Agent Access, not on the API tab. See The integrations hub.

The seven tabs#

Individual settings reference#

Defaults below are the shipped defaults. Settings marked Restart take effect only after a service restart.

Custom fonts#

A report is rendered with the fonts its workbook uses. When Reportworq runs on Linux, this matters more than it does on Windows: a new Linux server has almost no fonts installed, so any font your reports use that is not present is silently replaced with a substitute, and numbers, tables and cell-range images can come out squished, misaligned or in the wrong font.

This is common because of how teams work: the source reports are usually authored on Windows with Windows fonts (Calibri, Cambria, Arial, Trebuchet MS, a corporate brand font, and so on), the finished output is opened on Windows too, but the report itself is generated on the Linux server in between. For the output to match, the Linux server needs the same fonts the source reports use.

We strongly recommend uploading the fonts your reports use through Custom Fonts. Under Settings > Configuration > Performance, turn on Use custom fonts from a provider folder, then pick the workspace folder that holds your uploaded .ttf / .otf / .ttc files. Reportworq materializes those fonts on every runner and renders with them. Upload the exact fonts your source reports and outputs use - this is the reliable way to get Linux-generated output that looks identical to Windows.

• Custom Fonts Folder (legacy) - a literal on-disk folder path scanned for fonts. Still honored for classic Windows and tarball installs, but for containers and general use prefer the workspace-folder option above, which keeps the fonts with the instance and survives a host rebuild.
• For the full picture, and the PNG alternative for fonts you cannot install, see the Troubleshooting index.

Size parallel execution against RAM, not just CPU#

Two Performance settings set concurrency: Parallel Job Execution (top-level jobs at once) and Tasks per Job (variations within a job). The theoretical maximum concurrency is their product, for example 5 by 5 is 25 concurrent tasks.

Two different controls are called "Parallel Job Execution". This one, on Settings ▸ Configuration ▸ Performance ▸ Execution, is this server's own job concurrency and accepts 1 to 50. A load-balancer node's own settings screen, and the max-jobs spinner on the main server's Load Balancer grid, carry a control of the same name that is that node's routing capacity and accepts 0 to 128. They are stored separately and do different work, so check which screen you are on before changing one.

The rule that matters for capacity planning: peak memory scales with the job count. If five jobs run in parallel and each needs roughly 2 GB, the instance needs about 10 GB free at the peak. Size the Performance tab against the RAM the server actually has, not just its CPU count. An under-sized box will run out of memory under load rather than simply running slowly. See System requirements for the baseline figures.

Capacity with a load balancer#

In a load-balanced deployment the concurrency limits apply per server. Each server runs jobs up to its own Parallel Job Execution and Tasks per Job, so the total capacity of the instance is the per-node figure multiplied by the number of nodes. Size the limits against the RAM and CPU of a single node, then scale total throughput by adding nodes rather than by raising the limits beyond what one node can hold. See Deployment topology for load-balancer setup.

Relocate the Repository safely#

The Repository Path is the root of the content and configuration store, so changing it affects every user. Never move the folder while the service is running, that risks corrupting the store the same way a live migration does.

Relocate it with this sequence instead:

1. On the Web Server tab, under Backup, create a backup.
2. Change the Repository Path to the new location.
3. Restart the service.
4. Restore the backup into the new location.

This gives you a clean, restorable copy and never leaves the store half-moved. The same backup zip is restorable to any Reportworq instance, so it also covers migration to a new server, see Migrate to a new server.

On a load-balanced deployment the Repository must be a UNC network share, for example \\fileserver\reportworq, reachable by every node rather than a local disk path, because all nodes read and write the one shared store. Set the path to the share before starting the additional nodes.

SSL and self-signed certificates#

HTTPS is mandatory for the Excel add-in and for every Microsoft 365 feature (Entra sign-in, SharePoint, Microsoft 365 email, and Graph). On a fresh Windows on-premises install, Reportworq turns on HTTPS for you at first boot with an auto-trusted self-signed certificate, so the first browse to the server is https:// with no manual step (see Deployment topology). To turn on HTTPS yourself, or to replace the certificate, use the certificate actions on the Web Server tab. A self-signed certificate is enough to unblock the add-in and Microsoft 365, but replace it with a certificate from a trusted authority as soon as you can.

This section is about the certificate Reportworq's own web server presents to browsers. For an outbound SMTP server whose certificate does not validate, see Do not validate the mail server's TLS certificate on the Email tab, above.

Replace or regenerate the self-signed certificate#

Reportworq already creates and installs a self-signed certificate for you on a fresh install, so you use this action to replace or regenerate it, for example to cover additional host names or after a server rename. The Create Self Signed Certificate action generates a new certificate and turns on HTTPS if it is off. It prompts for one field:

• Certificate Names. Enter the names the certificate should cover, separated by commas, for example localhost, <machine>, <machine>.<domain>. On a domain-joined server the field is pre-filled with the machine name and its fully qualified domain name. Include every name users will use to reach the server: a name the certificate does not cover produces a certificate warning in the browser.

On create, Reportworq installs the certificate into the server's Trusted Root store, so the server itself trusts it with no manual import. The certificate password is generated and held internally, there is nothing to copy down and nothing is shown.

Let client machines trust the certificate#

A self-signed certificate is trusted on the server automatically, but other machines' browsers do not trust it until you give them the public certificate.

1. On the Web Server tab, select Download Trusted Root Cert (for client machines) to export the public certificate file, Reportworq-TrustedRoot.cer. This action is available once a self-signed certificate exists.
2. Distribute that .cer file to each end-user workstation and import it into the machine's Trusted Root certification authorities, for example by Group Policy across the domain.

A certificate from a trusted public authority needs none of this client-side distribution, which is why it is recommended for anything beyond a quick test.

Install a certificate from a trusted authority#

A certificate from a public or internal authority is uploaded into the Repository, not typed as a path.

1. On the Web Server tab, at SSL Certificate, select Upload Certificate and choose your .pfx (or .p12) file.
2. If the file is password-protected, select Set Certificate Password and enter it.
3. Restart the service, then browse the server over https:// to confirm.

Once a certificate is installed, the SSL Certificate row names it and when it expires, so you can check what the instance is actually serving without going to the file system. Where a public .cer companion exists, that name is also the link that downloads it for client machines.

Certificate notes#

• The certificate names must match the URL users type. Do not rely on localhost for remote users. If the certificate does not name the host users reach the server by, they get certificate warnings. This is the same rule as the Microsoft 365 advertised-address requirement, and the multi-name Certificate Names field lets one certificate cover every name in use.
• There is no certificate-path field to fill in. Earlier releases had a free-text path box, which was the most common cause of "HTTPS will not start" and could not work at all on a container deployment. Upload the certificate instead, and Reportworq stores it in the Repository, where every node and every restart finds it.
• Behind a TLS-terminating reverse proxy there is no certificate to configure. When the instance is served over HTTPS by a proxy, the SSL switch is locked on and the row says so. Do not try to bind a certificate as well. Also set External URL (above) to the public address recipients use, so the links Reportworq emails resolve through the proxy instead of pointing at the instance's internal host and port.

To confirm a certificate's names against the URL you access, dump it on the server with certutil -dump "cert.pfx".

Common tasks#

• Configure outbound email. On the Email tab, select your provider, enter the mailbox and Default From address, save, then send a test email to confirm delivery before you schedule any distributions.
• Tune for month-end. Before the close, raise Parallel Job Execution and Tasks per Job on the Performance tab so a large batch runs within the window, sized against available RAM per the rule above.
• Set audit retention for compliance. On the Logging tab, enable audit logging and set the retention to match your evidence-retention policy.
• Provision a new workspace. Workspaces are not configured on this screen. Create one and grant access to it on Settings ▸ Security ▸ Workspaces, see Workspaces.
• Enable the Local API. On the Reportworq API tab, select Add API key, pick the workspace it grants access to, enable the key with its switch, and save. Keys are global, so you manage them all here without switching workspaces.

Notes and limits#

• The Authentication settings are not on this screen. Configure them in The integrations hub.
• The License tab does not participate in the save flow. Its actions take effect immediately and activate against the external license service.
• The Data Collection tab is inert without the licensed Contribution capability (Data Collection is part of Contribution, not a separate line).
• The port, SSL, and Repository Path settings can break the instance if set carelessly. Change them deliberately and restart as prompted.

Going deeper. For a one-click inventory of every job, report, parameter, burst set, schedule, and contact in the instance, generate the Repository metadata report from Settings, Auditing, System Log.