Skip to content

Windows Service Installation

Production Recommendation

Native Windows Service is the recommended deployment method for Windows production environments. Docker on Windows is a separate deployment type — see Docker Installation if you prefer containers.

Validation evidence

IMPLEMENTED = YES · AUTOMATED TESTED = YES · LIVE E2E VALIDATED = YES (Windows lab, August 2026).
Details: Windows Service E2E · Installer validation matrix · Test matrix.

Prerequisites

  • Windows Server 2016+ or Windows 10/11 (64-bit)
  • MongoDB 6.0+ accessible from this host
  • PowerShell 5.1+ (ships with Windows)
  • Administrator privileges
  • The application release archive (.zip)

MongoDB Is a Separate Service

The installer does not install or manage MongoDB. MongoDB must be installed and running before you install IQV Integration API. See your organization's database operations documentation.

Runtime Directory Layout

After installation the service uses these paths:

text C:\IQVizyon\IQVIntegrationAPI\ bin\ # Application binary config\ # Configuration .env # Environment file (you must create this) logs\ # Application logs backups\ # Pre-update backups deployment\ # Deployment metadata

Installation

1. Prepare the Environment File

The installer never auto-creates a .env file. You must create it manually from .env.example before installing:

powershell Copy-Item .\config\.env.example C:\IQVizyon\IQVIntegrationAPI\config\.env

Edit the file and set all required values — at minimum MONGODB_URI, AUTH_CLIENT_SECRET, AUTH_JWT_SECRET.

Secrets

Never log or share the contents of .env. Secrets are never written to application logs.

2. Run the Installer

Open an elevated PowerShell prompt and run:

powershell powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\install.ps1

The installer will:

  1. Create the directory structure under C:\IQVizyon\IQVIntegrationAPI\.
  2. Copy the binary to bin\.
  3. Register the IQVIntegrationAPI Windows Service.
  4. Start the service.
  5. Run health checks (/health/live and /health/ready).
  6. Report success only after both liveness and readiness probes pass.

3. Verify

powershell Get-Service IQVIntegrationAPI

The service should show Running status.

powershell Invoke-RestMethod http://localhost:8080/health/live Invoke-RestMethod http://localhost:8080/health/ready

Both endpoints must return HTTP 200 before the installation is considered successful.

Install Scenarios

Scenario Service Runtime Config behavior
Clean install Absent Absent Source .env → config\.env
Preserved-runtime reinstall Absent (e.g. after uninstall) Present Preserve existing config\.env
Service repair / re-run Present Present Preserve config; idempotent SCM repair

Default policy is preserve. Overwrite only with explicit -ReplaceRuntimeConfig.

Preserved Runtime Reinstall

Typical flow after uninstall.ps1 (runtime kept):

  1. Service / firewall removed; C:\IQVizyon\IQVIntegrationAPI\ retained (binary, config\.env, logs, backups, metadata).
  2. Re-run install.ps1 (e.g. -SkipGitPull -SkipPrerequisiteInstall).
  3. Installer detects preserved runtime, prints Runtime config preserved: ...\config\.env, updates binary, registers service once (CreateService with exe+argv; no redundant ImagePath UpdateConfig after create).
  4. Config SHA-256 before/after should match unless -ReplaceRuntimeConfig was set.

Install mutations after backup are transactional: on failure the installer recovers (remove partial service if it did not exist before; restore backup / prior service when applicable). MongoDB migrations are not reversed (Database rollback: NOT PERFORMED).

Lab-only failure injection: -TestFailAt AfterServiceCreate|LiveHealth|... (explicit parameter only).

Port Ownership Validation

Installers do not treat “port is listening” as an automatic failure.

Field Meaning
Port / Listening TCP listen on HTTP_PORT
PID / ProcessName / Executable Listener identity (informational)
OwningServiceName Windows service owning that PID (if any)
ExpectedServiceName IQVIntegrationAPI
OwnedByExpectedService TCP OwningProcess == Win32_Service.ProcessId for the expected service

