Skip to content

Install on Windows Server

Applies to: All subscriptions

Purpose

Prepare the application host and get the Complifly services running under a supervisor that survives crashes and reboots. Windows Server is the reference platform; a Linux host follows the same sequence with the platform's own equivalents.

Audience

System administrators and implementation engineers with administrative access to the host.

Prerequisites

  • Technical Prerequisites complete
  • Administrative access to the host
  • Application files or repository access
  • Outbound access for package installation, including through any proxy

Steps

1. Confirm the host

Check Why
Operating system patched and supported Baseline
Time synchronisation working, drift under one second Token validation and statutory windows both depend on correct time
Sufficient CPU, memory and disk per the sizing tier See Sizing and Capacity
The host reaches the database, the queue and the internet Test from this host, not from a workstation

2. Install the runtime

Install Node.js at the version Complifly supports for your release.

Verify: The supported Node.js major version range is not stated in this portal. Confirm before installing — an unsupported runtime produces subtle failures under load rather than a clear refusal. Recorded as assumption B1 in the Assumptions Register.

Confirm the runtime and its package manager are both on the system path for the account the service will run under, not only for your interactive session. This distinction causes a service that starts by hand and fails as a service.

3. Install the PDF rendering dependencies

Document rendering runs a headless browser. On a minimal Windows Server image the libraries it needs are frequently absent, and their absence produces a system that works perfectly until someone prints.

Install them now, and verify with a test render later rather than discovering it during user acceptance testing.

4. Deploy the application files

Place the application in a dedicated directory — for example D:\complifly — containing the backend service and the front-end source or build output.

Requirement Detail
The service account can read and execute the application directory —
The service account can write to the log and upload directories Only those; not the whole tree
Ordinary users have no access Configuration files hold credentials
The path contains no spaces where avoidable Avoids quoting defects in supervisor definitions

5. Install dependencies

Install production dependencies for the backend service from within its directory. If the host uses a proxy, configure the package manager's proxy settings first — otherwise installation fails in a way that looks like a corrupt package source.

6. Write the configuration

Create the environment configuration file before the first start. The service reads it at startup and will not start meaningfully without it. See Environment Variables for every setting.

Two points that cause real incidents:

  • Set the port explicitly. The reference deployment uses 5003. A built-in fallback exists but should never be relied on; if the proxy and the service disagree about the port, the symptom is an HTTP 502 with no error in the application log.
  • Restrict the file's permissions. It contains database and provider credentials. It should be readable by the service account and administrators, and by nobody else.

7. Register the services under a supervisor

Two processes run: the API and the background worker. Both need a supervisor providing four properties:

Property Why
Restart on crash An unsupervised crash is an outage until someone notices
Start on boot A reboot must not require a person
Log capture and rotation Logs are the primary diagnostic tool, and unrotated logs fill disks
Clean stop Required for maintenance and upgrades

A process manager such as PM2 is used in reference deployments; a Windows service wrapper or a container orchestrator is equally acceptable. What matters is that all four properties hold and that the configuration is saved so it survives a reboot — a supervisor configured but not persisted is the classic cause of "it came back without the application" after a patch weekend.

Run exactly one worker instance across the whole deployment.

Verify: Whether concurrent workers are supported against one database is unconfirmed. Until Complifly states otherwise, one worker. Recorded as assumption C4.

8. Start and watch the first startup

Start the API and read the startup log to its end rather than checking only that the process is alive.

Log outcome Meaning
Database connection established, routes registered, listening Success
Stops naming a database object and a migration Working as intended. Apply the named migration — see Migrations
Stops on a database connection error Credentials, network path, or encryption settings
Starts but the port is already in use Another process holds the port; resolve before continuing

Validation

Check Method Pass condition
Runtime available to the service account Query the runtime version as that account Version returned, and it matches the supported range
API listening Request the health endpoint on the host itself HTTP 200 with a success body
API listening on the expected port Inspect listening ports The configured port, not the fallback
Startup log clean Read the log from the beginning of the startup No missing-object message; database connection established
Worker running Inspect the supervisor's process list Exactly one worker, in a running state
Survives restart Restart the host Both processes return without intervention
Log rotation configured Inspect the supervisor's log settings Rotation and retention set, not defaults left unexamined
Rendering dependencies present Trigger a test document render A PDF is produced. This is the check most often skipped, and it is the one that fails in front of a user
Configuration file protected Inspect its permissions Readable only by the service account and administrators
Outbound reachable Make a test call to the provider from this host Succeeds, including through any proxy

Troubleshooting

Symptom Cause Action
Service starts by hand but fails as a service Runtime not on the service account's path, or the account lacks directory rights Compare the environment of the service account with your own; fix the path and permissions
Application refuses to start, naming a database object Migration not applied Run the named migration and restart
Application refuses to start, database connection error Credentials, network path, or encryption mismatch Test the connection from this host with the exact settings the service uses
Port already in use Another process holds it, or a previous instance did not stop Identify the holder and stop it; do not silently change the port without updating the proxy
HTTP 502 from the proxy Proxy and service disagree about the port Align them. The application log will be silent about this
Dependency installation fails Proxy not configured for the package manager Configure the proxy, then retry
Printing fails, everything else works Headless-browser system libraries absent Install them on the host
Application does not return after a reboot Supervisor configuration not persisted Save the supervisor's process list so it is restored at boot, then test with a real reboot
Disk fills with log files Rotation not configured Configure rotation and retention
Two workers found running A second instance started during testing and was never stopped Reduce to one; duplicate background processing is a real risk