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:

1. 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 and registering any scheduled tasks specified in the configuration.

2. 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.

3. 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.

4. 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.

5. 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

Updating

npm update --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',
    },
  ],
  tasks: [
    {
      arguments: ['Itson is on task!'],
      command: 'say',
      name: 'Say',
      schedule: '0 * * * *',
    },
  ],
  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.

Itson works offline, but certain operations (log uploading, application updates) will be skipped after a (generous) timeout. (Or, use the --offline flag to skip these operations immediately.)

"Applications" start whenever itson is run, and then run forever and restart automatically if they are closed or crash.

"Tasks" run once at the specified time and then exit.

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 and tasks to the latest available versions. | | upload-logs | Upload all application and task logs to the configured S3 bucket. | | 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. Overrides the config file. | boolean | | --offline | Skip operations that require internet access. Overrides the config file. | 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 on" 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
• Scheduling short-running tasks using cron syntax

Itson is currently not concerned with the following:

• Automatic rollback (Though manual rollback can be accomplished by pinning a specific version in the itson.config.js file.)
• Crash reporting (I'm handling this via log uploads and remote analysis.)

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.

Though the tool itself is written in TypeScript, the actual functionality is provided by platform-native implementations wherever possible. (E.g. launchd for process management, the system keychain for credential storage.)

Binary management

• mise
• ubi

Launchd

• svcinstall (cross-platform)
• npm-launchctl-helper
• launchd.info
• node-launchd.plist
• Agents: ~/Library/LaunchAgents/
• Logs: /tmp/
• Interesting precedent: node-mac, node-windows, node-linux.

Cron

• cronstrue
• cron to launchd python program

Keychain

• keytar-forked
• node-keytar

Maintainers

@kitschpatrol

Acknowledgments

Thanks to Philipp Kühn for demonstrating an approach to mapping cron syntax to the constraints of launchd's task scheduling system in his crontab-to-launchd project.

Contributing

Issues and pull requests are welcome.

License

MIT © Eric Mika