Installing Dependencies
Docker
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
- 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/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).