dagger/docs/learn/109-packages.md

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:

mkdir workspace
cd workspace

As described in the previous tutorials, initialize your Dagger workspace:

dagger init

That will create 2 directories: .dagger and cue.mod where our package will reside:

.
├── 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 reuse the Cloud Run example and create a package from it.

mkdir -p cue.mod/pkg/github.com/tjovicic/gcpcloudrun

Let's write the package logic. It is basically what we've seen in the 106-cloudrun example:

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"
)

#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
  }

  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 test package using our reusable gcpcloudrun:

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:

dagger up -e staging

You should see a familiar output:

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

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.

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

Our stdlib has many useful packages that you can use. You've probably seen it when you've initialized your workspace:

.
├── 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 and open a PR.