Installing Dependencies

Docker

Docker CE installation guide.

Manage Docker as a non-root user. Create the docker group and add your user to the group:

sudo groupadd docker
sudo usermod -aG docker $USER

Git command line utility

Git installation guide.

  • Minimum required version is 1.9.0.
  • Version 2.14.0 or newer is required to use Git Submodules.

Installing werf

Method 1 (recommended): by using multiwerf

Unix shell (sh, bash, zsh)

Installing multiwerf
# add ~/bin into PATH
export PATH=$PATH:$HOME/bin
echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc

# install multiwerf into ~/bin directory
mkdir -p ~/bin
cd ~/bin
curl -L https://raw.githubusercontent.com/flant/multiwerf/master/get.sh | bash
Add werf alias to the current shell session
. $(multiwerf use 1.0 stable --as-file)
CI usage tip

To ensure that multiwerf exists and is executable, use the type command:

type multiwerf && . $(multiwerf use 1.0 stable --as-file)

The command prints a message to stderr if multiwerf is not found. Thus, diagnostics in a CI environment becomes simpler.

Optional: run command on terminal startup
echo '. $(multiwerf use 1.0 stable --as-file)' >> ~/.bashrc

Windows

PowerShell
Installing multiwerf
$MULTIWERF_BIN_PATH = "C:\ProgramData\multiwerf\bin"
mkdir $MULTIWERF_BIN_PATH

Invoke-WebRequest -Uri https://flant.bintray.com/multiwerf/v1.0.16/multiwerf-windows-amd64-v1.0.16.exe -OutFile $MULTIWERF_BIN_PATH\multiwerf.exe

[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::Machine) + "$MULTIWERF_BIN_PATH",
    [EnvironmentVariableTarget]::Machine)

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
Add werf alias to the current shell session
Invoke-Expression -Command "multiwerf use 1.0 stable --as-file --shell powershell" | Out-String -OutVariable WERF_USE_SCRIPT_PATH
. $WERF_USE_SCRIPT_PATH.Trim()
cmd.exe
Installing multiwerf
set MULTIWERF_BIN_PATH="C:\ProgramData\multiwerf\bin"
mkdir %MULTIWERF_BIN_PATH%
bitsadmin.exe /transfer "multiwerf" https://flant.bintray.com/multiwerf/v1.0.16/multiwerf-windows-amd64-v1.0.16.exe %MULTIWERF_BIN_PATH%\multiwerf.exe
setx /M PATH "%PATH%;%MULTIWERF_BIN_PATH%"

# after that open new cmd.exe session and start using multiwerf
Add werf alias to the current shell session
FOR /F "tokens=*" %g IN ('multiwerf use 1.0 stable --as-file --shell cmdexe') do (SET WERF_USE_SCRIPT_PATH=%g)
%WERF_USE_SCRIPT_PATH%

multiwerf use command in details

The command multiwerf use MAJOR.MINOR CHANNEL allows using the actual werf binary and to be always up-to-date. You can use this command both in CI and on the local machine. The command returns a script or a path to the script file (when used with an --as-file option) that must be used as an argument to the source command. As a result, the current version of werf will be available during the shell session.

The script can be divided into two logic parts: updating and creating werf alias or the definition of the function depending on shell type. The update part performs multiwerf self-update and gets the actual werf binary for the specified MAJOR.MINOR version and CHANNEL (read more about werf versioning in the Backward Compatibility Promise section). The update is performed by the multiwerf update command. If the script is launched for the first time or there is no suitable werf binary found locally, these steps are being run consistently. Otherwise, the update runs in the background, and werf alias or a function binds to the existing werf binary based on local channel mapping.

if multiwerf werf-path MAJOR.MINOR CHANNEL >~\.multiwerf\multiwerf_use_first_werf_path.log 2>&1; then
    (multiwerf update --with-cache MAJOR.MINOR CHANNEL >~\.multiwerf\background_update.log 2>&1 </dev/null &)
else
    multiwerf update MAJOR.MINOR CHANNEL
fi

WERF_PATH=$(multiwerf werf-path MAJOR.MINOR CHANNEL)
WERF_FUNC=$(cat <<EOF
werf()
{
    $WERF_PATH "\$@"
}
EOF
)

eval "$WERF_FUNC"
if (Invoke-Expression -Command "multiwerf werf-path MAJOR.MINOR CHANNEL >~\.multiwerf\multiwerf_use_first_werf_path.log 2>&1" | Out-String -OutVariable WERF_PATH) {
    Start-Job { multiwerf update --with-cache MAJOR.MINOR CHANNEL >~\.multiwerf\background_update.log 2>&1 }
} else {
    multiwerf update MAJOR.MINOR CHANNEL
    Invoke-Expression -Command "multiwerf werf-path MAJOR.MINOR CHANNEL" | Out-String -OutVariable WERF_PATH
}

