Get Started with the Dagger CUE SDK

Introduction

This tutorial teaches you the basics of using Dagger with CUE. You will learn how to:

• Install the CUE SDK
• Use the CUE SDK to build and test an application locally
• Use the CUE SDK to build and deploy the application remotely

Requirements

This tutorial assumes that:

• You have a basic understanding of the CUE language. If not, read the CUE tutorial.
• You have Docker installed and running on the host system. If not, install Docker.

Step 1: Install the Dagger CUE SDK

tip

The dagger-cue CLI is available for installation on macOS, Linux, and Windows to run locally or in a CI environment.

Install the dagger-cue CLI following the steps below.

Step 2: Build, run and test locally

Everyone should be able to develop, test and run their application using a local pipeline. Having to commit and push in order to test a change slows down iteration. This step explains how to use the Dagger CUE SDK to configure a local pipeline to build, run and test an application.

Step 3: Build, run and test in a remote CI environment

Once you have the Dagger Engine running locally, it's easy to use Dagger with any CI environment (no migration required) to run the same Dagger pipelines. Any CI environment with Docker pre-installed works with Dagger out of the box.

Now that you are comfortable with the local CI/CD loop, the next step is to configure a production deployment of the application using a remote CI environment. This step will also deploy the build output to Netlify.

note

We started with CI environments that you told us you are using. If you cannot find your CI environment below, let us know via this GitHub discussion.

GitHub Actions

.github/workflows/todoapp.yml

name: todoapp

on:
  push:
    # Trigger this workflow only on commits pushed to the main branch
    branches:
      - main

# Dagger plan gets configured via client environment variables
env:
  # This needs to be unique across all of netlify.app
  APP_NAME: todoapp-dagger-europa
  NETLIFY_TEAM: dagger

jobs:
  dagger:
    runs-on: ubuntu-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v2

      # You need to run `dagger-cue project init` locally before and commit the cue.mod directory to the repository with its contents
      - name: Deploy to Netlify
        uses: dagger/dagger-for-github@v3
        # See all options at https://github.com/dagger/dagger-for-github
        with:
          version: 0.2
          # To pin external dependencies, you can use `project update github.com/[package-source]@v[n]`
          cmds: |
            project update
            do deploy
        env:
          # Get one from https://app.netlify.com/user/applications/personal
          NETLIFY_TOKEN: ${{ secrets.NETLIFY_TOKEN }}

TravisCI

.travis.yml

os: linux
arch: amd64
dist: bionic
language: minimal

env:
  global:
    - DAGGER_VERSION: 0.2.25
    - DAGGER_LOG_FORMAT: plain
    - DAGGER_CACHE_PATH: .dagger-cache

services:
  - docker

install:
  - |
    # Installing dagger-cue
    cd /usr/local
    curl -L https://dl.dagger.io/dagger/install.sh | sudo sh
    cd -

stages:
  - name: build
    if: type IN (push, pull_request)

jobs:
  include:
    - stage: build
      env:
        - TASK: "dagger-cue do build"
      before_script:
        - dagger-cue project update
      script:
        - dagger-cue do build

CircleCI

.circleci/config.yml

version: 2.1

jobs:
  install-and-run-dagger:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - setup_remote_docker:
          version: "20.10.14"
      - run:
          name: "Install the Dagger Engine"
          command: |
            cd /usr/local
            wget -O - https://dl.dagger.io/dagger/install.sh | sudo sh
            cd -
      - run:
          name: "Run the Dagger Engine"
          command: |
            dagger-cue do build --log-format plain

workflows:
  dagger-workflow:
    jobs:
      - install-and-run-dagger

GitLab

.gitlab-ci.yml

.docker:
  image: docker:${DOCKER_VERSION}-git
  services:
    - docker:${DOCKER_VERSION}-dind
  variables:
    # See https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#docker-in-docker-with-tls-enabled-in-the-docker-executor
    DOCKER_HOST: tcp://docker:2376

    DOCKER_TLS_VERIFY: "1"
    DOCKER_TLS_CERTDIR: "/certs"
    DOCKER_CERT_PATH: "/certs/client"

    # Faster than the default, apparently
    DOCKER_DRIVER: overlay2

    DOCKER_VERSION: "20.10"

