Skip to content

Installation Guide

Applies to: All subscriptions

Purpose

Take a prepared environment to a verified Complifly instance. The emphasis is on verified: a system whose services have started is not the same as a system that works, and several of Complifly's failure modes are invisible until a user tries something specific.

Audience

System administrators and implementation engineers with server and database access.

Prerequisites

Do not begin until the prerequisites are genuinely complete. An installation started on an unprepared environment does not fail cleanly — it half-succeeds, and the residue is harder to diagnose than a fresh start.

Steps

Follow in this order. Each step depends on the one before.

# Step Page
1 Prepare the host, install the runtime, deploy the application files Install on Windows Server
2 Create the database, the login and the connection Database Setup
3 Apply the schema and verify it landed completely Migrations
4 Configure the application Configuration Guide
5 Build and publish the web front end Front-end Deployment
6 Put the reverse proxy and TLS in front Reverse Proxy and TLS
7 Prove the installation works Post-Installation Verification

Two properties that shape the whole process

The application refuses to start against a database it cannot use. At startup it checks a manifest of required database objects and, if one is missing, stops and names the migration that creates it. This is deliberate. The alternative — starting, reporting healthy, and failing when a user presses a button hours later — is how this behaviour came to exist. A refusal to start is therefore information, not a fault.

Silent failures are the norm, not the exception. Three examples you will meet during installation:

Silent failure What you see What is actually wrong
Missing tenant scope in a query or script Zero rows, success reported Row-Level Security filtered everything
Queue unreachable while queue-backed jobs are enabled Application entirely healthy Jobs enqueue and are never consumed
Missing headless-browser system libraries Everything works until someone prints PDF rendering cannot launch

Every step's Validation section is written to catch failures of this kind. Do not substitute "no errors appeared" for the checks given.

Order dependencies you cannot rearrange

This Must come before Because
Database created Migrations There is nothing to migrate into
Migrations applied First application start The application refuses to start otherwise
Configuration written First application start It reads configuration at startup
Front end built Proxy configuration The proxy serves the built assets
Certificates issued Proxy configuration The proxy will not start without them
GSP credentials configured Any government operation Nothing reaches NIC until they are set

Validation

The installation is complete when every check in Post-Installation Verification passes. Summarised:

Area Proof
Application Health endpoint responds through the proxy
Schema No missing-object message at startup, and the object manifest verifies
Isolation Security policies exist and are enforced, tested with two identities
Background work A submitted job runs to completion
Government connectivity The provider connection test succeeds
Mail A test message is delivered to a real mailbox
Rendering A test document prints with a scannable QR code
End to end One document travels from ingest to IRN to print

The last row is the only one that proves the installation as a whole. Everything above it can pass while the system is still unable to process a document.

Troubleshooting

Symptom Cause Action
Application will not start, naming a database object A migration has not been applied Run the named migration, then restart. See Migrations
Application will not start, no schema message Database unreachable or credentials wrong Test the connection from the application host using the application's own credentials
Proxy returns HTTP 502 The proxy cannot reach the API Confirm the API is listening on the expected port and the proxy's target matches
Sign-in page loads, authentication fails Token signing configuration missing or inconsistent See User Authentication
Everything works except uploads Worker not running, or the queue unreachable Check both. Restarting the API will not help
Everything works except government operations Provider credentials or network path Run the provider connection test. See GSP Configuration
Printing fails, everything else fine Headless-browser libraries absent on the host Install them; this is an operating-system dependency
Application works locally but not through the proxy Proxy routing or origin configuration See Reverse Proxy and TLS