kjuulh/dagger
Archived
1
0
Fork 0
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

new getting started tutorial

Browse Source 
Signed-off-by: Richard Jones <richard@dagger.io>
This commit is contained in:
Richard Jones 2021-10-01 15:11:15 -06:00
parent 00e10219ca
commit ef66f0bc69
1 changed files with 149 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
docs/learn/1003-get-started.md
View File

@ -4,10 +4,7 @@ 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.
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&rsquo;t already, be sure to read [What is CUE?](../introduction/1005-what_is_cue.md)
@ -23,28 +20,43 @@ In this tutorial we will learn:
## Deploy an Application Locally
The following instructions assume you are working locally, but could just as easily be run on a remote
machine into which you have a shell. For the sake of brevity and simplicity we will create directories under
your home directory, but feel free to replace `~/` with a path that works best for you.
The following instructions assume you are working locally, but could just as easily be run on a remote machine into which you have a shell.
### Install Dagger
First, make sure [you have installed Dagger](../1001-install.md). You can run `dagger version` to ensure
you have the latest installed and working.
First, make sure [you have installed Dagger](../1001-install.md). You can run `dagger version` to ensure you have the latest installed and working.
### Create a Dagger Project
First we need a directory that will contain our `.cue` files and a `.dagger` directory which stores metadata about environments. First, create a new directory for our todoapp, then initialize the project:
First clone the [Dagger examples repository](https://github.com/dagger/examples), change directories to the `todoapp/` and list its contents:
> Note that all tutorials will operate from the todoapp directory.
```bash
mkdir ~/todoapp
cd ~/todoapp
dagger init
git clone https://github.com/dagger/examples.git
cd examples/todoapp
ls -la
```
If you now run `ls -la` you will see 2 new directories:
This React application will use Yarn to build a static website with the following directories and files.
- The `.dagger` directory will store metadata about _environments_, _inputs_, and _outputs_ which we will cover shortly.
```bash
-rw-r--r-- ... 794 Sep 7 10:09 package.json
drwxr-xr-x ... 256 Sep 7 10:09 public
drwxr-xr-x ... 192 Sep 29 11:17 src
-rw-r--r-- ... 465514 Sep 29 11:17 yarn.lock
```
Now we need to initialize this directory as a Dagger _project_ (and relist directories):
```bash
dagger init
ls -la
```
You will now see 2 new directories:
- The `.dagger` directory will store metadata about _environments_, _inputs_, and _outputs_ which we will cover later.
- The `cue.mod` directory stores libraries such as [dagger/universe](https://github.com/dagger/universe) which can be _imported_ into your Dagger _plan_.
Dagger will load all `.cue` files recursively in the current Dagger project. More directories can be added to help organize code.
@ -53,54 +65,155 @@ Dagger will load all `.cue` files recursively in the current Dagger project. Mor
### Write a Dagger Plan
A Dagger _plan_ is written in CUE and expresses the _resources_, _dependencies_, and _logic_ to deploy an application to an environment. Unlike traditional glue code written in an scripting language (e.g.: Bash, PowerShell), a Dagger plan is _declarative_ rather than _imperative_. This frees us from thinking about order of operations, since Dagger will infer dependendencies and calculate correct order on its own.
A Dagger _plan_ is written in CUE and defines the _resources_, _dependencies_, and _logic_ to deploy an application to an environment. Unlike traditional glue code written in a scripting language such as Bash or PowerShell, a Dagger plan is _declarative_ rather than _imperative_. This frees us from thinking about the order of operations, since Dagger will infer dependendencies and calculate correct order on its own.
First create a directory to hold our plan, separate from our application code:
Let's first create a directory to hold our plan separately from our application code:
```shell
mkdir ./plan
```bash
mkdir -p ./plans/local
```
Next, create a file in `plan/` called `todoapp.cue` with the following content
We will now create the following files:
- `plans/todoapp.cue` which will define resources common to all environments
- `plans/local/local.cue` which will define resources specific to the local environment
Create the file `plans/todoapp.cue` with the following content:
```cue
package todoapp
import (
"alpha.dagger.io/dagger"
"alpha.dagger.io/dagger/stream"
"alpha.dagger.io/js/yarn"
"alpha.dagger.io/dagger"
"alpha.dagger.io/os"
"alpha.dagger.io/docker"
"alpha.dagger.io/js/yarn"
)
// Source code of the sample application
source: dagger.#Artifact & dagger.#Input
// Build the source code using Yarn
app: yarn.#Package & {
"source": source
"source": dagger.#Artifact & dagger.#Input
}
// package the staic HTML from yarn into a Docker image
image: os.#Container & {
image: docker.#Pull & {
from: "nginx"
}
copy: "/usr/share/nginx/html": from: app.build
}
// push the image to a registry
push: docker.#Push & {
// leave target as a string here so that
// different environments can push to different registries
target: string
source: image
}
```
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 to some other container orchestration system such as Kubernetes somewhere out there among the various cloud providers.
Create the file `plans/local/local.cue` with the following content:
```cue
package todoapp
import (
"alpha.dagger.io/dagger"
"alpha.dagger.io/docker"
)
// run our todoapp in our local Docker engine
todoapp: docker.#Run & {
ref: push.ref
name: "todoapp"
ports: ["8080:80"]
socket: dagger.#Stream & dagger.#Input
}
// push to our local registry
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.
Our `local.cue` file now holds resources specific to our `local` environment. Also notice that we are defining a concrete value for the `target` key here. The entire `push` object is defined in both files and CUE will merge the values found among our 2 files.
### Create an Environment
Before we can deploy the plan, we need to define an environment which is the specific plan to execute, as well as the context from which inputs are pulled and to which state is stored.
In this example we will deploy the app to our local docker engine so let&rsquo;s create a `local` environment:
```shell
dagger new local -p ./plan
dagger new local -p ./plans/local
dagger list
```
The `list` command shows the current environments defined:
```bash
local ...todoapp/.dagger/env/local
```
### Define Input Values per Environment
```shell
dagger input list
```
Our Dagger plan includes a number of references to `dagger.#Input` which inform the Dagger engine that the concrete value should be pulled from inputs. While some things such as the registry target we saw above can be expressed purely in CUE, others such as directories, secrets, and sockets are required to be explicitly defined as _inputs_ to ensure security. If Dagger allowed such things to be stated in CUE, the entire package system could become a source of attacks.
```text
Input Value Set by user Description
app.source dagger.#Artifact false Application source code
```
List the inputs Dagger is aware of according to our plan:
```shell
dagger -e local input dir app.source ./app
dagger -e local input list
```
You should see the following output:
```bash
Input Value Set by user Description
app.source dagger.#Artifact false Application source code
todoapp.socket struct false Mount local docker socket
```
Notice that `Set by user` is false for both, because we have not yet provided Dagger with those values.
Let&rsquo;s provide them now:
```shell
dagger -e local input socket todoapp.socket /var/run/docker.sock
dagger -e local input dir app.source ./
```
Now let's replay the `dagger input list` command:
```bash
Input Value Set by user Description
app.source dagger.#Artifact true Application source code
todoapp.socket struct true Mount local docker socket
```
Notice that Dagger now reports that both inputs have been set.
### Deploy the Appplication
With our plan in place, our environment set, and our inputs defined we can deploy the application:
```bash
dagger up
```
Once complete you should get logs, and a final output like this:
```bash
Output Value Description
app.build struct Build output directory
push.ref "localhost:5000/todoapp:latest@sha256:<hash>" Image ref
push.digest "sha256:<hash>" Image digest
todoapp.ref "localhost:5000/todoapp:latest@sha256:<hash>" Image reference (e.g: nginx:alpine)
todoapp.run.env.IMAGE_REF "localhost:5000/todoapp:latest@sha256:<hash>" -
```
Congratulations! You&rsquo;ve deployed your first Dagger plan! You can now open [http://localhost:8080](http://localhost:8080) in your browser!