Documentation

ORTUS CHEQIT Installation Guide

Updated 2026-05-01

Scope

This guide explains how to obtain, install, activate, update, and recover an ORTUS CHEQIT instance. It is intended for deployment engineers and customer administrators.

Obtain CHEQIT

CHEQIT release downloads are published as signed Linux release archives. During limited release, approved customers obtain the installer, checksum, and activation details from their customer account or assisted onboarding contact.

Before installing, confirm:

  • You have the correct customer licence or activation instructions.
  • You have the signed Linux release archive and release metadata.
  • You know whether the deployment is standalone, federated primary, federated leaf, or HA standby.
  • The host can reach required VMS/camera networks.
  • If online activation or online updates are required, the host can reach the configured ORTUS licensing/update endpoint.

Host Requirements

Recommended Linux deployment:

  • A dedicated Linux server or VM.
  • systemd.
  • Persistent storage for the application database, support bundles, update staging, and evidence/artifacts.
  • Network connectivity to VMS/camera sources.
  • HTTPS/TLS termination for production access.
  • SMTP configuration if email 2FA or email notifications will be used.

Sizing depends on camera count, connector type, detector cadence, alert volume, retention, and whether the instance is standalone, primary, leaf, or standby.

Starting points:

  • Pilot or small standalone: 4 vCPU, 8 GB RAM, 100 GB SSD.
  • Standard production site or leaf: 8 vCPU, 16 GB RAM, 250 GB SSD/NVMe.
  • Large site or primary: 16 vCPU, 32 GB RAM, 500 GB-1 TB NVMe.
  • Enterprise federated primary: 16-32 vCPU, 64 GB RAM, 1-2 TB NVMe, with leaves sized per site.
  • HA standby: match the active primary.

See the detailed sizing guide:

docs/release-v1/system-requirements.md

Install With systemd

The recommended Linux path is the one-shot systemd installer:

bash scripts/install-systemd.sh

The installer prepares:

  • /opt/ortus-cheqit for application runtime files.
  • /etc/ortus-cheqit/cheqit.env for protected environment configuration.
  • systemd service ortus-cheqit.service.
  • optional update-worker units when configured.
  • UI static files served by the API process.
  • initial admin credentials when generated.

Keep the generated admin password in a secure password manager. CHEQIT cannot display existing passwords later because passwords are not stored reversibly.

First Admin Credentials

CHEQIT should not be deployed with fixed vendor credentials. The installer defaults to a local admin account and generates a strong random password when one is not supplied. The password is printed once at the end of installation and only a hash is retained in the protected configuration/database.

Options:

sudo bash scripts/install-systemd.sh --admin-user admin
sudo bash scripts/install-systemd.sh --admin-user site-admin --admin-password '<strong password>'

For normal operation, create named administrator accounts after first sign-in and keep the built-in admin account as a protected break-glass path.

Install Paths, Port, And HTTPS

Default Linux paths:

  • Runtime files: /opt/ortus-cheqit.
  • Protected configuration: /etc/ortus-cheqit/cheqit.env.
  • Database, artifacts, updates, and runtime state: /var/lib/ortus-cheqit.

By default the installer selects the first free port in 8090..8100. Pin the port when the customer firewall, proxy, or monitoring expects a stable value:

sudo bash scripts/install-systemd.sh --port 8090

Recommended access patterns:

# Lab/private VPN direct HTTP.
sudo bash scripts/install-systemd.sh --bind-address 0.0.0.0 --port 8090

# Production behind an existing HTTPS reverse proxy/load balancer.
sudo bash scripts/install-systemd.sh \
  --https-mode external \
  --public-url https://cheqit.example.com \
  --bind-address 127.0.0.1 \
  --port 8090

# Production with a generated same-host Caddy HTTPS config.
sudo bash scripts/install-systemd.sh \
  --https-mode caddy \
  --public-url https://cheqit.example.com \
  --port 8090

CHEQIT does not terminate TLS inside the application process. Terminate HTTPS in a reverse proxy, load balancer, private overlay, or same-host Caddy service. For public hostnames, use ACME/Let's Encrypt where possible. For private or air-gapped deployments, use a customer private CA certificate and pass --tls-cert-file and --tls-key-file when generating the Caddy config.

See the detailed systemd runbook for host-level commands:

docs/deployment/systemd.md

First Sign-In

  1. Open the CHEQIT URL shown by the installer.
  2. Sign in with the local admin account or another configured account.
  3. If prompted, change the temporary password.
  4. Open the avatar menu to access Profile, Settings, and Sign out.

Before activation, the installed app is intentionally locked down. Users can sign in, but normal operational surfaces are unavailable until the instance has a valid licence.

Activation

Open Settings -> Licensing -> Activation.

Online Activation

