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​
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.
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
- TravisCI
- CircleCI
- GitLab
- Jenkins
- Tekton
- AzurePipelines
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 }}
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
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
.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.232
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-cue/install.sh | VERSION="$DAGGER_VERSION" 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
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"]
}
}
}
}
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
:
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
'''
}
}
}
}
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
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.
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.