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 save it to 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 builder-tool 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.

Contents

• Features
• Installation
  • Installing Dependencies
  • Installing werf
• Getting started
• Backward Compatibility Promise
• Docs and Support
• License

• 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 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.

• 3-way-merge #1616.
• Developing applications locally with werf #1940.
• Content-based tagging #1184.
• 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.

• 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 distributedly (coming soon) #1614.
• 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:
  • IMAGES_REPO:[IMAGE_NAME-]TAG using monorepo mode.
  • IMAGES_REPO[/IMAGE_NAME]:TAG using multirepo mode.
• Different image tagging strategies:
  • Tagging images by binding them to git tag, branch, or commit.
  • Content-based tagging (coming soon) #1184.

• 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.
  • 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.

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 installation guide.

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

multiwerf is a version manager for werf. It:

• downloads werf binary builds;
• manages multiple versions of binaries installed on a single host (they can be used concurrently);
• automatically updates werf binary (this option can be disabled).

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

# install multiwerf into ~/bin directory
mkdir -p ~/bin
cd ~/bin
curl -L https://raw.githubusercontent.com/flant/multiwerf/master/get.sh | bash
source <(multiwerf use 1.0 beta)

Note: If you are using bash versions before 4.0 (e.g. 3.2 is default for MacOS users), you must use source /dev/stdin <<<"$(multiwerf use 1.0 beta)" instead of source <(multiwerf use 1.0 beta)

The latest release is available at this page

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

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

Download werf.exe

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

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.
• GitLab CI/CD integration — configure build, deploy, dismiss and cleanup jobs for GitLab CI.
• Integration with Unsupported CI/CD systems — integrate werf with any CI/CD system.
• 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).

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.

Patch releases are divided into channels. Channel is a prefix in a prerelease part of version (1.1.0-alpha.2, 1.1.0-beta.3, 1.1.0-ea.1). The version without a prerelease part is considered to have originated in a stable channel.

• stable channel (1.1.0, 1.1.1, 1.1.2, etc.). This version is recommended for use in critical environments with tight SLAs. We guarantee backward compatibility between stable releases within the minor branch (1.1.x).
• ea channel versions are mostly safe to use. These versions are suitable for all environments. We guarantee backward compatibility between ea releases within the minor branch (1.1.x). We guarantee that ea release should become a stable release after at least 2 weeks of broad testing.
• rc channel (2.3.2-rc.2). These releases are mostly safe to use and can be used in non-critical environments or for local development. We do not guarantee backward compatibility between rc releases. We guarantee that rc release should become ea after at least 1 week of internal testing.
• beta channel (1.2.2-beta.0). These releases are for broad testing of new features to catch regressions. We do not guarantee backward compatibility between beta releases.
• alpha channel (1.2.2-alpha.12, 2.0.0-alpha.5, etc.). These releases can bring new features but are unstable. We do not guarantee backward compatibility between alpha releases.

Make your first werf application or plunge into the complete documentation.

We are always in contact with the community through Twitter, Slack and Telegram. Join us!

Russian-speaking users can reach us in Telegram Chat

Your issues are processed carefully if posted to issues at GitHub

Apache License 2.0, see LICENSE