.dagger:
  extends: [.docker]
  variables:
    DAGGER_VERSION: 0.2.25
    DAGGER_LOG_FORMAT: plain
    DAGGER_CACHE_PATH: .dagger-cache

    ARGS: ""
  cache:
    key: dagger-${CI_JOB_NAME}
    paths:
      - ${DAGGER_CACHE_PATH}
  before_script:
    - |
      # install dagger
      cd /usr/local
      wget -O - https://dl.dagger.io/dagger/install.sh | sh
      cd -

      dagger-cue version
  script:
    - dagger-cue project update
    - |
      dagger-cue \
          do \
          --cache-from type=local,src=${DAGGER_CACHE_PATH} \
          --cache-to type=local,mode=max,dest=${DAGGER_CACHE_PATH} \
          ${ARGS}

build:
  extends: [.dagger]
  variables:
    ARGS: build

caution

Gitlab's template above is using a Docker-in-Docker service. No UNIX socket (/var/run/docker.sock) will be available on the host unless you specifically mount it.

The recommended way of interacting with the docker daemon using the universe.dagger.io/docker/cli package is to rely on the TCP connection:

package example

import (
  "dagger.io/dagger"

  "universe.dagger.io/docker/cli"
)

dagger.#Plan & {
  client: {
    filesystem: "/certs/client": read: contents: dagger.#FS
    env: DOCKER_PORT_2376_TCP: string
  }
  actions: {
    test: cli.#Run & {
      host:   client.env.DOCKER_PORT_2376_TCP
      always: true
      certs: client.filesystem."/certs/client".read.contents
      command: {
        name: "docker"
        args: ["info"]
      }
    }
  }
}

Jenkins

With docker client and dagger-cue installed on your Jenkins agent, a Docker host available (can be docker:dind), and agents labeled in Jenkins with dagger-cue:

Jenkinsfile

pipeline {
  agent { label 'dagger' }

  environment {
    //https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#handling-credentials
    //DH_CREDS              = credentials('jenkins-dockerhub-creds')
    //AWS_ACCESS_KEY_ID     = credentials('jenkins-aws-secret-key-id')
    //AWS_SECRET_ACCESS_KEY = credentials('jenkins-aws-secret-access-key')
    //https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#using-environment-variables
    GREETING = "Hello there, Jenkins! Hello"
  }
  stages {
    stage("do") {
      steps {
        //this example uses https://github.com/jpadams/helloworld-dagger-jenkins
        //if you're using your own Dagger plan, substitute your action name for 'hello'
        //e.g. 'build' or 'push' or whatever you've created!
        sh '''
            dagger-cue do hello --log-format=plain
        '''
      }
    }
  }
}

Tekton

