Enable your Golang applications to self update. Inspired by Chrome based on Heroku's hk.
- Tested on Mac, Linux, Arm, and Windows
- Creates binary diffs with bsdiff allowing small incremental updates
- Falls back to full binary update if diff fails to match SHA
go install github.com/sanbornm/go-selfupdate/cmd/go-selfupdate@latest
go get -u github.com/sanbornm/go-selfupdate/...
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)
// app name allows you to serve updates for multiple apps on the same server/endpoint
}
// go look for an update when your app starts up
go updater.BackgroundRun()
// your app continues to run...
go-selfupdate path-to-your-app the-version
go-selfupdate myapp 1.2
By default this will create a folder in your project called public. You can then rsync or transfer this to your webserver or S3. To change the output directory use -o flag.
If you are cross compiling you can specify a directory:
go-selfupdate /tmp/mybinares/ 1.2
The directory should contain files with the name, $GOOS-$ARCH. Example:
windows-386
darwin-amd64
linux-arm
If you are using goxc you can output the files with this naming format by specifying this config:
"OutPath": "{{.Dest}}{{.PS}}{{.Version}}{{.PS}}{{.Os}}-{{.Arch}}",
Updates are fetched from an HTTP(s) server. AWS S3 or static hosting can be used. A JSON manifest file is pulled first which points to the wanted version (usually latest) and matching metadata. SHA256 hash is currently the only metadata but new fields may be added here like signatures. go-selfupdate isn't aware of any versioning schemes. It doesn't know major/minor versions. It just knows the target version by name and can apply diffs based on current version and version you wish to move to. For example 1.0 to 5.0 or 1.0 to 1.1. You don't even need to use point numbers. You can use hashes, dates, etc for versions.
GET yourserver.com/appname/linux-amd64.json
200 ok
{
"Version": "2",
"Sha256": "..." // base64
}
then
GET patches.yourserver.com/appname/1.1/1.2/linux-amd64
200 ok
[bsdiff data]
or
GET fullbins.yourserver.com/appname/1.0/linux-amd64.gz
200 ok
[gzipped executable data]
The only required files are <appname>/<os>-<arch>.json and <appname>/<latest>/<os>-<arch>.gz everything else is optional. If you wanted to you could skip using go-selfupdate CLI tool and generate these two files manually or with another tool.
Updater Config options:
type Updater struct {
CurrentVersion string // Currently running version. `dev` is a special version here and will cause the updater to never update.
ApiURL string // Base URL for API requests (JSON files).
CmdName string // Command name is appended to the ApiURL like http://apiurl/CmdName/. This represents one binary.
BinURL string // Base URL for full binary downloads.
DiffURL string // Base URL for diff downloads.
Dir string // Directory to store selfupdate state.
ForceCheck bool // Check for update regardless of cktime timestamp
CheckTime int // Time in hours before next check
RandomizeTime int // Time in hours to randomize with CheckTime
Requester Requester // Optional parameter to override existing HTTP request handler
Info struct {
Version string
Sha256 []byte
}
OnSuccessfulUpdate func() // Optional function to run after an update has successfully taken place
}
It is common for an app to want to restart to apply the update. go-selfupdate gives you a hook to do that but leaves it up to you on how and when to restart as it differs for all apps. If you have a service restart application like Docker or systemd you can simply exit and let the upstream app start/restart your application. Just set the OnSuccessfulUpdate hook:
u.OnSuccessfulUpdate = func() { os.Exit(0) }
Or maybe you have a fancy graceful restart library/func:
u.OnSuccessfulUpdate = func() { gracefullyRestartMyApp() }
go-selfupdate will keep a Go time.Time formatted timestamp in a file named cktime in folder specified by Updater.Dir. This can be useful for debugging to see when the next update can be applied or allow other applications to manipulate it.