From 35a86441bf2a751e6eb417b6f8ee47a41cd58269 Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Tue, 5 Oct 2021 11:57:21 -0600 Subject: [PATCH] added test Signed-off-by: Richard Jones --- docs/learn/1003-get-started.md | 59 +------- docs/learn/1003-get-started.md.bak | 126 ++++++++++++++++++ docs/learn/tests/doc.bats | 26 ++-- .../getting-started/plans/local/local.cue | 19 +++ .../tests/getting-started/plans/todoapp.cue | 36 +++++ 5 files changed, 195 insertions(+), 71 deletions(-) create mode 100644 docs/learn/1003-get-started.md.bak create mode 100644 docs/learn/tests/getting-started/plans/local/local.cue create mode 100644 docs/learn/tests/getting-started/plans/todoapp.cue diff --git a/docs/learn/1003-get-started.md b/docs/learn/1003-get-started.md index c3fa1a3d..0f6e493d 100644 --- a/docs/learn/1003-get-started.md +++ b/docs/learn/1003-get-started.md @@ -80,70 +80,15 @@ We will now create the following files: Create the file `plans/todoapp.cue` with the following content: -```cue -package todoapp - -import ( - "alpha.dagger.io/dagger" - "alpha.dagger.io/os" - "alpha.dagger.io/docker" - "alpha.dagger.io/js/yarn" -) - -// Build the source code using Yarn -app: yarn.#Package & { - "source": dagger.#Artifact & dagger.#Input -} - -// package the static HTML from yarn into a Docker image -image: os.#Container & { - image: docker.#Pull & { - from: "nginx" - } - - // app.build references our app key above - // which infers a dependency that Dagger - // uses to generate the DAG - copy: "/usr/share/nginx/html": from: app.build -} - -// push the image to a registry -push: docker.#Push & { - // leave target blank here so that different - // environments can push to different registries - target: string - - // the source of our push resource - // is the image resource we declared above - source: image -} - +```cue file=./tests/getting-started/plans/todoapp.cue ``` This file will define the resources and relationships between them that are common across _all environments_. For example, here we are deploying to our local Docker engine in our `local` environment, but for staging or production as examples, we would deploy the same image to some other container orchestration system such as Kubernetes hosted somewhere out there among the various cloud providers. Create the file `plans/local/local.cue` with the following content: -```cue -package todoapp +```cue file=./tests/getting-started/plans/local/local.cue -import ( - "alpha.dagger.io/dagger" - "alpha.dagger.io/docker" -) - -// run our todoapp in our local Docker engine -run: docker.#Run & { - ref: push.ref - name: "todoapp" - ports: ["8080:80"] - socket: dagger.#Stream & dagger.#Input -} - -// push to our local registry -// this concrete value satisfies the string constraint -// we defined in the previous file -push: target: "localhost:5000/todoapp" ``` Notice that both files have the same `package todoapp` declared on the first line. This is crucial to inform CUE that they are to be loaded and evaluated together in the same context. diff --git a/docs/learn/1003-get-started.md.bak b/docs/learn/1003-get-started.md.bak new file mode 100644 index 00000000..f5eaf5af --- /dev/null +++ b/docs/learn/1003-get-started.md.bak @@ -0,0 +1,126 @@ +--- +slug: /1003/get-started/ +--- + +# Get Started with Dagger + +In this tutorial, you will learn the basics of Dagger by building a Dagger project from scratch. This simple +project deploys a [React](https://reactjs.org/) application to your local machine via docker. In later tutorials, +you will learn how to configure Dagger to deploy to your infrastructure. And, for advanced users, +how to share access to your infrastructure in the same way that we share access to ours now. + +This tutorial does involve writing CUE, so if you haven’t already, be sure to read [What is CUE?](../introduction/1005-what_is_cue.md) + +In this tutorial we will learn how to: +- Structure a Dagger project +- Write CUE for Dagger +- Deploy an application using Dagger + +## Initial setup + +### Install Dagger + +First, make sure [you have installed Dagger on your local machine](../1001-install.md). + +### Setup example app + +You will need a local copy of the [Dagger examples repository](https://github.com/dagger/examples). +NOTE: you may use the same local copy across all tutorials. + +```shell +git clone https://github.com/dagger/examples +``` + +Make sure that all commands are run from the `todoapp` directory: + +```shell +cd examples/todoapp +``` + +### Import the tutorial key + +Dagger natively supports encrypted secrets: when a user inputs a value marked as secret +(for example, a password, API token, or ssh key) it is automatically encrypted with that user's key, +and no other user can access that value unless they are explicitly given access. + +In the interest of security, Dagger has no way _not_ to encrypt a secret value. +But this causes a dilemma for this tutorial: how do we give unrestricted, public access to our +(carefully sandboxed) infrastructure so that anyone can deploy to it? + +To solve this dilemma, we included the private key used to encrypt the tutorial's secret inputs. +Import the key to your Dagger installation, and you're good to go: + +```shell +./import-tutorial-key.sh +``` + +## First deployment + +Now that your environment is set up, you are ready to deploy: + +```shell +dagger up +``` + +That's it! You have just made your first deployment with Dagger. + +The URL of your newly deployed app should be visible towards the end of the command output. +If you visit that URL, you should see your application live! + +## Code, deploy, repeat + +This environment is pre-configured to deploy from the `./todoapp` directory, +so you can make any change you want to that directory, then deploy it with `dagger up`. +You can even replace our example React code with any React application! + +NOTE: you don't have to commit your changes to the git repository before deploying them. + +## Under the hood + +This example showed you how to deploy and develop an application that is already configured with Dagger. Now, let's learn a few concepts to help you understand how this was put together. + +### The Environment + +An Environment holds the entire deployment configuration. + +You can list existing environment from the `./todoapp` directory: + +```shell +dagger list +``` + +You should see an environment named `s3`. You can have many environments within your app. For instance, one for `staging`, one for `dev`, etc... + +Each environment can have a different kind of deployment code. For example, a `dev` environment can deploy locally; a `staging` environment can deploy to a remote infrastructure, and so on. + +### The plan + +The plan is the deployment code that includes the logic to deploy the local application to an AWS S3 bucket. From the `todoapp` directory, you can list the code of the plan: + +```shell +ls -l ./s3 +``` + +Any code change to the plan will be applied during the next `dagger up`. + +### The inputs + +The plan can define one or several `inputs`. Inputs may be configuration values, artifacts, or encrypted secrets provided by the user. Here is how to list the current inputs: + +```shell +dagger input list +``` + +The inputs are persisted inside the `.dagger` directory and pushed to your git repository. That's why this example application worked out of the box. + +### The outputs + +The plan defines one or several `outputs`. They can show helpful information at the end of the deployment. That's how we read the deploy `url` at the end of the deployment. Here is the command to list all outputs: + +```shell +dagger output list +``` + +## What's next? + +At this point, you have deployed your first application using Dagger and learned some dagger commands. You are now ready to [learn more about how to program Dagger](./1004-first-env.md). diff --git a/docs/learn/tests/doc.bats b/docs/learn/tests/doc.bats index 1cebc557..da94141c 100644 --- a/docs/learn/tests/doc.bats +++ b/docs/learn/tests/doc.bats @@ -11,21 +11,19 @@ setup() { @test "doc-1003-get-started" { setup_example_sandbox - # Set examples private key - "$DAGGER_SANDBOX"/import-tutorial-key.sh + # Follow tutorial + mkdir -p "$DAGGER_SANDBOX"/getting-started/plans + cp -R "$DAGGER_PROJECT"/getting-started/ "$DAGGER_SANDBOX"/getting-started/ + + dagger --project "$DAGGER_SANDBOX" new 'local' -p "$DAGGER_SANDBOX"/getting-started/plans/local + dagger --project "$DAGGER_SANDBOX" -e 'local' input socket run.socket /var/run/docker.sock + dagger --project "$DAGGER_SANDBOX" -e 'local' input dir app.source "$DAGGER_SANDBOX" + dagger --project "$DAGGER_SANDBOX" -e 'local' up - # Collect url - dagger --project "$DAGGER_SANDBOX" up - url=$(dagger --project "$DAGGER_SANDBOX" query -f text url) - - # More commands - dagger --project "$DAGGER_SANDBOX" list - ls -l "$DAGGER_SANDBOX"/s3 - dagger --project "$DAGGER_SANDBOX" input list - - # Check output - run curl "$url" - assert_output --partial "My Todo app" + until docker inspect --format "{{json .State.Status }}" todoapp | grep -m 1 "running"; do sleep 1 ; done + run curl -f -LI http://localhost:8080 + assert_output --partial '200 OK' + docker stop todoapp && docker rm todoapp } @test "doc-1004-first-env" { diff --git a/docs/learn/tests/getting-started/plans/local/local.cue b/docs/learn/tests/getting-started/plans/local/local.cue new file mode 100644 index 00000000..081df547 --- /dev/null +++ b/docs/learn/tests/getting-started/plans/local/local.cue @@ -0,0 +1,19 @@ +package todoapp + +import ( + "alpha.dagger.io/dagger" + "alpha.dagger.io/docker" +) + +// run our todoapp in our local Docker engine +run: docker.#Run & { + ref: push.ref + name: "todoapp" + ports: ["8080:80"] + socket: dagger.#Stream & dagger.#Input +} + +// push to our local registry +// this concrete value satisfies the string constraint +// we defined in the previous file +push: target: "localhost:5000/todoapp" \ No newline at end of file diff --git a/docs/learn/tests/getting-started/plans/todoapp.cue b/docs/learn/tests/getting-started/plans/todoapp.cue new file mode 100644 index 00000000..867aeb5e --- /dev/null +++ b/docs/learn/tests/getting-started/plans/todoapp.cue @@ -0,0 +1,36 @@ +package todoapp + +import ( + "alpha.dagger.io/dagger" + "alpha.dagger.io/os" + "alpha.dagger.io/docker" + "alpha.dagger.io/js/yarn" +) + +// Build the source code using Yarn +app: yarn.#Package & { + "source": dagger.#Artifact & dagger.#Input +} + +// package the static HTML from yarn into a Docker image +image: os.#Container & { + image: docker.#Pull & { + from: "nginx" + } + + // app.build references our app key above + // which infers a dependency that Dagger + // uses to generate the DAG + copy: "/usr/share/nginx/html": from: app.build +} + +// push the image to a registry +push: docker.#Push & { + // leave target blank here so that different + // environments can push to different registries + target: string + + // the source of our push resource + // is the image resource we declared above + source: image +} \ No newline at end of file