tekton/tasks/todo-app.yaml

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: dagger-cue
spec:
  description: |
    Execute a dagger action from a git repo.
  params:
    - name: dagger-version
      type: string
      description: The dagger version to run.
    - name: dagger-action
      type: string
      description: The dagger action to execute.
    - name: repo-url
      type: string
      description: The git repository URL to clone from.
    - name: app-dir
      type: string
      description: The path to access the app dagger codebase within the repository.
    - name: netlify-site-name
      type: string
      description: The Netlify site name. Unique value among Netlify sites.
    - name: netlify-team
      type: string
      description: The Netlify team to deploy to.
  workspaces:
    - name: shared-data
      description: |
        This workspace will receive the cloned git repo and be passed
        to the next Task.

  tasks:
    - name: fetch-repo
      taskRef:
        name: git-clone
      workspaces:
        - name: output
          workspace: shared-data
      params:
        - name: url
          value: $(params.repo-url)
        - name: revision
          value: $(params.dagger-version)

    - name: dagger-do
      runAfter: ["fetch-repo"] # Wait until the clone is done before deploying the app.
      workspaces:
        - name: source
          workspace: shared-data
      params:
        - name: dagger-version
          value: $(params.dagger-version)
        - name: dagger-action
          value: $(params.dagger-action)
        - name: app-dir
          value: $(params.app-dir)
        - name: netlify-site-name
          value: $(params.netlify-site-name)
        - name: netlify-team
          value: $(params.netlify-team)
      taskSpec:
        workspaces:
          - name: source
        params:
          - name: dagger-version
          - name: dagger-action
          - name: app-dir
          - name: netlify-site-name
          - name: netlify-team
        steps:
          - image: docker:20.10.13
            name: run-dagger-action
            workingDir: "$(workspaces.source.path)/$(params.app-dir)"
            script: |
              #!/usr/bin/env sh

              # Install dagger
              # Could be removed by using an official muli-arch dagger.io image
              arch=$(uname -m)
              case $arch in
                x86_64) arch="amd64" ;;
                aarch64) arch="arm64" ;;
              esac

              wget -c https://github.com/dagger/dagger/releases/download/$(params.dagger-version)/dagger_$(params.dagger-version)_linux_${arch}.tar.gz  -O - |  \
              tar zxf - -C /usr/local/bin

              dagger-cue version
              dagger-cue do $(params.dagger-action)

            env:
              - name: APP_NAME
                value: $(params.netlify-site-name)
              - name: NETLIFY_TEAM
                value: $(params.netlify-team)
              - name: DAGGER_LOG_FORMAT
                value: plain
              # Get one from https://app.netlify.com/user/applications/personal
              # and save it as a generic kubernetes secret
              - name: NETLIFY_TOKEN
                valueFrom:
                  secretKeyRef:
                    name: netlify
                    key: token
            volumeMounts:
              - mountPath: /var/run/
                name: dind-socket
        sidecars:
          - image: docker:20.10.13-dind
            name: server
            securityContext:
              privileged: true
            volumeMounts:
              - mountPath: /var/run/
                name: dind-socket
        volumes:
          - name: dind-socket
            emptyDir: {}
---
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: deploy-todo-app
spec:
  pipelineRef:
    name: dagger
  workspaces:
    - name: shared-data
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 1Gi
  params:
    - name: dagger-version
      value: v0.2.6
    - name: dagger-action
      value: deploy
    - name: repo-url
      value: https://github.com/dagger/todoapp.git
    - name: netlify-site-name
      value: todoapp-dagger-europa
    - name: netlify-team
      value: dagger

AzurePipelines

Azure Pipelines do not currently support a native task; however, it is still possible to run Dagger on Mac, Linux or Windows hosted agent.

To use Dagger on Mac or Linux hosted agent you can use the following pipeline file.

azure-pipelines.yml

trigger:
  branches:
    include:
    # Trigger this pipeline only on commits pushed to the main branch
    - 'main'

pool:
  # Specifying which AzureDevOps hosted build pool to use
  vmImage: 'ubuntu-latest'

variables:
  # Specifying which version of dagger-cue to install
  # This value is read from the install script
  DAGGER_VERSION: 0.2.19

jobs:
- job: dagger-cue
  steps:
  - script: |
      cd /usr/local
      curl -L https://dl.dagger.io/dagger/install.sh | DAGGER_VERSION=$(DAGGER_VERSION) sh
    displayName: Install Dagger $(DAGGER_VERSION)
  - script: |
      dagger-cue project update
      dagger-cue do ci
    displayName: Run ci action

Since you cannot use the install.sh script on a Windows hosted agent, you will need to update the install task to:

- task: ChocolateyCommand@0
  inputs:
    command: "install"
    installPackageId: "dagger-cue"
    installPackageVersion: "$(DAGGER_VERSION)"
  displayName: Install Dagger $(DAGGER_VERSION)

Conclusion

This tutorial introduced you to the Dagger CUE SDK. It explained how to install the SDK and use it to build, test and deploy an application locally and remotely. It also provided code samples for common CI environments.

Use the Guides and SDK Reference to learn more about the Dagger CUE SDK.