itson

ItsOn

A CLI tool for configuration-driven management of long-running interactive applications.

[!WARNING]

Itson is under development. It should not be considered suitable for general use until a 1.0 release.

Overview

Itson helps you install, update, and run your bespoke privately-distributed applications in the context of long-running interactive installations or exhibits.

Itson does the following each time it runs:

• Read a configuration file and register any new configuration settings with the operating system.
  For now, this amounts to scheduling itson's own launch on future startups.

• Check for available updates to exhibit applications, prompting for credentials if necessary.
  For now, this is limited to checking for new releases on GitHub, and follows semver rules. The latest release is selected by default, or a semver-compatible version constraint or range may be specified in the application's configuration. GitHub credentials are requested interactively as needed and securely stored for subsequent use.

• Download and install updates if available.
  For now, this means standalone pre-built .exe binaries or .app bundles provided as assets attached to GitHub releases, or uv tool-installable Python application packages hosted in GitHub repositories.

• Upload log files.
  For now, this means syncing a folder of log files to an S3-compatible object storage bucket for each application. S3 credentials are requested interactively as needed and then securely stored in the system keychain for subsequent use.

• Start exhibit application(s) using the system-level services framework, and keep them running if they're closed or crash.
  For now, this leverages launchd on macOS.

Getting started

Dependencies

Itson is architected with future cross-platform support in mind, but currently only provides implementations for macOS.

Itson requires Node 22.12.0+.

Installing Python application packages requires uv.

Installation

npm install --global itson

Usage

Create a configuration file as described below, and then invoke itson to update the system to reflect your configuration, check for and install any application updates, and then immediately launch any specified applications.

This command runs automatically at system startup when runOnStartup: true in your configuration.

Configuration

Create an itson.config.js file in your home directory.

export default {
  applications: [
    {
      command: '/Applications/AllWork.app/Contents/MacOS/AllWork',
      name: 'AllWork',
      update: {
        artifactPattern: /^AllWork.+\.zip$/,
        destination: '/Applications/AllWork.app',
        owner: 'kitschpatrol',
        repo: 'allwork',
        type: 'github',
      },
    },
    {
      command: 'interpose',
      name: 'Interpose',
    },
  ],
  runOnStartup: true,
}

An optional update strategy may be specified.

Currently, only updates from GitHub releases containing Python application packages or attached binary artifacts are supported.

Private GitHub repositories are supported via personal access tokens bearing at least the contents:read and metadata:read permissions.

Commands

Command: itson

Run an itson command.

If no command is provided, itson launch is run by default.

Usage:

itson [command]

Command	Description
launch	Update, register, and start all managed applications. Applications will auto-restart if they crash. (Default command.)
start	Start all managed applications. Applications will auto-restart if they crash.
stop	Stop all managed applications.
update	Update all managed applications to the latest available versions.
register	Register itson with the system according to the config file. Optionally run this after changing state in the config file.
reset	Clear any credentials stored in the system keychain, and remove any registered services.

Option	Description	Type
--verbose	Run with verbose logging	boolean
--help -h	Show help	boolean
--version -v	Show version number	boolean

Background

Alternatives

Monitoring / scheduling

• AMPM
• PM2

Updates / deployment

Update functionality can be baked into applications (e.g. Squirrel, Sparkle, Electron autoUpdater, etc.), but these are geared toward end-user applications and generally display their prompts interactively — unworkable for an "always up" interactive exhibit application.

Homebrew or Scoop implement robust and readily-scriptable package management solutions, but none are (practically) cross-platform. Securing and managing private registries for one-off applications is a bit of a pain.

Docker and other containerization strategies can be appealing on the back-end. For highly interactive real-time graphical applications, containerization creates extra hoops to jump through to access specialized low-level hardware, GPUs, and audio devices.

Scope

Itson is responsible for the following:

• Updating exhibit application software non-interactively
• Securely storing credentials required for updates
• Ensuring that exhibit application software restarts automatically in the event of a crash
• Uploading log files to S3

Itson is currently not concerned with the following:

• Scheduling
• Automatic rollback

Development notes

Itson itself is not a long-running process. It runs once at startup, and then hands over responsibility for application monitoring to the operating system's native service-management facilities.

Native implementations are used wherever possible (e.g. launchd for process management, the system keychain for credential storage.)

Launchd

• svcinstall (cross-platform)
• npm-launchctl-helper
• launchd.info
• Agents: ~/Library/LaunchAgents/
• Logs: /tmp/

Keychain

• keytar-forked
• node-keytar

Maintainers

@kitschpatrol

Contributing

Issues and pull requests are welcome.

License

MIT © Eric Mika