multiwerf

README

multiwerf

Tool to (auto)update a binary werf release to the latest available version

Installation

The simplest way is to install to current directory with install.sh script:

curl -L https://raw.githubusercontent.com/flant/multiwerf/master/install.sh | bash

Also you can manually download binary for your platform from bintray: latest version.

Usage

General usage of multiwerf is to download a werf binary and setup a werf function for the shell.

source <(multiwerf 1.0)

This command will download a stable version of werf into ~/.multiwerf directory and setup a function to run this version.

Commands

• multiwerf use MAJOR.MINOR CHANNEL — check for latest version of multiwerf, self update in background if needed, check for latest version in MAJOR.MINOR series and return a script for use with source
• multiwerf update MAJOR.MINOR CHANNEL — update binary to the latest version in MAJOR.MINOR series

First positional argument is in form of MAJOR.MINOR. More on this in Versioning.

CHANNEL is one of: alpha, beta, rc, stable

Binaries are downloaded to a directory $HOME/.multiwerf/VERSION/. For example, version 1.0.1-alpha.3 of werf binaries for user gitlab-runner will be stored as

/home/gitlab-runner/.multiwerf
|-- 1.0.1-alpha.3
|   |-- SHA256SUMS
|   |-- SHA256SUMS.sig
|   `-- werf-linux-amd64-1.0.1-alpha.3
|
...

use command also have --update=no flag to prevent version checking and use only locally available versions from ~/.multiwerf.

Versioning

Binary releases should follow a semver versioning, so version has this form:

MAJOR.MINOR.PATCH-PRERELEASE+METADATA

multiwerf makes this assumptions:

• PRERELEASE determines a CHANNEL
• PATCH can be increased directly (1.0.1 → 1.0.2)
• PATCH can be increased with prereleases (1.0.1 → 1.0.2-alpha → 1.0.2-alpha.1 → 1.0.2-rc.1 → 1.0.2)
• version without PRERELEASE part is a version for stable channel
• version with PRERELEASE part should be a version for alpha, beta or rc channels
• METADATA parts are not sorted (by semver spec)

Channels

stable

stable can be ommited: multiwerf use 1.1 stable or multiwerf use 1.1 is equivalent commands.

multiwerf will check for the latest PATCH for passed MAJOR.MINOR.

alpha, beta, rc

multiwerf use 1.0 alpha, multiwerf use 1.1 rc

multiwerf will check for the latest prerelease version. If there is version with equal or more stable prerelease then it will be used. If the latest version is stable then binary will be updated to stable.

For example, let assume that repository contains these versions:

2.0.2
2.0.12+build.2018.11
2.0.12+build.2018.12
2.1.0
2.1.1-alpha.1
2.1.1-rc.1
2.1.2
3.0.0
3.0.1-alpha.1
3.0.1-alpha.1
3.0.1-beta.2

multiwerf use 2.1

This command will download and run version 2.1.2 — the latest available stable for MAJOR=2, MINOR=1

multiwerf use 2.1 alpha
multiwerf use 2.1 rc

These commands will ignore 2.1.1-alpha and 2.1.1-rc prereleases and download version 2.1.2 because the latest version for 2.1 is 2.1.2.

multiwerf use 3.0 alpha

This command will download 3.0.1-beta.2 because there is availabe release in more stable channel: beta.

multiwerf use 3.0 rc

This command will download 3.0.0 because the latest PATCH 3.0.1 have no versions with rc prerelease.

multiwerf use 2.0

This command will download 2.0.12+build.2018.12 because equal MAJOR.MINOR.PATCH are are sorted by metadata.

Download settings

multiwerf depends on some external information:

• version list
• an url of repository
• a directories structure of the repository

The first version of multiwerf hardcode this information at complile time and support only bintray API and download url.

Some thoughts on release cycle

• stable channel is used for most critical environments with tight SLA
• rc for environments with normal SLA
• beta for environments where downtime is acceptable, i.e., dev, test, some kind of stages
• alpha for bleeding edge environments to give a try for fixes and new features

Installation and update

Multiwerf checks for new version in case of use and update commands. If new version in bintray.com/flant/multiwerf/multiwerf is found, multiwerf download it and start a new proccess with the same arguments and environment.

--self-update=no flag and MULTIWERF_SELF_UPDATE=no environment variable are available to turn off self updates.

Self update is disabled if multiwerf binary isn't owned by user that run it and if file is not writable by owner.

Offline tips

multiwerf can be used in offline scenarios.

1. set MULTIWERF_UPDATE=no and MULTIWERF_SELF_UPDATE=no environment variables to prevent http requests or use --self-update=no --update=no flags
2. put desired binary file and SHA256SUMS file into ~/.multiwerf/<version> directory
3. source <(multiwerf use ...) will not make any online request and consider locally available version as latest