mouuff / go-rocket-update

Easy to use and modular library to make self updating golang programs

go-rocket-update: Build self-updating Go programs

Enable your Golang applications to easily and safely to self update.

Here is the list of projects using this package.

It provides the flexibility to implement different updating user experiences like auto-updating, or manual user-initiated updates, and updates from different sources.

The gopher in this image was created by Takuya Ueda, licensed under Creative Commons 3.0 Attributions license.

Features

• Flexible way to provide updates (ex: using Github or Gitlab!)
• Cross platform support (Mac, Linux, Arm, and Windows)
• RSA signature verification
• Tooling to generate and verify signatures
• Background update
• Rollback feature

QuickStart

Install library

go get -u github.com/mouuff/go-rocket-update/...

Enable your App to Self Update

Here is an example using Github releases:

u := &updater.Updater{
	Provider: &provider.Github{
		RepositoryURL: "github.com/mouuff/go-rocket-update-example",
		ArchiveName:   fmt.Sprintf("binaries_%s.zip", runtime.GOOS),
	},
	ExecutableName: fmt.Sprintf("go-rocket-update-example_%s_%s", runtime.GOOS, runtime.GOARCH),
	Version:        "v0.0.1",
}

if _, err := u.Update(); err != nil {
	log.Println(err)
}

For more examples, please take a look at some code samples and this example project.

Push an update

The updater uses a Provider as an input source for updates. It provides files and version for the updater.

Here is few examples of providers:

• provider.Github: It will check for the latest release on Github with a specific archive name (zip or tar.gz)
• provider.Gitlab: It will check for the latest release on Gitlab with a specific archive name (zip or tar.gz)
• provider.Local: It will use a local folder, version will be defined in the VERSION file (can be used for testing, or in a company with a shared folder for example)
• provider.Zip: It will use a zip file. The version is defined by the file name (Example: binaries-v1.0.0.tar.gz). Use GlobNewestFile to find the right file.
• provider.Gzip: Same as provider.Zip but with a tar.gz file.

The updater will list the files and retrieve them the same way for all the providers:

The directory should have files containing ExecutableName.

Example directory content with ExecutableName: fmt.Sprintf("test_%s_%s", runtime.GOOS, runtime.GOARCH):

test_windows_amd64.exe
test_darwin_amd64
test_linux_arm

We recommend using goxc for compiling your Go application for multiple platforms.

Important notes

• To update the binary, you need to have the right permissions for the folder where it is installed. For example, if the binary is in a folder like "Program Files", the process will need to acquire admin permissions.

Planned features

This project is currently under construction, here is some of the things to come:

• More documentation and examples
• Variable templating
• Mutliple providers (enables the use of another provider if the first one is down)
• Update channels for Github provider (alpha, beta, ...)
• Validation of the executable being installed

go-rocket-update's Issues

Suggestion: allow basic templating in `ArchiveName` & `ExecutableName`

Certain projects use the release tag in the archive name, eg awesome-package_0.1.2_linux_amd64.tar.gz, and I seem to recall some that even use it in the binary name too (not that I think the latter is a good idea).

My suggestion is to allow some basic go templating on both the Provider ArchiveName and Updater .ExecutableName of at least some common variables, such as {{.Tag}} {{.GOOS}}&{{.GOARCH}}. Whilst certain variables can be generated before the request (runtime.GOOS&runtime.GOARCH`), others are dependent on the remote info.

u := &updater.Updater{
    Provider: &provider.Github{
        RepositoryURL: "github.com/user/awesome-package",
        ArchiveName:   `awesome-package_{{.Tag}}_{{.GOOS}}_{{.GOARCH}}`,
    },
    ExecutableName: "awesome-package_{{.Tag}}",
    Version:        "0.1.1",
}

This would of course still remain completely backwards compatible with the current system, and one could even mix the two: ArchiveName: fmt.Sprintf("awesome-package_{{.Tag}}_%s_%s.tar.gz", runtime.GOOS, runtime.GOARCH).

The backstory is I've been meaning to rewrite a simple GitHub binary updater I wrote some time ago (far more primitive than yours), although I have been putting it off while I collect ideas etc. I just came across go-rocket-update which I think has a lot of potential, so rather than me spend time rewriting mine from scratch, I'd first check to see if you were open to suggestions to yours instead? I also have some other suggestions too if you're open to it.

Obtaining the contents of the zip folder

Hi,
Thanks for the great package, I have been looking for this for a while.
Is it possible to retrieve the contents of the zip folder? I have multiple fies and folders to update and want to manually override them along with the update.
Is this possible?
Many thanks.

GCS provider

Would like to add a Provider: GCS.

Example code: https://github.com/rudderlabs/rudder-server/blob/master/services/filemanager/gcsmanager.go

Module used:
https://pkg.go.dev/cloud.google.com/go/storage

What do you think ?

Proposal: use semantic versioning comparison for "GetLatestVersion()"

I note that the provider GetLatestVersion() doesn't return the latest version necessarily, but rather the latest release (ie: first result). I guess that in most cases the latest release is the latest version, however this assumption isn't always correct. For example an app may have two separate major version releases 1.x.x & 2.x.x, however if the 1.x.x is released after the 2.x.x then it will show as the GetLatestVersion().

A better way (I think) to address this, as well support the planned feature of release channels (across all providers), is to do semantic version comparisons instead for all versions (returned from API).

Regarding semantic version comparisons, one issue I ran into was that depending what library / method you use. Some developers tag it v1.2.3, others just 1.2.3, and some apps tag it as v1.2.3 and then use 1.2.3 in their app version itself. I found it safest just to ignore (strip) the leading optional v in the semantic version comparison in all cases, that way I was always able to compare versions correctly.

Missing v prefix in 1.5.2 release

Hello, thanks a ton for making this tool!

Was about to experiment a bit with it but noticed that the most recent release is missing the v-prefix in its tag, causing version handlers to not approve of it. I assume this was a mistake seeing how all previous tags are prefixed accordingly.

[Feature Request] GitHub API Tokens For Private Repos

Title should be self-explanatory but just in case:

I'd like to see the ability to provide an auth/api token for the updater, to allow it to download new releases from private github repositories.

Optional rollback Cleanup() on update

Hi! Unless I'm missing something, I cannot see any way to automatically remove the rollback *.bak file after a successful update. Could this be something that can either be manually run (*updater.Updater.Cleanup()) or otherwise passed as an Updater variable, as I don't see the point of always having *.bak files left on the system when the upgrade was successful?

windows: won't work with programs in \Program Files

Not an issue with your library per-se. Writing here for posterity and documentation purposes. There is a permission error if your go binary is installed in program files in windows with the default permissions:

Error updating: rename C:\Program Files\LipSurf\LipSurf Companion App\lipsurf-companion-app.exe C:\Program Files\LipSurf\LipSurf Companion App\lipsurf-companion-app.exe.old: Access is denied.

Might be worth documenting what permissions are needed by each OS.

zip: not a valid zip file

keep getting the error above when I build on windows amd64. Does not happen on linux amd64.

Providers is awesone

The provider pattern is great. I noticed so many libs doing the same but hard coded to one provider. This project will hopefully flourish because of it allowing many devs to add providers - nice work.

I am wondering if you found a decent download Webportal package for golang when researching this project ? Equinox projects one that is generated. I think a Hugo based one would be a nice addition. So users can download the binary initially from there. The location of the binary can then match the providers.