Install Reportworq#

Reportworq installs three ways, and which one you use is a consequence of the deployment you chose: Windows MSI, Linux tarball, or a Docker / Azure App Service container. Decide the deployment first, see Deployment topology, then follow the matching path below.

You run the installer, set the service account that jobs run under, then finish setup and activate the license in the browser. The steps below cover the install, the service account, product activation, and how to uninstall without stranding a license or losing reusable state.

Before you begin#

• A supported server, see System requirements.
• Administrator rights on the server.
• Your Reportworq license key.
• For online activation, outbound connectivity from the server to the licensing service. For an air-gapped server, use the manual activation path below.
• If jobs will read from or write to network shares, a domain account to run the service under, see Set the Bootstrap service account.

Choose how you install#

The three differ in more than mechanics, so do not carry assumptions across:

• The default port differs. Windows listens on 8600, Linux and containers on 8080. The Real-time Event Hub is always the web port plus one, and both must be open.
• HTTPS arrives differently. A fresh Windows install generates a self-signed certificate and serves HTTPS at first boot. Linux and containers do not: they serve HTTP until you configure a certificate or terminate TLS at a reverse proxy. HTTPS is mandatory for the Excel add-in and every Microsoft 365 feature, so this is not optional in practice.
• Updates differ. Windows and Linux update in product. A container is updated by swapping its image, see Update Reportworq.
• Hardware requirements do not differ. Use the same figures for all three, see System requirements.

Run the installer (Windows)#

1. Run the Reportworq installer (Reportworq_Installer.exe) on the server.
2. Accept the license agreement. Acceptance is mandatory, the installer will not continue without it.
3. Let the installer complete. It installs to the default path C:\Program Files\Reportworq 6 and registers and starts the Reportworq 6 Bootstrap Service, the Windows service that hosts the web application and the job runtime.

Reportworq 6 installs alongside an existing Reportworq 5 on the same server. The two use a different install folder, a different Windows service, and a different default port (8600 for v6, 8300 for v5), so they run side by side without conflict.

Install on Linux#

1. Prepare the host. A 64-bit Linux distribution with glibc and systemd (Debian/Ubuntu, RHEL/Rocky/Alma, or SUSE). You need root or sudo.
2. Install the native prerequisites, which the render stack depends on: fontconfig, libfontconfig1, libfreetype6, and libgomp1.
3. Install at least one font package, for example fonts-liberation or fonts-dejavu, or your corporate fonts. This is not optional: a clean Linux server has almost no fonts, and report output renders blank or boxed without them.
4. Unpack the tarball and run its install.sh. It creates a reportworq service user and registers the systemd unit. The application lands in /opt/reportworq, and the repository defaults to /var/lib/reportworq/repository.
5. Set configuration in /etc/reportworq/reportworq.env. The web port is RW_PORT, default 8080.
6. Open the firewall for the web port and the Event Hub port (RW_PORT plus one).
7. Start the service, then browse to the server on its port to reach the EULA and the first-run wizard, see First-run setup.

Logs are written to /var/log/reportworq. Because the Windows first-boot certificate generator does not apply here, configure TLS before you rely on the Excel add-in or any Microsoft 365 feature, see Deployment topology.

Install as a container#

There is nothing to install on a host. The image carries the application, and every setting arrives through the environment.

1. Provide durable storage for the repository. On Azure, that is an Azure Files mount. This mounted storage is the only state that survives the container, so it is the thing to back up.
2. Set the environment: the repository path, the web port (RW_PORT), HTTPS, and the instance identity. The image already runs under the immutable deployment profile, so it will not try to rewrite its own settings file.
3. Provide the certificate and any custom fonts through the repository, since the container filesystem is read only.
4. Start the container and browse to it to reach first-run setup.

Two consequences of the read-only image are worth knowing up front: the in-product updater is disabled (you update by swapping the image tag, see Update Reportworq), and a v5 repository import is not available on this path. Import a v5 repository with a Windows or Linux install first, then point the container at the resulting v6 repository.

The web tier runs as a single instance; scale throughput by adding worker nodes against the same repository. See Deployment topology.

Set the Bootstrap service account#

The Bootstrap service runs as Local System by default. Local System cannot reach network resources, so if any report source, output destination, or the Repository lives on a network share or UNC path, you must change the service to run as a domain account. The identity you choose here is the identity every job and every file access runs under.

1. Open services.msc on the server.
2. Open Reportworq 6 Bootstrap Service > Properties > Log On.
3. Select This account and enter the domain account and password. Windows automatically grants it the "Log on as a service" right.
4. Grant that account, at minimum:
   • read and write to the install folder (C:\Program Files\Reportworq 6 by default),
   • read and write to the Repository folder if you relocate it outside the install root,
   • read and write to every network output destination,
   • read to every network report-source location the reports are pulled from.
5. Restart the Bootstrap Service so the new identity takes effect.

Warning: a path the interactive administrator can see is irrelevant if the service account cannot reach it. Report sources and destinations must be reachable by the service account. Getting the service account wrong is the most common cause of "jobs cannot read or write."

Finish setup and activate the license#

1. On the server, browse to the first-run setup wizard. A fresh Windows install turns on HTTPS automatically at first boot, so use https://localhost:8600 (the auto-generated certificate is already trusted on the server itself).
2. Work through the wizard (Welcome, Repository, License, Users, Finish). This is where you apply the license key and create the first administrator, see First-run setup.
3. To activate online, enter the license key on the License step and activate. Each activation consumes one license seat against the licensing service.

Activate an air-gapped server (manual activation)#

If the server has no outbound connectivity to the licensing service, use the manual (offline) path:

1. On the License screen, choose Manual activation and enter the license key. Reportworq displays an Activation Request Code.
2. Take that request code (with the Reportworq Manual Activation form URL) to an internet-connected machine and paste it into the form. The form returns an Activation Response Code.
3. Paste the response code back on the Reportworq server and select Activate.

Tip: if IT policy blocks the in-app copy buttons, select the code text and use Ctrl+A then Ctrl+C to copy it.

Enable remote access#

Local access on the server works immediately. To let administrators and users reach the server from other machines, add an inbound firewall rule for TCP 8600 (and 8601 for the Event Hub), then test with https://<computername>:8600 (HTTPS is on by default on a fresh Windows install). Remote browsers trust the auto-generated certificate only after you distribute the trusted-root certificate to them, see Server configuration. See the network requirements in System requirements.

Uninstall#

Warning: release the license before you uninstall, or the seat stays consumed against the licensing service.

1. On the Settings > Configuration > License screen, reveal the key (the lock icon), record it, then select Release. This returns the seat.
2. Uninstall from Windows Add/Remove Programs > Uninstall.

Warning: some files remain after uninstall. If you intend to reinstall on the same server or migrate to a new one, do not delete them, they carry the Repository and configuration state you will reuse. See Migrate to a new server.

For Linux and container deployments there is nothing to uninstall through Windows: remove the tarball directory, or stop and delete the container. The Repository lives on its mounted storage and is unaffected.

Notes and limits#

• The MSI installer and the Windows service are Windows-only. Linux and container deployments use no installer and no service, see Deployment topology.
• You can change the web port later in Server configuration, which requires a restart. The default is 8600; a v5 upgrader that is not running side by side can change it back to 8300, see System requirements.

Going deeper. For the license model, entitlements, and how seats are counted, see Licensing and entitlements. To stay current on releases, see Update Reportworq.