Merge branch 'main' into main

docs/1001-install.md

@@ -10,9 +10,9 @@ slug: /1001/install/
 
 :::
 
-## Option 1: Use Homebrew (Mac OS only)
+## Option 1 (Mac OS and Linux): Use Homebrew
 
-From your Mac OS terminal, run the following command:
+From a terminal, run the following command:
 
 ```shell
 brew install dagger/tap/dagger
@@ -25,7 +25,7 @@ brew update
 brew upgrade dagger
 ```
 
-## Option 2: Run a shell script
+## Option 2 (Mac OS and Linux): Run a shell script
 
 From a terminal, run the following command:
 

docs/getting-started/1200-local-dev.md

@@ -1,5 +1,5 @@
 ---
-slug: /
+slug: /1200/local-dev
 displayed_sidebar: europa
 ---
 
@@ -209,13 +209,10 @@ It becomes even more obvious when the change is not as straightforward as knowin
 
 <TabItem value="windows">
 
-We assume that you have [curl](https://curl.se/windows/) installed.
-If you do, you can install `dagger` with a few commands. From a powershell terminal, run:
+From a powershell terminal, run:
 
 ```shell
-curl https://dl.dagger.io/dagger/install.ps1 -OutFile install.ps1
-./install.ps1
-rm install.ps1
+Invoke-WebRequest -UseBasicParsing -Uri https://dl.dagger.io/dagger/install.ps1 | Invoke-Expression
 ```
 
 We try to move the dagger binary under `C:\Windows\System32` but

docs/getting-started/1220-vs.md

@@ -0,0 +1,47 @@
+---
+slug: /1220/vs
+displayed_sidebar: europa
+---
+
+# 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.)
+
+Dagger is not a PaaS, but you can use it to add PaaS-like features to your CICD pipelines:
+
+* A simple deployment abstraction for the developer
+* A catalog of possible customizations, managed by the platform team
+* On-demand staging or development environments
+
+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
+
+Most applications have a custom deploy script that usually gets the job done, but is painful to change and troubleshoot.
+
+Using Dagger, you have two options:
+
+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.
+
+## Dagger vs. Infrastructure as Code (Terraform, Pulumi, Cloudformation, CDK)
+
+Dagger is the perfect complement to an IaC tool.
+
+* 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 do I orchestrate it?
+
+It is very common for a Dagger configuration to integrate with at least one IaC tool.
+
+## Dagger vs. Build Systems (Make, Maven, Bazel, Npm/Yarn, Docker Build, etc.)
+
+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.

docs/getting-started/index.md

@@ -0,0 +1,15 @@
+---
+slug: /
+displayed_sidebar: europa
+---
+
+# Getting Started
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+Run your CI/CD pipelines locally, then easily integrate them with any CI environment.
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+```

docs/learn/tests/helpers.bash

@@ -28,6 +28,12 @@ common_setup() {
     export DAGGER_SANDBOX
     dagger init --project "$DAGGER_SANDBOX"
 
+    if [ -n "$GITHUB_ACTIONS" ];
+    then
+        export DAGGER_CACHE_TO="type=gha,mode=max,scope=docs-tests-$BATS_TEST_NAME"
+        export DAGGER_CACHE_FROM="type=gha,scope=docs-tests-$BATS_TEST_NAME"
+    fi
+
     # allows the use of `sops`
     SOPS_AGE_KEY_FILE=~/.config/dagger/keys.txt
     export SOPS_AGE_KEY_FILE

docs/tests/core-concepts/plan/structure.cue.fragment

@@ -1,5 +1,5 @@
 // ...
-// A plan has pre-requisited that we cover below.
+// A plan has pre-requisites that we cover below.
 // For now we focus on the dagger.#Plan structure.
 // ...
 

docs/use-cases/1211-go-docker-swarm.md

@@ -15,7 +15,7 @@ The production setup is a multi-node Docker Swarm cluster running on AWS.
 The Particubes team chose Dagger for continuous deployment because it was the easiest way of integrating GitHub with Docker Swarm.
 Every commit to the main branch goes straight to [docs.particubes.com](https://docs.particubes.com) via a Dagger pipeline that runs in GitHub Actions. Let us see how the Particubes Dagger plan fits together.
 
-### Actions API
+## Actions API
 
 This is a high level overview of all actions in the Particubes docs Dagger plan:
 
@@ -23,7 +23,7 @@ This is a high level overview of all actions in the Particubes docs Dagger plan:
 
 We can see all available actions in a Plan by running the following command:
 
-```bash
+```console
 $ dagger do
 Execute a dagger action.
 
@@ -34,7 +34,7 @@ Available Actions:
  deploy Deploy a container image
 ```
 
-### Client API
+## Client API
 
 Dagger actions usually need to interact with the host environment where the Dagger client runs. The Particubes' plan uses environment variables and the filesystem.
 
@@ -45,20 +45,22 @@ This is an overview of all client interactions for this plan:
 This is what the above looks like in the Dagger plan config:
 
 ```cue file=../tests/use-cases/go-docker-swarm/client-api.cue.fragment
+
 ```
 
-### The *build* Action
+## The `build` Action
 
-This is a more in-depth overview of the *build* action and how it interacts with the client in the Particubes docs Dagger plan:
+This is a more in-depth overview of the _build_ action and how it interacts with the client in the Particubes docs Dagger plan:
 
 ![build action](/img/use-cases/build-action.png)
 
 This is what the above looks like in the Dagger plan config:
 
 ```cue file=../tests/use-cases/go-docker-swarm/build-action.cue.fragment
+
 ```
 
-### Github Action integration
+## Github Action integration
 
 This is the GitHub Actions workflow config that invokes `dagger`, which in turn runs the full plan:
 
@@ -102,16 +104,17 @@ dagger do
 
 This is the first step that enabled the Particubes team to have the same CI/CD experience everywhere.
 
-### Full Particubes docs Dagger plan
+## Full Particubes docs Dagger plan
 
 This is the entire plan running on Particubes' CI:
 
 ```cue file=../tests/use-cases/go-docker-swarm/full/particubes.docs.cue
+
 ```
 
-### What comes next ?
+## What comes next ?
 
-Particubes' team suggested that we create a `dev` action with *hot reload*, that way Dagger would even asbtract away the ramp-up experience when developing the doc
+Particubes' team suggested that we create a `dev` action with _hot reload_, that way Dagger would even asbtract away the ramp-up experience when developing the doc
 
 :::tip
 The latest version of this pipeline can be found at [github.com/voxowl/particubes/pull/144](https://github.com/voxowl/particubes/blob/2af173596729929cfb7a7a1f78f1ec0d8b685e5e/lua-docs/docs.cue)