Skip to content

Installation

IQV Platform installs with a single command. There are no manual steps such as npm install, npm run build, docker compose, creating services or configuring Nginx — the installation script does all of it.

Canonical entry points:

Operating system Script
Windows scripts\windows\install.ps1
Linux scripts/linux/install.sh

Commands

# Auto (mode is selected automatically)
powershell -ExecutionPolicy Bypass -File .\scripts\windows\install.ps1

# Docker
powershell -ExecutionPolicy Bypass -File .\scripts\windows\install.ps1 -Mode docker

# Native (without Docker)
powershell -ExecutionPolicy Bypass -File .\scripts\windows\install.ps1 -Mode native

chmod +x scripts/linux/*.sh

# Auto (mode is selected automatically)
sudo ./scripts/linux/install.sh

# Docker
sudo ./scripts/linux/install.sh --mode docker

# Native (without Docker)
sudo ./scripts/linux/install.sh --mode native

Interface after installation: http://localhost:5173/

Mode selection

If -Mode / --mode is not supplied, the mode is determined in the following order and the selected mode is printed to the screen:

  1. The recorded mode of the previous installation (installed-version state file),
  2. If there is no record: docker when the Docker daemon is running, otherwise native.

There is no silent fallback to the wrong mode; if a prerequisite is not met, the script stops with a single, explicit error message.

Prerequisites

Component Docker mode Native mode
Node.js 22 (dashboard engines: >=22 <23) — Required
Docker Engine + Compose v2 Required —
Nginx — Required (Linux native)
External MongoDB / MinIO / SMTP Required Required

The script detects a missing prerequisite itself and states what needs to be done in a single line; it never leaves a half-finished installation behind.

What the installation does

  1. Computes the repository root from the script's own location (it does not rely on the cwd).
  2. Validates prerequisites and port conflicts (5173, 3001).
  3. Creates backend/.env from .env.example if it is missing; it never overwrites an existing .env, never generates secret values, and reports missing keys.
  4. Verifies that the required environment variables are populated and are not placeholders.
  5. Installs dependencies and produces production builds for the frontend and the backend.
  6. In Docker mode it brings up the compose stack (-p iqv-platform); in native mode it installs the service/task definitions (systemd + Nginx / Scheduled Task).
  7. Performs a real healthcheck: backend /health and frontend HTTP 200.
  8. It does not print INSTALL SUCCESS until health has been verified.

Options

Option Description
-Mode / --mode docker | native (auto when omitted)
-Force / --force Repair/reinstall when already installed
-DryRun / --dry-run Lists what would be done without changing anything
-Yes / --yes Non-interactive (CI/automation)

Exit codes

Code Meaning
0 Success
2 Invalid usage/parameter
3 Missing or incompatible prerequisite
4 Port conflict
5 Git error
6 Dependency/build error
7 Healthcheck failed
8 Installation state (already installed, etc.)

Idempotency

Running the installation a second time does not break the system: if it is already installed, it reports the state and suggests --force. A port held by the platform's own container is not counted as a conflict.