From 79f86227f3352864ea615076dde28a964b7751fc Mon Sep 17 00:00:00 2001 From: Solomon Hykes Date: Tue, 7 Dec 2021 21:39:49 +0000 Subject: [PATCH] Docs: rewrite intro and "vs" to match landing page Signed-off-by: Solomon Hykes --- docs/introduction/1002-vs.md | 47 +++++++++++++++++++----------------- docs/introduction/what_is.md | 31 +++++------------------- 2 files changed, 31 insertions(+), 47 deletions(-) diff --git a/docs/introduction/1002-vs.md b/docs/introduction/1002-vs.md index 100b231d..82790629 100644 --- a/docs/introduction/1002-vs.md +++ b/docs/introduction/1002-vs.md @@ -4,40 +4,43 @@ slug: /1002/vs/ # Dagger vs. Other Software +## Dagger vs. CI (Github Actions, Gitlab, CircleCI, Jenkins, etc.) + +Dagger does not replace your CI: it improves it by adding a portable development layer on top of it. + +* Dagger runs on all major CI products. This *reduces CI lock-in*: you can change CI without rewriting all your pipelines. +* Dagger also runs on your dev machine. This allows *dev/CI parity*: the same pipelines can be used in CI and development. + ## Dagger vs. PaaS (Heroku, Firebase, etc.) -_Summary: Dagger can be used with or without a PaaS system._ +Dagger is not a PaaS, but you can use it to add PaaS-like features to your CICD pipelines: -A PaaS system is a complete platform for deploying and running certain types of applications. +* A simple deployment abstraction for the developer +* A catalog of possible customizations, managed by the platform team +* On-demand staging or development environments -- The benefit of using a PaaS system is convenience: developers don't have to worry about the many details of deployment: everything just works. -- The drawback of using a PaaS system is lack of flexibility: only certain types of applications are supported. - -As an application grows, it is almost certain to outgrow the capabilities of a PaaS system, leaving no choice but to look for alternatives. A good strategy is to choose the right platform for each component. Some components continue to run on a PaaS system; others run on specialized infrastructure. This strategy can be implemented with Dagger: each component gets its own deployment plan expressed as code, and Dagger glues it all together into a single workflow. +Using Dagger is a good way to get many of the benefits of a PaaS (developer productivity and peace of mind), +without giving up the benefits of custom CICD pipelines (full control over your infrastructure and tooling). ## Dagger vs. artisanal deploy scripts -_Summary: Dagger can augment your deploy scripts, and later help you simplify or even remove them._ +Most applications have a custom deploy script that usually gets the job done, but is painful to change and troubleshoot. -Most applications don't fit entirely in any major PaaS system. Instead they are deployed by a patchwork of tools, usually glued together by an artisanal script. +Using Dagger, you have two options: -A deploy script may be written in virtually any scripting language. The most commonly used languages include Bash, Powershell, Make, Python, Ruby, Javascript... As well as a plethora of niche specialized languages. +1. You can *replace* your script with a DAG that is better in every way: more features, more reliable, faster, easier to read, improve, and debug. +2. You can *extend* your script by wrapping it, as-is, into a DAG. This allows you to start using Dagger right away, and worry about rewrites later. -Most teams are unhappy with their deploy script. They are high maintenance, tend to break at the worst possible time, and are less convenient to use than a PaaS. But when you need control of your stack, what other choice is there? +## Dagger vs. Infrastructure as Code (Terraform, Pulumi, Cloudformation, CDK) -Dagger can either replace artisanal deploy scripts altogether, or augment them by incorporating them into a more standardized deployment system. This is a good strategy for teams which already have scripts and want to improve their deployment gradually, without the disruption of a "big bang" rewrite. +Dagger is the perfect complement to an IaC tool. -## Dagger vs. CI (Github Actions, Gitlab, CircleCI, Jenkins, etc.) +* IaC tools help infrastructure teams answer questions like: what is the current state of my infrastructure? What is its desired state? And how do I get there? +* Dagger helps CICD teams answer question like: what work needs to be done to deliver my application, in what order, and how to I orchestrate it? -_Summary: Dagger can be used with or without a CI system._ +It is very common for a Dagger configuration to integrate with at least one IaC tool. -Dagger is not a replacement for a CI system. It can be used to deploy applications directly from the terminal, -or automatically as part of a CI script. +## Dagger vs. Build Systems (Make, Maven, Bazel, Npm/Yarn, Docker Build, etc.) -## Dagger vs. Build Systems (Make, Maven, Bazel, Npm/Yarn, etc.) - -_Summary: Dagger can be used with or without a build system._ - -Most deployment workflows involve building: the process of producing executable artifacts from source code. Build systems are highly specific to the type of application, the programming language in use, etc. - -Dagger can integrate any build system into an overall deployment workflow. If a Dagger module is not already available for a particular build system, a custom module can easily be written, and perhaps even contributed to the open-source catalog for everyone else to use. +Dagger is complementary to build systems. Most Dagger configurations involve integrating with at least one specialized build. +If several build systems are involved, Dagger helps integrate them into a unified graph. diff --git a/docs/introduction/what_is.md b/docs/introduction/what_is.md index 29812e7d..a8841143 100644 --- a/docs/introduction/what_is.md +++ b/docs/introduction/what_is.md @@ -4,32 +4,13 @@ slug: / # What is Dagger? -Dagger is a universal deployment engine. Write your deployment logic once, run it securely from anywhere. +Dagger is a portable devkit for CICD. It helps you develop powerful CICD pipelines that can run anwyhere. -Key features: - -* Escape YAML hell. Thanks to the Cue language, writing configuration is as fun and productive as writing code. -* A powerful declarative execution engine to automate even the most complex and custom logic -* Static type checking so you can catch configuration errors before running that huge deployment -* Built-in caching and parallelism for maximum scale and performance -* An ecosystem of reusable packages to save you time and share your expertise with the community -* Avoid CI lock-in: the same Dagger configuration can be used in any CI, or with no CI at all -* Rapid local development: test and run everything locally, in seconds. -* Deploy from CI or the laptop: no more duplicating your CI config in a Makefile just so you can perform a task locally. -* Native support for encrypted secrets -* Just-in-time artifacts: fetch, transform and produce any artifact on the fly: source repositories, container images, binaries, database exports, ML models... - -Using Dagger, teams with different deployment workflows can more easily collaborate and deploy each other's software, -without being forced to change their tools. - -Typical use cases: - -* On-demand staging environments for reviewing code changes -* Manage CICD across multiple repositories and CI runners, with one unified configuration -* Iterate on infrastructure without disrupting development teams -* Lock down access to the production cluster so that only authorized configurations are applied -* Common ground between the PaaS, Kubernetes and Serverless siloes. -* On-demand integration environments for testing complex changes spanning several teams +* Choose from a wide catalog of reusable actions, or create your own in your favorite programming language. +* Tie it all together with [CUE](https://cuelang.org), the next-generation declarative language invented at Google. No more YAML hell! +* Unify dev and CI. The same Dagger pipeline can run on your dev machine or in CI. All you need is a Docker-compatible runtime. +* Avoid CI lock-in. Dagger runs natively on Github Actions, Gitlab, CircleCI, Jenkins, AWS Codebuild, Tekton, and more. +* Test and debug your pipelines locally; catch configuration errors in seconds with static type checking. ![Dagger_Website_Ship](https://user-images.githubusercontent.com/216487/122216381-328a3500-ce61-11eb-907f-d2b6f66b3b10.png)