Skip to content
Docs

Auto Updater

The Packager includes support for auto updates for Rust and Node.js applications by providing APIs for your application to securely update itself by fetching new releases on a remote server, installing updates and restarting itself.

Signing Keys

To securely deliver updates, the Packager signs your application generating a signature that is verified by the updater. To generate a new keypair, use the CLI signer generate command:

Terminal window
# Cargo
cargo packager signer generate
# pnpm
pnpm packager signer generate
# yarn
yarn packager signer generate
# npm
npx packager signer generate

The command will prompt you for the keypair password. Do not lose that password, you will need to define it as the CARGO_PACKAGER_SIGN_PRIVATE_KEY_PASSWORD environment variable for the packager to sign your update packages.

After generating the keys, the CLI prints the private key and the public key. The private key must be defined as the CARGO_PACKAGER_SIGN_PRIVATE_KEY environment variable and must be treated as a secret, DO NOT share it, if it is compromised you will need to replace it immediately.

Along with the private key, the CLI also prints the public key that must be configured in the application to verify updates. The configuration object is documented later in this guide.

Rust

To configure the updater for your Rust application, add the cargo-packager-updater crate:

Terminal window
cargo add cargo-packager-updater

Create the updater configuration object, with the endpoint of the remote server hosting your app updates and your signing public key:

let config = cargo_packager_updater::Config {
  endpoints: vec!["http://myserver.com/updates"],
  pubkey: "<pubkey here>",
  ..Default::default()
};

Check out the complete configuration documentation.

Use the cargo_packager_updater::check_update API to fetch an update if there is one:

use cargo_packager_updater::{check_update, Config};


// insert your config object here
let config = Config {};


let current_version = env!("CARGO_PKG_VERSION");


// ideally you should handle the error here instead of using expect()
if let Some(update) = cargo_packager_updater::check_update(current_version, config).expect("failed to check for update") {
  update.download_and_install().expect("failed to download and install update");
} else {
  // there is no updates
}

NPM (Node.js)

To configure the updater for your Node.js application, install the @crabnebula/updater NPM with your preferred package manager:

Terminal window
# pnpm
pnpm add @crabnebula/updater
# yarn
yarn add @crabnebula/updater
# npm
npm i @crabnebula/updater

Create the updater configuration object, with the endpoint of the remote server hosting your app updates and your signing public key:

const config = {
  endpoints: ["http://myserver.com/updates"],
  pubkey: "<pubkey here>",
};

Check out the complete configuration documentation.

Use the checkUpdate API to fetch an update if there is one:

import { checkUpdate } from "@crabnebula/updater";


// insert your config object here
const config = { ... };


// here you must use the current app version
// usually an environment variable that is injected in your app
// (framework-specific), check your framework documentation for ideas on how to do this
const currentVersion = "0.1.0";


const update = await checkUpdate(currentVersion, config);


if (update !== null) {
  update.downloadAndInstall();
} else {
  // there is no updates
}

Configuration

The updater configuration object allows you to define a list of endpoints to connect,

Endpoints

The endpoints required configuration is a list of URLs that are used to check if a new update is available. The endpoints are queried in order until a valid response is found (subsequent URLs are used as fallback in case the first one cannot be reached).

Each endpoint can use the {{arch}}, {{target}} or {{current_version}} variables which are detected and replaced with the appropriate values before making a request to the endpoint:

  • {{current_version}}: The version of the app that is requesting the update.
  • {{target}}: The operating system name (one of linux, windows or macos).
  • {{arch}}: The architecture of the machine (one of x86_64, i686, aarch64 or armv7).

for example https://releases.myapp.com/{{target}}/{{arch}}/{{current_version}} can evaluate to https://releases.myapp.com/windows/x86_64/0.1.0.

Pubkey

The pubkey is a required configuration that defines the public key generated with the signer generate Packager CLI command. It is used to verify the authenticity of the update, ensuring it was built using your private key.

Windows

Under the windows object you can define the installerArgs, a list of string arguments that are given to the NSIS or WiX installers, and the installMode, an enum (one of basicUi, quiet and passive) which furthers configure the installer (defaults to passive, a mode that does not require the user to interact with the update installation).