Rules

  • Ownership is proven by SCM ProcessId match, never by process name alone.
  • ServiceRepair + listener owned by IQVIntegrationAPI → PASS (no -Force needed).
  • CleanInstall / PreservedRuntimeReinstall with any listener → FAIL exit 15 (including a manual iqv-integration-api.exe that is not the SCM service).
  • ServiceRepair with a foreign listener → FAIL exit 15.
  • Port conflict during preflight is mutation-free (no backup, no service stop).
  • After service stop, the installer waits for the previous service PID to release the port before binary swap.

Linux systemd equivalent: compare listener PID to systemctl show -p MainPID. Docker equivalent: accept only the managed Compose/API published port mapping; foreign containers/processes are conflicts.

Service management

Status

powershell powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\status.ps1

Update

powershell powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\update.ps1

The update script creates a backup under C:\IQVizyon\IQVIntegrationAPI\backups\ before applying changes. See Update and Rollback for the full update procedure.

Uninstall

powershell powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\service\uninstall.ps1

MongoDB Data

The uninstaller never deletes MongoDB data. Your database remains intact after service removal.

Binary Service Commands

The binary itself supports service lifecycle commands:

powershell .\iqv-integration-api.exe service install --env-file C:\IQVizyon\IQVIntegrationAPI\config\.env .\iqv-integration-api.exe service uninstall .\iqv-integration-api.exe service start .\iqv-integration-api.exe service stop .\iqv-integration-api.exe service restart .\iqv-integration-api.exe service status .\iqv-integration-api.exe service run --env-file C:\IQVizyon\IQVIntegrationAPI\config\.env

The --env-file flag tells the service where to load its environment configuration.

Firewall Configuration

Open the API port (default 8080) for inbound connections from your integration partners:

powershell New-NetFirewallRule -DisplayName "IQV Integration API" ` -Direction Inbound -Protocol TCP -LocalPort 8080 ` -Action Allow -Profile Domain,Private

Port Conflicts

If port 8080 is already in use, the service will fail to start. Change the port in your .env file or stop the conflicting process.

Logging

Application slog is written to process stdout. The service host does not redirect that stream into logs\. The Event Log source IQVIntegrationAPI is registered for SCM; the application does not write slog lines there.

Installer/update file log: C:\IQVizyon\IQVIntegrationAPI\logs\installer-update.log.

See Logging. Secrets, tokens, and credentials are never written to logs.

Exit Codes

Installer scripts use scripts/windows/service/Common.ps1 (0–17). The table on Windows Service E2E is the accurate mapping (EXIT_SUCCESS, EXIT_PORT_CONFLICT=15, …). Do not confuse those constants with generic “Mongo timeout = 5” labels.

Troubleshooting

DATABASE_UNAVAILABLE

The application cannot reach MongoDB. Verify:

  1. MongoDB service is running: Get-Service MongoDB or check MongoDB's own management tool.
  2. MONGODB_URI in .env is correct and reachable from this host.
  3. MongoDB authentication credentials are valid.
  4. Firewall allows outbound connections to the MongoDB port.

Port Conflict (Exit Code 6)

Another process is using the configured port. Find it:

powershell Get-NetTCPConnection -LocalPort 8080 | Select-Object OwningProcess Get-Process -Id <PID>

Migration Failure (Exit Code 14)

A database migration failed. Do not retry automatically. Inspect the migration logs, fix the issue, then retry or rollback. See Update and Rollback.

Dirty Repository (Exit Code 15)

The deployment directory contains unexpected modifications. The update script uses git pull --ff-only for source-based deployments and will refuse to proceed if the working directory has uncommitted changes. Never use git reset --hard — resolve the conflict manually.

Offline Installation

For air-gapped environments:

  1. Download the release archive on an internet-connected machine.
  2. Transfer the archive to the target host via secure media.
  3. Extract and run the install script as documented above.
  4. Ensure MongoDB is reachable from the target host.

Health Checks

Both liveness and readiness probes must pass before a deployment is considered successful:

Endpoint Purpose
GET /health/live Process is alive
GET /health/ready Process is alive and MongoDB is reachable

The installer and update scripts automatically verify both endpoints. Do not report success if either probe fails.