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

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/werf/multiwerf/master/get.sh | bash
Adding werf alias to the current shell session
. $(multiwerf use 1.1 stable --as-file)
CI usage tip

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

type multiwerf && . $(multiwerf use 1.1 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.1 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.3.0/multiwerf-windows-amd64-v1.3.0.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")
Adding werf alias to the current shell session
Invoke-Expression -Command "multiwerf use 1.1 stable --as-file --shell powershell" | Out-String -OutVariable WERF_USE_SCRIPT_PATH
. $WERF_USE_SCRIPT_PATH.Trim()
cmd.exe
Installing multiwerf

Run cmd.exe as Administrator and then do the following:

set MULTIWERF_BIN_PATH="C:\ProgramData\multiwerf\bin"
mkdir %MULTIWERF_BIN_PATH%
bitsadmin.exe /transfer "multiwerf" https://flant.bintray.com/multiwerf/v1.3.0/multiwerf-windows-amd64-v1.3.0.exe %MULTIWERF_BIN_PATH%\multiwerf.exe
setx /M PATH "%PATH%;%MULTIWERF_BIN_PATH%"

# after that open new cmd.exe session and start using multiwerf
Adding werf alias to the current shell session
FOR /F "tokens=*" %g IN ('multiwerf use 1.1 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 MAJOR.MINOR CHANNEL --in-background --output-file=~/.multiwerf/multiwerf_use_background_update.log --with-cache
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" | Out-String -OutVariable WERF_PATH) -and ($LastExitCode -eq 0)) {
    multiwerf update MAJOR.MINOR CHANNEL --in-background --output-file=~\.multiwerf\multiwerf_use_background_update.log --with-cache
} 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 (
    multiwerf update MAJOR.MINOR CHANNEL --in-background --output-file=~\.multiwerf\multiwerf_use_background_update.log --with-cache
)

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/werf/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.1.21+fix22/werf-darwin-amd64-v1.1.21+fix22 -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.1.21+fix22/werf-linux-amd64-v1.1.21+fix22 -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.1.21+fix22/werf-windows-amd64-v1.1.21+fix22.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.1.21+fix22/werf-windows-amd64-v1.1.21+fix22.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/werf/werf/cmd/werf

Backward Compatibility Promise

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

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.

  • We do not guarantee backward compatibility between:
    • alpha releases;
    • beta releases;
    • ea releases.
  • We guarantee backward compatibility between:
    • stable releases within the minor branch (1.1.x);
    • rock-solid releases within the minor branch (1.1.x).