Use online activation when the CHEQIT host can reach the ORTUS licensing service:

  1. Obtain an activation code from the customer portal or ORTUS.
  2. Enter the code in Settings -> Licensing -> Activation.
  3. Confirm the Current card shows an activated licence, activation date/time, plan, source, and entitlement details.
  4. Use the refresh icon in the Current card to refresh online status when needed.

Offline Activation

Use offline activation for air-gapped or restricted environments:

  1. On the CHEQIT host, open Settings -> Licensing -> Activation.
  2. Download the machine request .key file.
  3. Move that file to a machine with internet access.
  4. Sign in to the customer portal and upload the machine key.
  5. Complete purchase/approval if required.
  6. Download the signed offline activation .key.
  7. Move the activation key back to the CHEQIT host.
  8. Import it in Settings -> Licensing -> Activation.

The offline activation key is bound to the machine request. Use the correct key for the correct host.

Federated Activation

A leaf or standby can unlock through a licensed Enterprise primary:

  1. Configure the primary with an Enterprise licence that includes the required federation/HA entitlements and enough activations.
  2. Register the leaf or standby on the primary.
  3. On the leaf or standby, open Settings -> Federation/HA.
  4. Enter the primary URL and node token.
  5. Sync with the primary.
  6. Confirm the node unlocks through a delegated federation lease or reports a clear entitlement/capacity error.

Local licences take precedence on leaf instances. If a leaf has its own valid licence, it uses that first.

Camera Allocation

CHEQIT enforces licensed camera limits.

If the fleet has more cameras than the licence allows:

  • All cameras can remain visible in the dashboard when explicitly requested.
  • Cameras outside the allocation are marked unlicensed.
  • Unlicensed cameras are not analysed and cannot generate alerts.
  • Media, spot checks, recordings, and alert review are blocked for unlicensed cameras.
  • Adding new cameras while already over the licensed limit is blocked.

Administrators manage allocation in Settings -> Licensing -> Camera Limit.

Software Updates

Open Settings -> System.

The System tab shows:

  • installed build version,
  • update channel,
  • last update check,
  • latest trusted release,
  • whether restart is required,
  • update action when a signed trusted update is available.

To update:

  1. Click Check for updates.
  2. Review the update status.
  3. If an update is available and trusted, click Install update.
  4. Confirm the modal.
  5. CHEQIT queues the update for the root update worker.
  6. The worker verifies signatures/checksums, stages the release, backs up local state, restarts the service, checks health, and rolls back on failure.

Do not power off the host while an update is running.

Air-Gapped Updates

Air-gapped deployments should use signed offline release bundles. Import the bundle to the configured update-import location and run the documented update-worker procedure from the systemd runbook.

Federation And HA Installation Notes

For federated deployments:

  • Install and activate the primary first.
  • Configure leaves after the primary is healthy.
  • Leaves initiate network calls to the primary. The primary does not need inbound access to leaves.
  • For HA, configure the standby after the primary is licensed and stable.

For production HA, use a stable DNS name, VIP, or load balancer in front of the active primary when possible. CHEQIT also caches endpoint information and can recover browser sessions after failover when the app has been loaded before, but this is a fallback rather than a replacement for a stable front door.

See:

docs/federated-deployment-admin-guide.md

Email Configuration

Email is required for:

  • email-based 2FA,
  • alert notification email,
  • test notification email.

Configure SMTP in /etc/ortus-cheqit/cheqit.env, then restart the service:

  • CHEQIT_EMAIL_SMTP_HOST
  • CHEQIT_EMAIL_SMTP_PORT
  • CHEQIT_EMAIL_SMTP_MODE
  • CHEQIT_EMAIL_SMTP_USERNAME
  • CHEQIT_EMAIL_SMTP_PASSWORD
  • CHEQIT_AUTH_2FA_EMAIL_FROM or CHEQIT_NOTIFICATIONS_EMAIL_FROM

Recipient delivery is configured in the application per user. There is no global fixed alert-recipient override in the current release.

Admin Password Recovery

CHEQIT cannot reveal the current admin password. If access is lost, reset it.

If you can still sign in:

  1. Open Profile.
  2. Open Security.
  3. Change password.

If locked out, use the host-level reset procedure from the admin manual or systemd runbook.

Post-Install Checks

After installation and activation:

  1. Confirm /api/v1/health returns healthy.
  2. Confirm Settings -> Licensing shows an active licence.
  3. Confirm Settings -> System can check update status.
  4. Add and test the required connector.
  5. Confirm cameras appear in Nexus, Tree, and Map where applicable.
  6. Confirm camera allocation is correct.
  7. Configure notification recipients and send a test email if SMTP is enabled.
  8. Download a support bundle and verify it is redacted before sending it to ORTUS.

Uninstall / Cleanup

Use the systemd deployment runbook for safe service stop, backup, uninstall, and cleanup procedures. Always back up the database and configuration before removing an installed instance.