Skip to content

Provisioning

Jump to bottom
Tres Finocchiaro edited this page Aug 12, 2024 · 12 revisions

Compatibility

  • ✅ 2.2 | ✅ 2.1 | ✅ 2.0 | ⛔ 1.9 | ...

Objective

Since 2.2.4

Provide custom deployment options with QZ Tray

Quick Start

  1. Prepare environment for compiling
  2. Prepare provision.json file 
    [
   {
      "description": "Configure log file size",
      "type": "property",
      "data": "log.size=2097152"
   }
]
  3. Invoke ant with the provision file: 
    ant -Dprovision.file=provision.json nsis
  4. You now have a customized installer.

Provision Types

Cert | Property | Preference | Script | Software | Remover

Cert

Certificates are installed during the "phase": "startup" and write an entry to allowed.dat (e.g. %APPDATA%\qz) to avoid clicking "Remember this decision".

[
   {
      "description": "Trusts a certificate",
      "type": "cert",
      "data": "digital-certificate.txt"
   }
]

Property

Properties are installed during "phase": "certgen"‡ (post-install) and writes a properties entry to qz-tray.properties located in the installation directory. (e.g. %PROGRAMFILES%\QZ Tray)

[
   {
      "description": "Disable logs",
      "type": "property",
      "data": "log.disable=true"
   }
]
  • ‡ websocket.secure.ports and websocket.insecure.ports are an exception and must also be provided during "phase": "install" for Windows installers to set firewall rules.

Preference

Properties are installed during "phase": "startup" and write a properties entry to prefs.properties located in the user data directory (e.g. %APPDATA%\qz)

[
   {
      "description": "Show all notifications",
      "type": "preference",
      "data": "tray.notifications=true"
   }
]

Script

Script are run during "phase": "install" or "phase": "startup" and allow granular customizations. The script will be automatically copied into the installer.

  • data Must point to a valid script file and may be relative or absolute in respect to the location of provision.json.
  • os is recommended and never inferred.
  • The script may reference custom environment variables provided by the installer.
[
   {
      "description": "Python script",
      "os": "linux|mac",
      "type": "script",
      "data": "my_script.py"
   }
]

Script Variables

Name Example Name Example
APP_TITLE QZ Tray APP_VENDOR_ABBREV qz
APP_ABBREV qz-tray APP_VENDOR QZ Industries, LLC
APP_VERSION 2.2.4 APP_SHARED_DIR C:\ProgramData\qz
APP_OS windows APP_DIR C:\Program Files\QZ Tray
APP_ARCH x86_64 APP_USER_DIR C:\Users\USERNAME\AppData\Roaming\qz 
#!/usr/bin/env python3

import os

title=os.getenv('APP_TITLE')
version=os.getenv('APP_VERSION')

def notify(title, message):
  os.system(f"notify-send '{title}' '{message}'")

notify(title, "Hello from {} {}".format(title, version))

Software

Software is run during "phase": "install" and will execute with the provided deployment arguments.

  • os optional but will be assumed based on file extension
  • arch is optional but strongly recommended
  • args will automatically be split up on whitespace for convenience
    • ... if whitespace is needed, use "arg1": "first arg", "arg2": "second arg"
Extension Platform Supported
.exe, .msi Windows ✅
.pkg macOS ✅
.dmg macOS ⚠️
.run Linux ✅ 
[
   {
      "description": "Install Notepad++",
      "type": "software",
      "os": "windows",
      "arch": "x86_64",
      "data": "npp.8.5.8.Installer.x64.exe",
      "args": "/S"
   }
]

Remover

Remover is a task to uninstall other QZ Tray installations, which is especially helpful for Company Branded builds to remove known-conflicting installs.

  • data may be qz, or the application identifiers from the Company Branded portal.
    • Example: "data": "qz" Shorthand for QZ branded installers)
    • Example: "data": "Cherry Connect,cc-util,cc" Long format, required for Company Branded builds.
[
   {
      "description": "Remove QZ Tray",
      "type": "remover",
      "data": "QZ Tray,qz-tray,qz",
   }
]

Phases

Phase Description
"phase": "install" Runs as a privileged account during QZ Tray installation, but before QZ Tray has been fully deployed to the system.
"phase": "certgen" Runs as a privileged account during QZ Tray installation, but after QZ Tray has been fully deployed to the system.
"phase": "startup" Runs as user account during the startup of QZ Tray.
"phase": "uninstall" Runs as as a privileged account during uninstallation of QZ Tray.

Arch

Arch will designate which architecture to perform the step.

  • If not provided, arch will default to "arch": "*" and run on all systems.
  • Multiple values may be provided: "arch": "aarch64|riscv64"
Arch Description Supported
"arch": "x86_64" Intel 64-bit systems ✅
"arch": "aarch64" Apple Silicon or ARM64 systems ✅
"arch": "riscv64" RISC-V 64-bit systems ✅
"arch": "arm" ARM 32-bit systems ⚠️
"arch": "x86" Intel 32-bit systems ⚠️

OS

OS will designate which platform to perform the step.

  • If not provided, os will default to "os": "*" and run on all systems
    • Except software installers, which will try to choose a sane value.
  • Multiple values may be provided: "os": "mac|linux"
OS Description Supported
"os": "windows" Windows Operating System ✅
"os": "mac" macOS Operating System ✅
"os": "linux" Linux Operating System ✅
Clone this wiki locally