{"id":13542531,"url":"https://github.com/cloud66-oss/updater","last_synced_at":"2025-10-30T00:04:24.410Z","repository":{"id":57542055,"uuid":"180613979","full_name":"cloud66-oss/updater","owner":"cloud66-oss","description":"A simple to use Go package for self updating binaries.","archived":false,"fork":false,"pushed_at":"2020-09-03T13:14:59.000Z","size":37,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-24T21:42:26.895Z","etag":null,"topics":["golang","golang-library","updater"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud66-oss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-10T15:46:44.000Z","updated_at":"2024-05-25T14:49:49.000Z","dependencies_parsed_at":"2022-09-08T23:51:36.045Z","dependency_job_id":null,"html_url":"https://github.com/cloud66-oss/updater","commit_stats":null,"previous_names":["khash/updater"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66-oss%2Fupdater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66-oss%2Fupdater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66-oss%2Fupdater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud66-oss%2Fupdater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud66-oss","download_url":"https://codeload.github.com/cloud66-oss/updater/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225708,"owners_count":21068078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","golang-library","updater"],"created_at":"2024-08-01T10:01:09.816Z","updated_at":"2025-10-30T00:04:24.401Z","avatar_url":"https://github.com/cloud66-oss.png","language":"Go","funding_links":[],"categories":["Go","golang"],"sub_categories":[],"readme":"\u003cimg src=\"http://cdn2-cloud66-com.s3.amazonaws.com/images/oss-sponsorship.png\" width=150/\u003e\n\n# Updater\n A simple to use Go package for self updating binaries. It supports HTTP download, Semantic versioning, channels and remote forced updates.\n\n ## Install\n\n```bash\n$ go get github.com/cloud66-oss/updater\n```\n\n## Usage\n\nTo use updater, you need to push your binaries somewhere they can be downloaded using HTTP (like an S3 bucket). You also need to construct a single JSON file to include details of your versions. By default this file is called `versions.json` and can look like this:\n\n```json\n{\n  \"versions\": [\n    {\n      \"version\":  \"1.0.0-pre\",\n      \"channel\": \"dev\"\n    },\n    {\n      \"version\": \"1.0.0\",\n      \"channel\": \"stable\"\n    },\n    {\n      \"version\": \"1.0.0-pre-1-57dh54\",\n      \"channel\": \"nightly\",\n      \"force\": true\n    }\n  ]\n}\n```\n\nUpdater supports multiple OS and architectures.\n\n**NOTE**:\n\nUpdater strictly requires SemVer compatible versions.\n\nThis is an example code:\n\n\n```go\nfunc update() {\n\tworker, err := updater.NewUpdater(utils.Version, \u0026updater.Options{\n\t\tRemoteURL: \"https://s3.amazonaws.com/acme/myapp/\",\n\t\tChannel:   \"dev\",\n\t\tSilent:    false,\n\t})\n\tif err != nil {\n\t\tfmt.Println(err)\n\t}\n\n\terr = worker.Run(false)\n\tif err != nil {\n\t    fmt.Println(err)\n\t}\n}\n```\n\nThe code above updates the current executable if the local version is older than the remote version for the `dev` channel.\n\n### Options\n\n`updater.Options` has the following fields:\n\n```go\n\tRemoteURL            string\n\tVersionSpecsFilename string\n\tBinPattern           string\n\tChannel              string\n\tSilent               bool\n```\n\n**RemoteURL**\n\nThe full URL of where the binaries and `versions.json` file can be found. An example could be `https://downloads.acme.org/`. Including the trailing `/` is not mandatory.\n\n**VersionSpecsFilename**\n\nThis is the name of the JSON file. If not set, `versions.json`  will be used which will mean the full URL for the JSON file will be `https://downloads.acme.org/versions.json`\n\n**BinPattern**\n\nThis is the pattern used to find the relevant binary file to download. If not specified the default is `{{OS}}_{{ARCH}}_{{VERSION}}`. This means the updater will look for version `1.10.20` of the binary compiled for the OSX 64bit architecture at `https://downloads.acme.org/darwin_amd64_1.10.20`\n\n**Channel**\n\nThis is the name of the channel to look for. Default is `dev`. Using channels you can choose to have different version tracks for your binaries.\n\n**Silent**\n\nIf set to `false` the updater will print out progress of the update to the console (stdout).\n\n### Updater\n\nThe Updater itself, can be created using `NewUpdater` and run using the `Run` function. You can force updates by passing the `force` parameter into `Run`. If forced, the binary will be updated even if it's newer than the remote version.\n\nYou can also remote force an update. This is useful when you need to rollback to an older version across all clients. To force an update remotely, set the `force` attribute to `true` in `versions.json` as per example above.\n\n## Compiling\n\nCompiling your binaries and construction of the JSON file is up to you. You can use the following as helpers.\n\n### Build\n\nThis is an example build bash script:\n\n```bash\n#!/bin/bash\n\nversion=$(git describe --tags --always)\n\nif [ -z \"$1\" ]\n  then\n    echo \"No channel supplied\"\n    exit 1\nfi\n\nchannel=$1\n\necho \"Building $channel/$version\"\necho\n\nrm build/*\ncurl -s http://s3.amazonaws.com/acme/versions.json | jq '.versions |= map(if (.channel == \"'$channel'\") then .version = \"'$version'\" else . end)' \u003e build/versions.json\necho \"Current Versions\"\ncat build/versions.json | jq -r '.versions | map([.channel, .version] | join(\": \")) | .[]'\necho\n\ngox -ldflags \"-X github.com/acme/myapp/utils.Version=$version -X github.com/acme/myapp/utils.Channel=$channel\" -os=\"darwin linux windows\" -arch=\"amd64\" -output \"build/{{.OS}}_{{.Arch}}_$version\"\n```\n\nThe above example assumes 2 variables in `utils` package to hold the current version and the current channel for your application and sets them to the current git tag and the user input into the bash script. This means for the updater to work, you'd need to tag your code with a valid SemVer tag.\n\nIt also requires [gox](https://github.com/mitchellh/gox) tool to allow cross compiling of the code.\n\n### Publish\n\nTo publish your binaries to S3 you can use something like this bash script:\n\n\n```bash\n#!/bin/bash\n\naws s3 cp build s3://acme/myapp --acl public-read --recursive\n```\n\nThis script requires a configured AWS cli installed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud66-oss%2Fupdater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud66-oss%2Fupdater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud66-oss%2Fupdater/lists"}