function werf { & $WERF_PATH.Trim() $args }
FOR /F "tokens=*" %%g IN ('multiwerf werf-path MAJOR.MINOR CHANNEL') do (SET WERF_PATH=%%g)

IF %ERRORLEVEL% NEQ 0 (
    multiwerf update MAJOR.MINOR CHANNEL 
    FOR /F "tokens=*" %%g IN ('multiwerf werf-path MAJOR.MINOR CHANNEL') do (SET WERF_PATH=%%g)
) ELSE (
    START /B multiwerf update MAJOR.MINOR CHANNEL >~/.multiwerf/background_update.log 2>&1
)

DOSKEY werf=%WERF_PATH% $*

During the update, multiwerf tries to download the desirable werf version based on a channel mapping. The channel mapping is a special file that keeps relations between channels and werf versions. By default, multiwerf uses the mapping file which is maintained in the werf repository (https://github.com/flant/werf/blob/multiwerf/multiwerf.json)

Such an approach allows a user not to worry about updates and use the same werf binary version on CI and the local machine. We create new releases with fixes and features and manage channels while you simply use a single command everywhere.

Method 2: by downloading binary package

The latest release can be found at this page

MacOS

curl -L https://dl.bintray.com/flant/werf/v1.0.6-rc.5/werf-darwin-amd64-v1.0.6-rc.5 -o /tmp/werf
chmod +x /tmp/werf
sudo mv /tmp/werf /usr/local/bin/werf

Linux

curl -L https://dl.bintray.com/flant/werf/v1.0.6-rc.5/werf-linux-amd64-v1.0.6-rc.5 -o /tmp/werf
chmod +x /tmp/werf
sudo mv /tmp/werf /usr/local/bin/werf

Windows

PowerShell
$WERF_BIN_PATH = "C:\ProgramData\werf\bin"
mkdir $WERF_BIN_PATH

Invoke-WebRequest -Uri https://dl.bintray.com/flant/werf/v1.0.6-rc.5/werf-windows-amd64-v1.0.6-rc.5.exe -OutFile $WERF_BIN_PATH\werf.exe

[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::Machine) + "$WERF_BIN_PATH",
    [EnvironmentVariableTarget]::Machine)

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
cmd.exe (run as Administrator)
set WERF_BIN_PATH="C:\ProgramData\werf\bin"
mkdir %WERF_BIN_PATH%
bitsadmin.exe /transfer "werf" https://dl.bintray.com/flant/werf/v1.0.6-rc.5/werf-windows-amd64-v1.0.6-rc.5.exe %WERF_BIN_PATH%\werf.exe
setx /M PATH "%PATH%;%WERF_BIN_PATH%"

# open new cmd.exe session and start using werf

Method 3: by compiling from source

go get github.com/flant/werf/cmd/werf

Backward Compatibility Promise

Note: This promise was introduced with werf 1.0 and does not apply to previous versions or to dapp releases

werf follows a versioning strategy called Semantic Versioning. It means that major releases (1.0, 2.0) can break backward compatibility. In the case of werf, an update to the next major release may require to do a full re-deploy of applications or to perform other non-scriptable actions.

Minor releases (1.1, 1.2, etc.) may introduce new global features, but have to do so without significant backward compatibility breaks with a major branch (1.x). In the case of werf, this means that an update to the next minor release goes smoothly most of the time. However, it may require running a provided upgrade script.

Patch releases (1.1.0, 1.1.1, 1.1.2) may introduce new features, but must do so without breaking backward compatibility within the minor branch (1.1.x). In the case of werf, this means that an update to the next patch release should be smooth and can be done automatically.

All changes go through all stability channels:

  • alpha channel can bring new features but can be unstable. We do not guarantee backward compatibility between alpha releases.
  • beta channel is for more broad testing of new features to catch regressions. We do not guarantee backward compatibility between beta releases.
  • ea channel is mostly safe and can be used in non-critical environments or for local development. We do not guarantee backward compatibility between ea releases.
  • stable channel is mostly safe and we encourage you to use this version everywhere. We guarantee that ea release should become stable not earlier than 1 week after internal tests. We guarantee backward compatibility between stable releases within the minor branch (1.1.x).
  • rock-solid channel is a generally available version and recommended for use in critical environments with tight SLAs. We guarantee that stable release should become a rock-solid release not earlier than after 2 weeks of extensive testing. We guarantee backward compatibility between rock-solid releases within the minor branch (1.1.x).

The relations between channels and werf releases are described in multiwerf.json. The usage of werf within the channel should be carried out with multiwerf.

When using release channels, you do not specify a version, because the version is managed automatically within the channel

Stability channels and frequent releases allow receiving continuous feedback on new changes, quickly rolling problem changes back, ensuring the high stability of the software, and preserving an acceptable development speed at the same time.