hello-dagger/README.md

Hello Dagger

An example repo demonstrating Dagger.

What is Dagger?

Dagger is not a CI/CD Runner like GitHub Actions or Gitlab CI. It is an abstraction that uses and composes containers to run commands. Think of it as somewhere between just, nix, and writing custom programs for your build plus containers all over the place.

It exists as a cli tool which either starts a Dagger Engine locally or connects to an existing one (in the cloud). This engine runs as a container and runs all tasks inside the engine as a container as well. The cli tool communicates via GraphQL with the engine.

Besides the TUI, Dagger Cloud is a commercial offering that is basically a fancy add-on. It provides web-visualizations of errors during a dagger execution and of performance metrics (profiling), as well as some caching features.

The TUI and engine are published under the Apache 2 License and thus can be used free of charge.

Besides using containers, Dagger's main selling point is the ability to program tasks in high level languages like Go or Typescript instead of configuring them in json or yaml. Dagger provides a DSL-like API that reminds one of Dockerfile commands + FP (even though it isn't). Combined with the ecosystem of the base language nearly anything can be coded and containerized fairly easy.

Walkthrough

This repo uses mise / asdf for setup, see .tool-versions.

Initialize the existing repo with dagger:

dagger init --sdk=typescript --source=./dagger

Typescript is just one option to write the config in, Python and Go are also currently available with more to follow.

Note: For some reason it wants to create a LICENSE file...

LSPs should work properly out of the box as the dagger config is located in the ./dagger directory. When using TS this is a self-sufficient node/yarn project.

To get an overview of available functions to call:

dagger functions

Run a function:

dagger call build --source=.

This runs the build function defined in dagger/src/index.ts and passes . as the source parameter of that function.

Camel Case function names in the TS setup are available in Kebab Case on the shell (same applies for Go and Python). This does not only apply to your own declared functions but to all functions available on the returned data types.

this.build(source).asService().up({ ports: "8080:8080" });

becomes

dagger call build --source=. as-service up --ports=8080:8080

After running a dagger command the Dagger Engine stays alive as a local container waiting for the next call.