werf is an Open Source CLI tool written in Go, designed to simplify and speed up the delivery of applications. To use it, you need to describe the configuration of your application (in other words, how to build and deploy it to Kubernetes) and store it in a Git repo — the latter acts as a single source of truth. In short, that's what we call GitOps today.
- werf builds Docker images using Dockerfiles or an alternative fast built-in builder based on the custom syntax. It also deletes unused images from the Docker registry.
- werf deploys your application to Kubernetes using a chart in the Helm-compatible format with handy customizations and improved rollout tracking mechanism, error detection, and log output.
werf is not a complete CI/CD solution, but a tool for creating pipelines that can be embedded into any existing CI/CD system. It literally "connects the dots" to bring these practices into your application. We consider it a new generation of high-level CI/CD tools.
- Getting started
- Documentation and support
- Production ready
- Full application lifecycle management: build and publish images, deploy an application to Kubernetes, and remove unused images based on policies.
- The description of all rules for building and deploying an application (that may have any number of components) is stored in a single Git repository along with the source code (Single Source Of Truth).
- Build images using Dockerfiles.
- Alternatively, werf provides a custom builder tool with support for custom syntax, Ansible, and incremental rebuilds based on Git history.
- werf supports Helm 2-compatible charts and complex fault-tolerant deployment processes with logging, tracking, early error detection, and annotations to customize the tracking logic of specific resources.
- werf is a CLI tool written in Go. It can be embedded into any existing CI/CD system to implement CI/CD for your application.
- Cross-platform development: Linux-based containers can be run on Linux, macOS, and Windows.
- Developing applications locally with werf #1940.
Content-based tagging#1184. Support for the most Docker registry implementations#2199. Parallel image builds#2200.
- Proven approaches and recipes for the most popular CI systems #1617.
Distributed builds with the shared Docker registry#1614.
- Support for Helm 3 #1606.
- (Kaniko-like) building in the userspace that does not require Docker daemon #1618.
Complete list of features
- Effortlessly build as many images as you like in one project.
- Build images using Dockerfiles or Stapel builder instructions.
- Build images concurrently on a single host (using file locks).
- Build images simultaneously.
- Build images distributedly.
- Advanced building process with Stapel:
- Incremental rebuilds based on git history.
- Build images with Ansible tasks or Shell scripts.
- Share a common cache between builds using mounts.
- Reduce image size by detaching source data and building tools.
- Build one image on top of another based on the same config.
- Debugging tools for inspecting the build process.
- Detailed output.
- Store images in one or multiple Docker repositories using the following naming patterns:
- Different image tagging strategies:
- Tagging images by binding them to git tag, branch, or commit.
- Content-based tagging.
- Deploy an application to Kubernetes and check if it has been deployed correctly.
- Track the statuses of all application resources.
- Control the readiness of resources.
- Control the deployment process with annotations.
- Full visibility of both the deployment process and the final result.
- Logging and error reporting.
- Regular status reporting during the deployment phase.
- Debug problems effortlessly without unnecessary kubectl invocations.
- Prompt CI pipeline failure in case of a problem (i.e. fail fast).
- Instant detection of resource failures during the deployment process without having to wait for a timeout.
- Full compatibility with Helm 2.
- Ability to limit user permissions using RBAC definition when deploying an application (Tiller is compiled into werf and is run under the ID of the outside user that carries out the deployment).
- Parallel builds on a single host (using file locks).
- Distributed parallel deploys (coming soon) #1620.
- Сontinuous delivery of images with permanent tags (e.g., when using a branch-based tagging strategy).
- Clean up local and Docker registry by enforcing customizable policies.
- Keep images that are being used in the Kubernetes cluster. werf scans the following kinds of objects: Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Job, CronJob, ReplicationController.
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.
There are a lot of ways to install werf, but using multiwerf is a recommended practice both for local development and CI usage.
The other approaches are also available in Installation guide.
Unix shell (sh, bash, zsh)
# 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 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
$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()
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%
Following guides demonstrate the key features of werf and help you to start using it:
- Getting started — start using werf with an existing Dockerfile.
- First application — build your first application (PHP Symfony) with werf builder.
- Deploy into Kubernetes — deploy an application to the Kubernetes cluster using werf built images.
- CI/CD systems integration: generic, GitLab CI, GitHub Actions.
- Multi-images application — build multi-images application (Java/ReactJS).
- Mounts — reduce image size and speed up your build with mounts (Go/Revel).
- Artifacts — reduce image size with artifacts (Go/Revel).
Documentation and support
Russian-speaking users can also reach us in Telegram Chat.
Your issues are processed carefully if posted to issues at GitHub.
werf is a mature, reliable tool you can trust:
- 5 stability levels are available, from alpha to stable & rock-solid. All changes in werf go through each of them, and transitions to the most stable channels require specific periods of preliminary testing. This all guarantees certain levels of stability from which users can choose.
- Most of werf code is covered with automatic (e2e and unit) tests.
- In Flant, werf is being used in production since 2016 for building and since 2017 for deploying hundreds of applications. These apps are extremely diverse in sizes, designs, and technology stacks being used. We know at least dozens of other businesses using werf for years.
- If there are any concerns on using werf, please welcome to our online communities (Slack, Twitter) and feel free to ask the questions you might have — we are happy to help!
All changes in werf go through all stability channels:
alphachannel can bring new features but can be unstable;
betachannel is for more broad testing of new features to catch regressions;
eachannel is mostly safe and can be used in non-critical environments or for local development;
stablechannel is mostly safe and we encourage you to use this version everywhere. We guarantee that
earelease should become
stablenot earlier than 1 week after internal tests;
rock-solidchannel is a generally available version and recommended for use in critical environments with tight SLAs. We guarantee that
stablerelease should become a
rock-solidrelease not earlier than after 2 weeks of extensive testing.
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.
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:
- We guarantee backward compatibility between:
stablereleases within the minor branch (1.1.x);
rock-solidreleases within the minor branch (1.1.x).
Apache License 2.0, see LICENSE.