DOCSEARCHbyAlgolia
Submit Docs

go-selfupdate

repository·master·Indexed 23 days ago

https://github.com/sanbornm/go-selfupdate

A library and CLI tool that enables Golang applications to perform self-updates. It supports small incremental updates using binary diffs via bsdiff, with a fallback to full gzipped binary updates. The package includes a selfupdate.Updater for background update checks and a CLI utility to generate update manifests and binary patches.

Tokens
1.7K
Snippets
4
Records
8
Agent score
33%

What's inside go-selfupdate

  1. Understand the Update Protocol

    master

    The update process follows an HTTP(s) protocol. The client first fetches a JSON manifest for a specific platform, then attempts to download a binary diff (patch) or falls back to a full gzipped binary.

    1. Fetch Manifest: GET <server>/<appname>/<os>-<arch>.json

    Response Format:

    {
	"Version": "2",
	"Sha256": "..."
}

    2. Fetch Patch (Optional): GET <diff-url>/<appname>/<current-version>/<target-version>/<os>-<arch>

    3. Fetch Full Binary (Fallback): GET <bin-url>/<appname>/<target-version>/<os>-<arch>.gz

    Required Files on Server:

    • <appname>/<os>-<arch>.json
    • <appname>/<latest>/<os>-<arch>.gz

  2. Install the go-selfupdate CLI and library

    master

    To use go-selfupdate, you need both the CLI tool for creating update patches and the library to integrate into your Go application.

    Install the CLI utility:

    go install github.com/sanbornm/go-selfupdate/cmd/go-selfupdate@latest

    Install the library in your project:

    go get -u github.com/sanbornm/go-selfupdate/...
    go install github.com/sanbornm/go-selfupdate/cmd/go-selfupdate@latest

  3. Restart your application after an update

    master

    Since go-selfupdate does not automatically restart your process, you should use the OnSuccessfulUpdate hook to trigger a restart. If your application is managed by a service manager like systemd or Docker, you can simply exit the process and let the manager restart it.

    Example: Exit to allow service manager to restart:

    u.OnSuccessfulUpdate = func() { os.Exit(0) }

    Example: Using a custom graceful restart function:

    u.OnSuccessfulUpdate = func() { gracefullyRestartMyApp() }
    u.OnSuccessfulUpdate = func() { os.Exit(0) }

  4. Configure the selfupdate.Updater

    master

    The Updater struct controls how updates are discovered and applied.

    FieldTypeDescription
    CurrentVersionstringCurrent running version. Use dev to disable updates.
    ApiURLstringBase URL for JSON manifest requests.
    CmdNamestringApp name appended to ApiURL.
    BinURLstringBase URL for full binary downloads.
    DiffURLstringBase URL for binary diff downloads.
    DirstringDirectory to store selfupdate state (e.g., cktime file).
    ForceCheckboolIf true, check for updates regardless of CheckTime.
    CheckTimeintTime in hours before next check.
    RandomizeTimeintTime in hours to randomize with CheckTime.
    RequesterRequesterOptional custom HTTP request handler.
    OnSuccessfulUpdatefunc()Optional hook to run after a successful update.

  5. Enable your App to Self Update

    master

    Integrate the selfupdate.Updater into your application to check for updates in the background. You must provide the current version of your app, the URLs for the API, binaries, and diffs, and the command name.

    Note: CmdName is appended to the ApiURL (e.g., http://apiurl/CmdName/).

    var updater = &selfupdate.Updater{
	CurrentVersion: version, // the current version of your app used to determine if an update is necessary
	// these endpoints can be the same if everything is hosted in the same place
	ApiURL:         "http://updates.yourdomain.com/", // endpoint to get update manifest
	BinURL:         "http://updates.yourdomain.com/", // endpoint to get full binaries
	DiffURL:         "http://updates.yourdomain.com/", // endpoint to get binary diff/patches
	Dir:            "update/",                        // directory relative to your app to store temporary state files related to go-selfupdate
	CmdName:        "myapp",                          // your app's name (must correspond to app name hosting the updates)
}

// go look for an update when your app starts up
go updater.BackgroundRun()
// your app continues to run...

  6. Create update patches and binaries with the CLI

    master

    Use the go-selfupdate CLI to generate the necessary files for your update server. By default, it creates a public folder in your project containing the manifest and binaries.

    Basic usage:

    go-selfupdate <path-to-your-app> <the-version>

    Example:

    go-selfupdate myapp 1.2

    Options:

    • -o: Specify a custom output directory.

    Cross-compilation requirements: If you are cross-compiling, provide a directory containing files named with the format $GOOS-$ARCH (e.g., windows-386, darwin-amd64, linux-arm).

    go-selfupdate path-to-your-app the-version

  7. Use the go-selfupdate CLI to create update manifests and binary diffs

    master

    The go-selfupdate CLI tool is used to generate update manifests (JSON files containing version and SHA256 info) and compressed binary patches (diffs) for your application. It supports both single-binary updates and batch processing of multiple binaries within a directory.

    Usage Modes

    1. Single platform update: Provide a path to a single binary and the new version. go-selfupdate <path_to_binary> <version>

    2. Cross platform / Batch update: Provide a directory containing multiple binaries. The tool will iterate through the directory and create updates for each file found. go-selfupdate <directory_path> <version>

    Workflow

    When you run the tool, it:

    1. Creates a JSON manifest for the target platform (e.g., linux-amd64.json) containing the new version and SHA256 hash.
    2. Compresses the new binary into a .gz file.
    3. Compares the new binary against existing versions in the output directory to generate a binary patch (diff) using binarydist.
    4. Organizes files into a versioned directory structure within the output directory.

  8. Configure go-selfupdate CLI flags

    master

    The go-selfupdate CLI accepts the following flags to control output and target platforms:

    • -o string: The output directory where update manifests, compressed binaries, and patches will be written. Defaults to public.
    • -platform string: The target platform identifier in the format OS-ARCH (e.g., linux-amd64, darwin-arm64).
      • If not provided, it defaults to the current running os/arch.
      • If the environment variables GOOS and GOARCH are set, it uses their combination as the default.

    Positional Arguments:

    1. appPath: Path to the binary or directory containing binaries.
    2. version: The new version string being released.