From 216686c7ec1fc4521d8f31d3a5b81fabb0c98679 Mon Sep 17 00:00:00 2001 From: Tihomir Jovicic Date: Thu, 15 Jul 2021 11:29:30 +0200 Subject: [PATCH 1/3] Add doc on how to create packages Signed-off-by: Tihomir Jovicic --- docs/learn/109-packages.md | 134 +++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 docs/learn/109-packages.md diff --git a/docs/learn/109-packages.md b/docs/learn/109-packages.md new file mode 100644 index 00000000..0cd1bd0b --- /dev/null +++ b/docs/learn/109-packages.md @@ -0,0 +1,134 @@ +# Dagger 109: creating packages + +This tutorial illustrates how to create new packages, manually distribute them among your applications and contribute to +the Dagger stdlib packages. + +## Creating your own package + +### Initializing workspace + +Create an empty directory for your new Dagger workspace: + +```shell +mkdir workspace +cd workspace +``` + +As described in the previous tutorials, initialize your Dagger workspace: + +```shell +dagger init +``` + +That will create 2 directories: `.dagger` and `cue.mod` where our package will reside: + +```shell +. +├── cue.mod +│ ├── module.cue +│ ├── pkg +│ └── usr +├── .dagger +│ └── env +``` + +### Writing the package + +Now that you've initialized your workspace it's time to write a simple package. Package name usually starts with a +domain name (as in Go) followed with a descriptive name. In this example we will use my Github domain name and call our +package `echo` because it will print a single line to stdout. + +```shell +mkdir -p cue.mod/pkg/github.com/tjovicic/echo +``` + +Let's write the package logic. It will spin up an alpine container and print out `Hello` to stdout: + +```shell +touch cue.mod/pkg/github.com/tjovicic/echo/source.cue +``` + +```cue title="cue.mod/pkg/github.com/tjovicic/echo/source.cue" +package echo + +import ( + "alpha.dagger.io/alpine" + "alpha.dagger.io/os" +) + +ctr: os.#Container & { + image: alpine.#Image & { + package: { + bash: "=~5.1" + } + } + + command: "echo Hello" +} +``` + +### Running the package + +Now that you've successfully created a package, let's run it in a new environment. Create a new environment using the +new `echo` package. + +```shell +dagger new staging -p github.com/tjovicic/echo +``` + +Run it: + +```shell +dagger up -e staging +``` + +At the end of the output you should see `Hello` printed out: + +```shell +11:09AM INF system | starting buildkit version=v0.8.3 +WARN[0003] commandConn.CloseWrite: commandconn: failed to wait: signal: terminated +WARN[0003] commandConn.CloseRead: commandconn: failed to wait: signal: terminated +WARN[0003] commandConn.CloseWrite: commandconn: failed to wait: signal: terminated +11:09AM INF ctr | computing +11:09AM INF ctr.#up[0].from | #5 0.080 fetch https://dl-cdn.alpinelinux.org/alpine/v3.13/main/x86_64/APKINDEX.tar.gz +11:09AM INF ctr.#up[0].from | #5 0.612 fetch https://dl-cdn.alpinelinux.org/alpine/v3.13/community/x86_64/APKINDEX.tar.gz +11:09AM INF ctr.#up[0].from | #5 1.094 (1/4) Installing ncurses-terminfo-base (6.2_p20210109-r0) +11:09AM INF ctr.#up[0].from | #5 1.149 (2/4) Installing ncurses-libs (6.2_p20210109-r0) +11:09AM INF ctr.#up[0].from | #5 1.273 (3/4) Installing readline (8.1.0-r0) +11:09AM INF ctr.#up[0].from | #5 1.361 (4/4) Installing bash (5.1.0-r0) +11:09AM INF ctr.#up[0].from | #5 1.534 Executing bash-5.1.0-r0.post-install +11:09AM INF ctr.#up[0].from | #5 1.541 Executing busybox-1.32.1-r6.trigger +11:09AM INF ctr.#up[0].from | #5 1.554 OK: 8 MiB in 18 packages +11:09AM INF ctr | #6 0.110 Hello +11:09AM INF ctr | completed duration=5.4s +Output Value Description +``` + +## Manually distributing packages + +You've probably guessed this package isn't tied to just your workspace. You can easily copy/paste it into any number +of different workspaces and use it as we've showed above. + +```shell +mkdir -p /my-new-workspace/cue.mod/pkg/github.com/tjovicic/echo +cp ./cue.mod/pkg/github.com/tjovicic/echo/source.cue /my-new-workspace/cue.mod/pkg/github.com/tjovicic/echo +``` + +## Contributing to Dagger stdlib + +Our [stdlib](https://github.com/dagger/dagger/tree/main/stdlib) has many useful packages that you can use. +You've probably seen it when you've initialized your workspace: + +```shell +. +├── cue.mod +│ ├── module.cue +│ ├── pkg +│ │ ├── alpha.dagger.io +│ │ └── .gitignore +│ └── usr +``` + +We are still a small community and are constantly looking for new contributors that will work with us improve this +amazing project. If you feel like we are missing a package or want to improve an existing one, please start with our +[contributing docs](https://github.com/dagger/dagger/blob/main/CONTRIBUTING.md) and open a PR. From 3137e720574110adf7534abcedaa52056649bae0 Mon Sep 17 00:00:00 2001 From: Tihomir Jovicic Date: Fri, 16 Jul 2021 10:14:53 +0200 Subject: [PATCH 2/3] Replacing package example with CloudRun definition Signed-off-by: Tihomir Jovicic --- docs/learn/109-packages.md | 103 +++++++++++++++++++++++-------------- 1 file changed, 65 insertions(+), 38 deletions(-) diff --git a/docs/learn/109-packages.md b/docs/learn/109-packages.md index 0cd1bd0b..1634d937 100644 --- a/docs/learn/109-packages.md +++ b/docs/learn/109-packages.md @@ -35,45 +35,82 @@ That will create 2 directories: `.dagger` and `cue.mod` where our package will r ### Writing the package Now that you've initialized your workspace it's time to write a simple package. Package name usually starts with a -domain name (as in Go) followed with a descriptive name. In this example we will use my Github domain name and call our -package `echo` because it will print a single line to stdout. +domain name (as in Go) followed with a descriptive name. In this example we reuse the Cloud Run example and create a +package from it. ```shell -mkdir -p cue.mod/pkg/github.com/tjovicic/echo +mkdir -p cue.mod/pkg/github.com/tjovicic/gcpcloudrun ``` -Let's write the package logic. It will spin up an alpine container and print out `Hello` to stdout: +Let's write the package logic. It is basically what we've seen in the 106-cloudrun example: ```shell -touch cue.mod/pkg/github.com/tjovicic/echo/source.cue +touch cue.mod/pkg/github.com/tjovicic/gcpcloudrun/source.cue ``` -```cue title="cue.mod/pkg/github.com/tjovicic/echo/source.cue" -package echo +```cue title="cue.mod/pkg/github.com/tjovicic/gcpcloudrun/source.cue" +package gcpcloudrun import ( - "alpha.dagger.io/alpine" - "alpha.dagger.io/os" + "alpha.dagger.io/dagger" + "alpha.dagger.io/docker" + "alpha.dagger.io/gcp" + "alpha.dagger.io/gcp/cloudrun" + "alpha.dagger.io/gcp/gcr" ) -ctr: os.#Container & { - image: alpine.#Image & { - package: { - bash: "=~5.1" - } +#Run: { + // Source code of the sample application + src: dagger.#Artifact & dagger.#Input + + // GCR full image name + imageRef: string & dagger.#Input + + image: docker.#Build & { + source: src } - command: "echo Hello" + gcpConfig: gcp.#Config + + creds: gcr.#Credentials & { + config: gcpConfig + } + + push: docker.#Push & { + target: imageRef + source: image + auth: { + username: creds.username + secret: creds.secret + } + } + + deploy: cloudrun.#Service & { + config: gcpConfig + image: push.ref + } } ``` ### Running the package -Now that you've successfully created a package, let's run it in a new environment. Create a new environment using the -new `echo` package. +Now that you've successfully created a package, let's run it in a new environment. Create a new test package using +our reusable `gcpcloudrun`: ```shell -dagger new staging -p github.com/tjovicic/echo +mkdir test + +cat > test/source.cue << EOF +package test + +import ( + "github.com/tjovicic/gcpcloudrun" +) + +run: gcpcloudrun.#Run +EOF + +dagger new staging -p ./test ``` Run it: @@ -82,26 +119,16 @@ Run it: dagger up -e staging ``` -At the end of the output you should see `Hello` printed out: +You should see a familiar output: ```shell -11:09AM INF system | starting buildkit version=v0.8.3 -WARN[0003] commandConn.CloseWrite: commandconn: failed to wait: signal: terminated -WARN[0003] commandConn.CloseRead: commandconn: failed to wait: signal: terminated -WARN[0003] commandConn.CloseWrite: commandconn: failed to wait: signal: terminated -11:09AM INF ctr | computing -11:09AM INF ctr.#up[0].from | #5 0.080 fetch https://dl-cdn.alpinelinux.org/alpine/v3.13/main/x86_64/APKINDEX.tar.gz -11:09AM INF ctr.#up[0].from | #5 0.612 fetch https://dl-cdn.alpinelinux.org/alpine/v3.13/community/x86_64/APKINDEX.tar.gz -11:09AM INF ctr.#up[0].from | #5 1.094 (1/4) Installing ncurses-terminfo-base (6.2_p20210109-r0) -11:09AM INF ctr.#up[0].from | #5 1.149 (2/4) Installing ncurses-libs (6.2_p20210109-r0) -11:09AM INF ctr.#up[0].from | #5 1.273 (3/4) Installing readline (8.1.0-r0) -11:09AM INF ctr.#up[0].from | #5 1.361 (4/4) Installing bash (5.1.0-r0) -11:09AM INF ctr.#up[0].from | #5 1.534 Executing bash-5.1.0-r0.post-install -11:09AM INF ctr.#up[0].from | #5 1.541 Executing busybox-1.32.1-r6.trigger -11:09AM INF ctr.#up[0].from | #5 1.554 OK: 8 MiB in 18 packages -11:09AM INF ctr | #6 0.110 Hello -11:09AM INF ctr | completed duration=5.4s -Output Value Description +9:32AM ERR system | required input is missing input=run.src +9:32AM ERR system | required input is missing input=run.imageRef +9:32AM ERR system | required input is missing input=run.gcpConfig.region +9:32AM ERR system | required input is missing input=run.gcpConfig.project +9:32AM ERR system | required input is missing input=run.gcpConfig.serviceKey +9:32AM ERR system | required input is missing input=run.deploy.name +9:32AM FTL system | some required inputs are not set, please re-run with `--force` if you think it's a mistake missing=0s ``` ## Manually distributing packages @@ -110,8 +137,8 @@ You've probably guessed this package isn't tied to just your workspace. You can of different workspaces and use it as we've showed above. ```shell -mkdir -p /my-new-workspace/cue.mod/pkg/github.com/tjovicic/echo -cp ./cue.mod/pkg/github.com/tjovicic/echo/source.cue /my-new-workspace/cue.mod/pkg/github.com/tjovicic/echo +mkdir -p /my-new-workspace/cue.mod/pkg/github.com/tjovicic/gcpcloudrun +cp ./cue.mod/pkg/github.com/tjovicic/gcpcloudrun/source.cue /new-workspace/cue.mod/pkg/github.com/tjovicic/gcpcloudrun ``` ## Contributing to Dagger stdlib From 203f893f7c2048e4fb305fbbaca93d5ae75a9e8f Mon Sep 17 00:00:00 2001 From: Tihomir Jovicic Date: Fri, 16 Jul 2021 10:16:38 +0200 Subject: [PATCH 3/3] Fix docs linting issues Signed-off-by: Tihomir Jovicic --- docs/learn/109-packages.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/learn/109-packages.md b/docs/learn/109-packages.md index 1634d937..b0817373 100644 --- a/docs/learn/109-packages.md +++ b/docs/learn/109-packages.md @@ -52,11 +52,11 @@ touch cue.mod/pkg/github.com/tjovicic/gcpcloudrun/source.cue package gcpcloudrun import ( - "alpha.dagger.io/dagger" - "alpha.dagger.io/docker" - "alpha.dagger.io/gcp" - "alpha.dagger.io/gcp/cloudrun" - "alpha.dagger.io/gcp/gcr" + "alpha.dagger.io/dagger" + "alpha.dagger.io/docker" + "alpha.dagger.io/gcp" + "alpha.dagger.io/gcp/cloudrun" + "alpha.dagger.io/gcp/gcr" ) #Run: { @@ -104,7 +104,7 @@ cat > test/source.cue << EOF package test import ( - "github.com/tjovicic/gcpcloudrun" + "github.com/tjovicic/gcpcloudrun" ) run: gcpcloudrun.#Run