Cookbook

Filesystem

List host directory contents

The following code listing obtains a reference to the host working directory and lists the directory's contents.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    entries, err := client.Host().Directory(".").Entries(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(entries)
}

import { connect, Client } from "@dagger.io/dagger"

connect(
  async (client: Client) => {
    const entries = await client.host().directory(".").entries()
    console.log(entries)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger

async def main():
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        entries = await client.host().directory(".").entries()

    print(entries)

anyio.run(main)

Learn more

Get host directory with filters

The following code listing obtains a reference to the host working directory containing all files except *.txt files.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    os.WriteFile("foo.txt", []byte("1"), 0600)
    os.WriteFile("bar.txt", []byte("2"), 0600)
    os.WriteFile("baz.rar", []byte("3"), 0600)

    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    entries, err := client.Host().Directory(".", dagger.HostDirectoryOpts{
        Exclude: []string{"*.txt"},
    }).Entries(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(entries)
}

import { connect, Client } from "@dagger.io/dagger"
import * as fs from "fs"

const files = ["foo.txt", "bar.txt", "baz.rar"]
let count = 1

for (const file of files) {
  fs.writeFileSync(file, count.toString())
  count = count + 1
}

connect(
  async (client: Client) => {
    const entries = await client
      .host()
      .directory(".", { exclude: ["*.txt"] })
      .entries()
    console.log(entries)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger

async def main():
    for i, file in enumerate(["foo.txt", "bar.txt", "baz.rar"]):
        await (anyio.Path(".") / file).write_text(str(i + 1))

    cfg = dagger.Config(log_output=sys.stderr)

    async with dagger.Connection(cfg) as client:
        entries = await client.host().directory(".", exclude=["*.txt"]).entries()

    print(entries)

anyio.run(main)

The following code listing obtains a reference to the host working directory containing only *.rar files.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    os.WriteFile("foo.txt", []byte("1"), 0600)
    os.WriteFile("bar.txt", []byte("2"), 0600)
    os.WriteFile("baz.rar", []byte("3"), 0600)

    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    entries, err := client.Host().Directory(".", dagger.HostDirectoryOpts{
        Include: []string{"*.rar"},
    }).Entries(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(entries)
}

import { connect, Client } from "@dagger.io/dagger"
import * as fs from "fs"

const files = ["foo.txt", "bar.txt", "baz.rar"]
let count = 1

for (const file of files) {
  fs.writeFileSync(file, count.toString())
  count = count + 1
}

connect(
  async (client: Client) => {
    const entries = await client
      .host()
      .directory(".", { include: ["*.rar"] })
      .entries()
    console.log(entries)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger

async def main():
    for i, file in enumerate(["foo.txt", "bar.txt", "baz.rar"]):
        await (anyio.Path(".") / file).write_text(str(i + 1))

    cfg = dagger.Config(log_output=sys.stderr)

    async with dagger.Connection(cfg) as client:
        entries = await client.host().directory(".", include=["*.rar"]).entries()

    print(entries)

anyio.run(main)

The following code listing obtains a reference to the host working directory containing all files except *.rar files.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    os.WriteFile("foo.txt", []byte("1"), 0600)
    os.WriteFile("bar.txt", []byte("2"), 0600)
    os.WriteFile("baz.rar", []byte("3"), 0600)

    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    entries, err := client.Host().Directory(".", dagger.HostDirectoryOpts{
        Include: []string{"*.*"},
        Exclude: []string{"*.rar"},
    }).Entries(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(entries)
}

import { connect, Client } from "@dagger.io/dagger"
import * as fs from "fs"

const files = ["foo.txt", "bar.txt", "baz.rar"]
let count = 1

for (const file of files) {
  fs.writeFileSync(file, count.toString())
  count = count + 1
}

connect(
  async (client: Client) => {
    const entries = await client
      .host()
      .directory(".", { include: ["*.*"], exclude: ["*.rar"] })
      .entries()
    console.log(entries)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    for i, file in enumerate(["foo.txt", "bar.txt", "baz.rar"]):
        await (anyio.Path(".") / file).write_text(str(i + 1))

    cfg = dagger.Config(log_output=sys.stderr)

    async with dagger.Connection(cfg) as client:
        entries = (
            await client.host()
            .directory(".", exclude=["*.rar"], include=["*.*"])
            .entries()
        )

    print(entries)


anyio.run(main)

Learn more

Mount and read host directory in container

The following code listing mounts a host directory in a container at the /host container path and then reads the contents of the mounted directory.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    contents, err := client.Container().
        From("alpine:latest").
        WithDirectory("/host", client.Host().Directory(".")).
        WithExec([]string{"ls", "/host"}).
        Stdout(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(contents)
}

import { connect, Client } from "@dagger.io/dagger"

connect(
  async (client: Client) => {
    const contents = await client
      .container()
      .from("alpine:latest")
      .withDirectory("/host", client.host().directory("."))
      .withExec(["ls", "/host"])
      .stdout()

    console.log(contents)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        out = await (
            client.container()
            .from_("alpine:latest")
            .with_directory("/host", client.host().directory("."))
            .with_exec(["ls", "/host"])
            .stdout()
        )

    print(out)


anyio.run(main)

Mount and write to host directory from container

The following code listing shows how to mount a host directory in a container at the /host container path, write a file to it, and then export the modified directory back to the host:

note

Modifications made to a host directory mounted in a container do not appear on the host. Data flows only one way between Dagger operations, because they are connected in a DAG. To write modifications back to the host directory, you must explicitly export the directory back to the host filesystem.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    contents, err := client.Container().
        From("alpine:latest").
        WithDirectory("/host", client.Host().Directory("/tmp/sandbox")).
        WithExec([]string{"/bin/sh", "-c", `echo foo > /host/bar`}).
        Directory("/host").
        Export(ctx, "/tmp/sandbox")
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(contents)
}

import { connect, Client } from "@dagger.io/dagger"

connect(
  async (client: Client) => {
    const contents = await client
      .container()
      .from("alpine:latest")
      .withDirectory("/host", client.host().directory("/tmp/sandbox"))
      .withExec(["/bin/sh", "-c", `echo foo > /host/bar`])
      .directory("/host")
      .export("/tmp/sandbox")

    console.log(contents)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        out = await (
            client.container()
            .from_("alpine:latest")
            .with_directory("/host", client.host().directory("/tmp/sandbox"))
            .with_exec(["/bin/sh", "-c", "`echo foo > /host/bar`"])
            .directory("/host")
            .export("/tmp/sandbox")
        )

    print(out)


anyio.run(main)

Learn more

Add Git repository as directory to container

The following code listing adds a remote Git repository branch to a container as a directory at the /src container path and then executes a command in the container to list the directory contents.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    // create Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // get repository at specified branch
    project := client.
        Git("https://github.com/dagger/dagger").
        Branch("main").
        Tree()

    // return container with repository
    // at /src path
    contents, err := client.Container().
        From("alpine:latest").
        WithDirectory("/src", project).
        WithWorkdir("/src").
        WithExec([]string{"ls", "/src"}).
        Stdout(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(contents)
}

import { connect } from "@dagger.io/dagger"

// create Dagger client
connect(
  async (client) => {
    // get repository at specified branch
    const project = client
      .git("https://github.com/dagger/dagger")
      .branch("main")
      .tree()

    // return container with repository
    // at /src path
    const contents = await client
      .container()
      .from("alpine:latest")
      .withDirectory("/src", project)
      .withWorkdir("/src")
      .withExec(["ls", "/src"])
      .stdout()

    console.log(contents)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # get repository at specified branch
        project = client.git("https://github.com/dagger/dagger").branch("main").tree()

        # return container with repository
        # at /src path
        out = await (
            client.container()
            .from_("alpine:latest")
            .with_directory("/src", project)
            .with_workdir("/src")
            .with_exec(["ls", "/src"])
            .stdout()
        )

    print(out)


anyio.run(main)

Add Git repository as directory to container with filters

The following code listing adds a remote Git repository branch as a directory at the /src container path, excluding *.md files.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    // create Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // get repository at specified branch
    project := client.
        Git("https://github.com/dagger/dagger").
        Branch("main").
        Tree()

    // return container with repository
    // at /src path
    // excluding *.md files
    contents, err := client.Container().
        From("alpine:latest").
        WithDirectory("/src", project, dagger.ContainerWithDirectoryOpts{
            Exclude: []string{"*.md"},
        }).
        WithWorkdir("/src").
        WithExec([]string{"ls", "/src"}).
        Stdout(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(contents)
}

import { connect } from "@dagger.io/dagger"

// create Dagger client
connect(
  async (client) => {
    // get repository at specified branch
    const project = client
      .git("https://github.com/dagger/dagger")
      .branch("main")
      .tree()

    // return container with repository
    // at /src path
    // excluding *.md files
    const contents = await client
      .container()
      .from("alpine:latest")
      .withDirectory("/src", project, { exclude: ["*.md"] })
      .withWorkdir("/src")
      .withExec(["ls", "/src"])
      .stdout()

    console.log(contents)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # get repository at specified branch
        project = client.git("https://github.com/dagger/dagger").branch("main").tree()

        # return container with repository
        # at /src path
        # excluding *.md files
        out = await (
            client.container()
            .from_("alpine:latest")
            .with_directory("/src", project, exclude=["*.md"])
            .with_workdir("/src")
            .with_exec(["ls", "/src"])
            .stdout()
        )

    print(out)


anyio.run(main)

The following code listing adds a remote Git repository branch as a directory at the /src container path, including only *.md files.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    // create Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // get repository at specified branch
    project := client.
        Git("https://github.com/dagger/dagger").
        Branch("main").
        Tree()

    // return container with repository
    // at /src path
    // including only *.md files
    contents, err := client.Container().
        From("alpine:latest").
        WithDirectory("/src", project, dagger.ContainerWithDirectoryOpts{
            Include: []string{"*.md"},
        }).
        WithWorkdir("/src").
        WithExec([]string{"ls", "/src"}).
        Stdout(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(contents)
}

import { connect } from "@dagger.io/dagger"

// create Dagger client
connect(
  async (client) => {
    // get repository at specified branch
    const project = client
      .git("https://github.com/dagger/dagger")
      .branch("main")
      .tree()

    // return container with repository
    // at /src path
    // including only *.md files
    const contents = await client
      .container()
      .from("alpine:latest")
      .withDirectory("/src", project, { include: ["*.md"] })
      .withWorkdir("/src")
      .withExec(["ls", "/src"])
      .stdout()

    console.log(contents)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # get repository at specified branch
        project = client.git("https://github.com/dagger/dagger").branch("main").tree()

        # return container with repository
        # at /src path
        # including only *.md files
        out = await (
            client.container()
            .from_("alpine:latest")
            .with_directory("/src", project, include=["*.md"])
            .with_workdir("/src")
            .with_exec(["ls", "/src"])
            .stdout()
        )

    print(out)


anyio.run(main)

The following code listing adds a remote Git repository branch as a directory at the /src container path, including all *.md files except README.md.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "dagger.io/dagger"
)

func main() {
    // create Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // get repository at specified branch
    project := client.
        Git("https://github.com/dagger/dagger").
        Branch("main").
        Tree()

    // return container with repository
    // at /src path
    // include all *.md files except README.md
    contents, err := client.Container().
        From("alpine:latest").
        WithDirectory("/src", project, dagger.ContainerWithDirectoryOpts{
            Include: []string{"*.md"},
            Exclude: []string{"README.md"},
        }).
        WithWorkdir("/src").
        WithExec([]string{"ls", "/src"}).
        Stdout(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(contents)
}

import { connect } from "@dagger.io/dagger"

// create Dagger client
connect(
  async (client) => {
    // get repository at specified branch
    const project = client
      .git("https://github.com/dagger/dagger")
      .branch("main")
      .tree()

    // return container with repository
    // at /src path
    // include all *.md files except README.md
    const contents = await client
      .container()
      .from("alpine:latest")
      .withDirectory("/src", project, {
        include: ["*.md"],
        exclude: ["README.md"],
      })
      .withWorkdir("/src")
      .withExec(["ls", "/src"])
      .stdout()

    console.log(contents)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # get repository at specified branch
        project = client.git("https://github.com/dagger/dagger").branch("main").tree()

        # return container with repository
        # at /src path
        # include all *.md files except README.md
        out = await (
            client.container()
            .from_("alpine:latest")
            .with_directory("/src", project, include=["*.md"], exclude=["README.md"])
            .with_workdir("/src")
            .with_exec(["ls", "/src"])
            .stdout()
        )

    print(out)


anyio.run(main)

Builds

Perform multi-stage build

The following code listing performs a multi-stage build.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    // create dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // get host directory
    project := client.Host().Directory(".")

    // build app
    builder := client.Container().
        From("golang:latest").
        WithDirectory("/src", project).
        WithWorkdir("/src").
        WithEnvVariable("CGO_ENABLED", "0").
        WithExec([]string{"go", "build", "-o", "myapp"})

    // publish binary on alpine base
    prodImage := client.Container().
        From("alpine").
        WithFile("/bin/myapp", builder.File("/src/myapp")).
        WithEntrypoint([]string{"/bin/myapp"})

    addr, err := prodImage.Publish(ctx, "localhost:5000/multistage")
    if err != nil {
        panic(err)
    }

    fmt.Println(addr)
}

import { connect, Client } from "@dagger.io/dagger"

connect(
  async (client: Client) => {
    // get host directory
    const project = client.host().directory(".")

    // build app
    const builder = client
      .container()
      .from("golang:latest")
      .withDirectory("/src", project)
      .withWorkdir("/src")
      .withEnvVariable("CGO_ENABLED", "0")
      .withExec(["go", "build", "-o", "myapp"])

    // publish binary on alpine base
    const prod = client
      .container()
      .from("alpine")
      .withFile("/bin/myapp", builder.file("/src/myapp"))
      .withEntrypoint(["/bin/myapp"])
    const addr = await prod.publish("localhost:5000/multistage")

    console.log(addr)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # get host directory
        project = client.host().directory(".")

        # build app
        builder = (
            client.container()
            .from_("golang:latest")
            .with_directory("/src", project)
            .with_workdir("/src")
            .with_env_variable("CGO_ENABLED", "0")
            .with_exec(["go", "build", "-o", "myapp"])
        )

        # publish binary on alpine base
        prod = (
            client.container()
            .from_("alpine")
            .with_file("/bin/myapp", builder.file("/src/myapp"))
            .with_entrypoint(["/bin/myapp"])
        )
        addr = await prod.publish("localhost:5000/multistage")

    print(addr)


anyio.run(main)

Learn more

Perform matrix build

The following code listing builds separate images for multiple OS and CPU architecture combinations.

Go
Node.js
Python

// Create a multi-build pipeline for a Go application.
package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    println("Building with Dagger")

    // define build matrix
    geese := []string{"linux", "darwin"}
    goarches := []string{"amd64", "arm64"}

    ctx := context.Background()
    // initialize dagger client
    c, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }

    // get reference to the local project
    src := c.Host().Directory(".")

    // create empty directory to put build outputs
    outputs := c.Directory()

    golang := c.Container().
        // get golang image
        From("golang:latest").
        // mount source code into golang image
        WithDirectory("/src", src).
        WithWorkdir("/src")

    for _, goos := range geese {
        for _, goarch := range goarches {
            // create a directory for each OS and architecture
            path := fmt.Sprintf("build/%s/%s/", goos, goarch)

            build := golang.
                // set GOARCH and GOOS in the build environment
                WithEnvVariable("GOOS", goos).
                WithEnvVariable("GOARCH", goarch).
                WithExec([]string{"go", "build", "-o", path})

            // add build to outputs
            outputs = outputs.WithDirectory(path, build.Directory(path))
        }
    }

    // write build artifacts to host
    ok, err := outputs.Export(ctx, ".")
    if err != nil {
        panic(err)
    }

    if !ok {
        panic("did not export files")
    }
}

import { connect } from "@dagger.io/dagger"

// Create a multi-build pipeline for a Go application.

// define build matrix
const oses = ["linux", "darwin"]
const arches = ["amd64", "arm64"]

// initialize dagger client
connect(
  async (client) => {
    console.log("Building with Dagger")

    // get reference to the local project
    const src = client.host().directory(".")

    // create empty directory to put build outputs
    var outputs = client.directory()

    const golang = client
      .container()
      // get golang image
      .from("golang:latest")
      // mount source code into golang image
      .withDirectory("/src", src)
      .withWorkdir("/src")

    for (const os of oses) {
      for (const arch of arches) {
        // create a directory for each OS and architecture
        const path = `build/${os}/${arch}/`

        const build = golang
          // set GOARCH and GOOS in the build environment
          .withEnvVariable("GOOS", os)
          .withEnvVariable("GOARCH", arch)
          .withExec(["go", "build", "-o", path])

        // add build to outputs
        outputs = outputs.withDirectory(path, build.directory(path))
      }
    }

    // write build artifacts to host
    await outputs.export(".")
  },
  { LogOutput: process.stderr }
)

"""Create a multi-build pipeline for a Go application."""

import itertools
import sys

import anyio

import dagger


async def main():
    print("Building with Dagger")

    # define build matrix
    oses = ["linux", "darwin"]
    arches = ["amd64", "arm64"]

    # initialize dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # get reference to the local project
        src = client.host().directory(".")

        # create empty directory to put build outputs
        outputs = client.directory()

        golang = (
            # get `golang` image
            client.container()
            .from_("golang:latest")
            # mount source code into `golang` image
            .with_directory("/src", src)
            .with_workdir("/src")
        )

        for goos, goarch in itertools.product(oses, arches):
            # create a directory for each OS and architecture
            path = f"build/{goos}/{goarch}/"

            build = (
                golang
                # set GOARCH and GOOS in the build environment
                .with_env_variable("GOOS", goos)
                .with_env_variable("GOARCH", goarch)
                .with_exec(["go", "build", "-o", path])
            )

            # add build to outputs
            outputs = outputs.with_directory(path, build.directory(path))

        # write build artifacts to host
        await outputs.export(".")


anyio.run(main)

Learn more

Build multi-arch image

The following code listing builds a single image for different CPU architectures using native emulation.

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

// the platforms to build for and push in a multi-platform image
var platforms = []dagger.Platform{
    "linux/amd64", // a.k.a. x86_64
    "linux/arm64", // a.k.a. aarch64
    "linux/s390x", // a.k.a. IBM S/390
}

// the container registry for the multi-platform image
const imageRepo = "localhost/testrepo:latest"

func main() {
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // the git repository containing code for the binary to be built
    gitRepo := client.Git("https://github.com/dagger/dagger.git").
        Branch("086862926433e19e1f24cd709e6165c36bdb2633").
        Tree()

    platformVariants := make([]*dagger.Container, 0, len(platforms))
    for _, platform := range platforms {
        // pull the golang image for this platform
        ctr := client.Container(dagger.ContainerOpts{Platform: platform})
        ctr = ctr.From("golang:1.20-alpine")

        // mount in source code
        ctr = ctr.WithDirectory("/src", gitRepo)

        // mount in an empty dir where the built binary will live
        ctr = ctr.WithDirectory("/output", client.Directory())

        // ensure the binary will be statically linked and thus executable
        // in the final image
        ctr = ctr.WithEnvVariable("CGO_ENABLED", "0")

        // build the binary and put the result at the mounted output
        // directory
        ctr = ctr.WithWorkdir("/src")
        ctr = ctr.WithExec([]string{
            "go", "build",
            "-o", "/output/dagger",
            "/src/cmd/dagger",
        })

        // select the output directory
        outputDir := ctr.Directory("/output")

        // wrap the output directory in a new empty container marked
        // with the same platform
        binaryCtr := client.
            Container(dagger.ContainerOpts{Platform: platform}).
            WithRootfs(outputDir)
        platformVariants = append(platformVariants, binaryCtr)
    }

    // publishing the final image uses the same API as single-platform
    // images, but now additionally specify the `PlatformVariants`
    // option with the containers built before.
    imageDigest, err := client.
        Container().
        Publish(ctx, imageRepo, dagger.ContainerPublishOpts{
            PlatformVariants: platformVariants,
            // Some registries may require explicit use of docker mediatypes
            // rather than the default OCI mediatypes
            // MediaTypes: dagger.Dockermediatypes,
        })
    if err != nil {
        panic(err)
    }
    fmt.Println("Pushed multi-platform image w/ digest: ", imageDigest)
}

Learn more

Build multi-arch image with cross-compilation

The following code listing builds a single image for different CPU architectures using cross-compilation.

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
    platformFormat "github.com/containerd/containerd/platforms"
)

var platforms = []dagger.Platform{
    "linux/amd64", // a.k.a. x86_64
    "linux/arm64", // a.k.a. aarch64
    "linux/s390x", // a.k.a. IBM S/390
}

// the container registry for the multi-platform image
const imageRepo = "localhost/testrepo:latest"

// util that returns the architecture of the provided platform
func architectureOf(platform dagger.Platform) string {
    return platformFormat.MustParse(string(platform)).Architecture
}

func main() {
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    gitRepo := client.Git("https://github.com/dagger/dagger.git").
        Branch("086862926433e19e1f24cd709e6165c36bdb2633").
        Tree()

    platformVariants := make([]*dagger.Container, 0, len(platforms))
    for _, platform := range platforms {
        // pull the golang image for the *host platform*. This is
        // accomplished by just not specifying a platform; the default
        // is that of the host.
        ctr := client.Container()
        ctr = ctr.From("golang:1.20-alpine")

        // mount in our source code
        ctr = ctr.WithDirectory("/src", gitRepo)

        // mount in an empty dir to put the built binary
        ctr = ctr.WithDirectory("/output", client.Directory())

        // ensure the binary will be statically linked and thus executable
        // in the final image
        ctr = ctr.WithEnvVariable("CGO_ENABLED", "0")

        // configure the go compiler to use cross-compilation targeting the
        // desired platform
        ctr = ctr.WithEnvVariable("GOOS", "linux")
        ctr = ctr.WithEnvVariable("GOARCH", architectureOf(platform))

        // build the binary and put the result at the mounted output
        // directory
        ctr = ctr.WithWorkdir("/src")
        ctr = ctr.WithExec([]string{
            "go", "build",
            "-o", "/output/dagger",
            "/src/cmd/dagger",
        })
        // select the output directory
        outputDir := ctr.Directory("/output")

        // wrap the output directory in a new empty container marked
        // with the platform
        binaryCtr := client.
            Container(dagger.ContainerOpts{Platform: platform}).
            WithRootfs(outputDir)
        platformVariants = append(platformVariants, binaryCtr)
    }

    // publishing the final image uses the same API as single-platform
    // images, but now additionally specify the `PlatformVariants`
    // option with the containers built before.
    imageDigest, err := client.
        Container().
        Publish(ctx, imageRepo, dagger.ContainerPublishOpts{
            PlatformVariants: platformVariants,
            // Some registries may require explicit use of docker mediatypes
            // rather than the default OCI mediatypes
            // MediaTypes: dagger.Dockermediatypes,
        })
    if err != nil {
        panic(err)
    }
    fmt.Println("published multi-platform image with digest", imageDigest)
}

Learn more

Build image from Dockerfile

The following code listing builds an image from a Dockerfile in the current working directory on the host.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "math"
    "math/rand"
    "os"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    // initialize Dagger client
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    contextDir := client.Host().Directory(".")

    ref, err := contextDir.
        DockerBuild().
        Publish(ctx, fmt.Sprintf("ttl.sh/hello-dagger-%.0f", math.Floor(rand.Float64()*10000000))) //#nosec
    if err != nil {
        panic(err)
    }

    fmt.Printf("Published image to :%s\n", ref)
}

import { connect } from "@dagger.io/dagger"

connect(
  async (client) => {
    // set build context
    const contextDir = client.host().directory(".")

    // build using Dockerfile
    // publish the resulting container to a registry
    const imageRef = await contextDir
      .dockerBuild()
      .publish("ttl.sh/hello-dagger-" + Math.floor(Math.random() * 10000000))
    console.log(`Published image to: ${imageRef}`)
  },
  { LogOutput: process.stderr }
)

import random
import sys

import anyio

import dagger


async def main():
    config = dagger.Config(log_output=sys.stdout)

    async with dagger.Connection(config) as client:
        # set build context
        context_dir = client.host().directory(".")

        # build using Dockerfile
        # publish the resulting container to a registry
        image_ref = await context_dir.docker_build().publish(
            f"ttl.sh/hello-dagger-{random.randrange(10 ** 8)}"
        )

    print(f"Published image to: {image_ref}")


anyio.run(main)

Learn more

Build image from Dockerfile using different build context

The following code listing builds an image from a Dockerfile using a build context directory in a different location than the current working directory.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "math"
    "math/rand"
    "os"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    // initialize Dagger client
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // get build context directory
    contextDir := client.Host().Directory("/projects/myapp")

    // get Dockerfile in different filesystem location
    dockerfilePath := "/data/myapp/custom.Dockerfile"
    dockerfile := client.Host().File(dockerfilePath)

    // add Dockerfile to build context directory
    workspace := contextDir.WithFile("custom.Dockerfile", dockerfile)

    // build using Dockerfile
    // publish the resulting container to a registry
    ref, err := client.
        Container().
        Build(workspace, dagger.ContainerBuildOpts{
            Dockerfile: "custom.Dockerfile",
        }).
        Publish(ctx, fmt.Sprintf("ttl.sh/hello-dagger-%.0f", math.Floor(rand.Float64()*10000000))) //#nosec
    if err != nil {
        panic(err)
    }

    fmt.Printf("Published image to :%s\n", ref)
}

import { connect } from "@dagger.io/dagger"

connect(
  async (client) => {
    // get build context directory
    const contextDir = client.host().directory("/projects/myapp")

    // get Dockerfile in different filesystem location
    const dockerfilePath = "/data/myapp/custom.Dockerfile"
    const dockerfile = client.host().file(dockerfilePath)

    // add Dockerfile to build context directory
    const workspace = contextDir.withFile("custom.Dockerfile", dockerfile)

    // build using Dockerfile
    // publish the resulting container to a registry
    const imageRef = await client
      .container()
      .build(workspace, { dockerfile: "custom.Dockerfile" })
      .publish("ttl.sh/hello-dagger-" + Math.floor(Math.random() * 10000000))
    console.log(`Published image to: ${imageRef}`)
  },
  { LogOutput: process.stderr }
)

import random
import sys

import anyio

import dagger


async def main():
    config = dagger.Config(log_output=sys.stdout)

    async with dagger.Connection(config) as client:
        # get build context directory
        context_dir = client.host().directory("/projects/myapp")

        # get Dockerfile in different filesystem location
        dockerfile_path = "/data/myapp/custom.Dockerfile"
        dockerfile = client.host().file(dockerfile_path)

        # add Dockerfile to build context directory
        workspace = context_dir.with_file("custom.Dockerfile", dockerfile)

        # build using Dockerfile
        # publish the resulting container to a registry
        image_ref = await (
            client.container()
            .build(context=workspace, dockerfile="custom.Dockerfile")
            .publish(f"ttl.sh/hello-dagger-{random.SystemRandom().randint(1,10000000)}")
        )

    print(f"Published image to: {image_ref}")


anyio.run(main)

Learn more

Add OCI annotations to image

The following code listing adds OpenContainer Initiative (OCI) annotations to an image.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    "dagger.io/dagger"
)

func main() {
    // create Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // create and publish image with annotations
    ctr := client.Container().
        From("alpine").
        WithLabel("org.opencontainers.image.title", "my-alpine").
        WithLabel("org.opencontainers.image.version", "1.0").
        WithLabel("org.opencontainers.image.created", time.Now().String()).
        WithLabel("org.opencontainers.image.source", "https://github.com/alpinelinux/docker-alpine").
        WithLabel("org.opencontainers.image.licenses", "MIT")

    addr, err := ctr.Publish(ctx, "ttl.sh/my-alpine")
    if err != nil {
        panic(err)
    }

    fmt.Println(addr)
}

import { connect } from "@dagger.io/dagger"

// create Dagger client
connect(
  async (client) => {
    // create and publish image with annotations
    const container = client
      .container()
      .from("alpine")
      .withLabel("org.opencontainers.image.title", "my-alpine")
      .withLabel("org.opencontainers.image.version", "1.0")
      .withLabel("org.opencontainers.image.created", new Date())
      .WithLabel(
        "org.opencontainers.image.source",
        "https://github.com/alpinelinux/docker-alpine"
      )
      .WithLabel("org.opencontainers.image.licenses", "MIT")

    const addr = await container.publish("ttl.sh/my-alpine")

    console.log(addr)
  },
  { LogOutput: process.stderr }
)

import sys
from datetime import datetime, timezone

import anyio

import dagger


async def main():
    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # publish app on alpine base
        addr = await (
            client.container()
            .from_("alpine")
            .with_label("org.opencontainers.image.title", "my-alpine")
            .with_label("org.opencontainers.image.version", "1.0")
            .with_label(
                "org.opencontainers.image.created",
                datetime.now(timezone.utc).isoformat(),
            )
            .with_label(
                "org.opencontainers.image.source",
                "https://github.com/alpinelinux/docker-alpine",
            )
            .with_label("org.opencontainers.image.licenses", "MIT")
            .publish("ttl.sh/my-alpine")
        )

    print(addr)


anyio.run(main)

Define build-time variables

The following code listing defines various environment variables for build purposes.

Go
Node.js
Python

// Create a multi-build pipeline for a Go application.
package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    println("Building with Dagger")

    // define build matrix
    geese := []string{"linux", "darwin"}
    goarches := []string{"amd64", "arm64"}

    ctx := context.Background()
    // initialize dagger client
    c, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }

    // get reference to the local project
    src := c.Host().Directory(".")

    // create empty directory to put build outputs
    outputs := c.Directory()

    golang := c.Container().
        // get golang image
        From("golang:latest").
        // mount source code into golang image
        WithDirectory("/src", src).
        WithWorkdir("/src")

    for _, goos := range geese {
        for _, goarch := range goarches {
            // create a directory for each OS and architecture
            path := fmt.Sprintf("build/%s/%s/", goos, goarch)

            build := golang.
                // set GOARCH and GOOS in the build environment
                WithEnvVariable("GOOS", goos).
                WithEnvVariable("GOARCH", goarch).
                WithExec([]string{"go", "build", "-o", path})

            // add build to outputs
            outputs = outputs.WithDirectory(path, build.Directory(path))
        }
    }

    // write build artifacts to host
    ok, err := outputs.Export(ctx, ".")
    if err != nil {
        panic(err)
    }

    if !ok {
        panic("did not export files")
    }
}

import { connect } from "@dagger.io/dagger"

// Create a multi-build pipeline for a Go application.

// define build matrix
const oses = ["linux", "darwin"]
const arches = ["amd64", "arm64"]

// initialize dagger client
connect(
  async (client) => {
    console.log("Building with Dagger")

    // get reference to the local project
    const src = client.host().directory(".")

    // create empty directory to put build outputs
    var outputs = client.directory()

    const golang = client
      .container()
      // get golang image
      .from("golang:latest")
      // mount source code into golang image
      .withDirectory("/src", src)
      .withWorkdir("/src")

    for (const os of oses) {
      for (const arch of arches) {
        // create a directory for each OS and architecture
        const path = `build/${os}/${arch}/`

        const build = golang
          // set GOARCH and GOOS in the build environment
          .withEnvVariable("GOOS", os)
          .withEnvVariable("GOARCH", arch)
          .withExec(["go", "build", "-o", path])

        // add build to outputs
        outputs = outputs.withDirectory(path, build.directory(path))
      }
    }

    // write build artifacts to host
    await outputs.export(".")
  },
  { LogOutput: process.stderr }
)

"""Create a multi-build pipeline for a Go application."""

import itertools
import sys

import anyio

import dagger


async def main():
    print("Building with Dagger")

    # define build matrix
    oses = ["linux", "darwin"]
    arches = ["amd64", "arm64"]

    # initialize dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # get reference to the local project
        src = client.host().directory(".")

        # create empty directory to put build outputs
        outputs = client.directory()

        golang = (
            # get `golang` image
            client.container()
            .from_("golang:latest")
            # mount source code into `golang` image
            .with_directory("/src", src)
            .with_workdir("/src")
        )

        for goos, goarch in itertools.product(oses, arches):
            # create a directory for each OS and architecture
            path = f"build/{goos}/{goarch}/"

            build = (
                golang
                # set GOARCH and GOOS in the build environment
                .with_env_variable("GOOS", goos)
                .with_env_variable("GOARCH", goarch)
                .with_exec(["go", "build", "-o", path])
            )

            # add build to outputs
            outputs = outputs.with_directory(path, build.directory(path))

        # write build artifacts to host
        await outputs.export(".")


anyio.run(main)

Learn more

Access private Git repository

The following code listing demonstrates how to access a private Git repository using SSH.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()
    client, err := dagger.Connect(ctx)
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // Retrieve path of authentication agent socket from host
    sshAgentPath := os.Getenv("SSH_AUTH_SOCK")

    // Private repository with a README.md file at the root.
    readme, err := client.
        Git("git@private-repository.git").
        Branch("main").
        Tree(
            dagger.GitRefTreeOpts{
                SSHAuthSocket: client.Host().UnixSocket(sshAgentPath),
            },
        ).
        File("README.md").
        Contents(ctx)

    if err != nil {
        panic(err)
    }

    fmt.Println("readme", readme)
}

import { connect, Client } from "@dagger.io/dagger"
import process from "process"

// initialize Dagger client
connect(async (client: Client) => {
  // Collect value of SSH_AUTH_SOCK env var, to retrieve authentication socket path
  const sshAuthSockPath = process.env.SSH_AUTH_SOCK?.toString() || ""

  // Retrieve authentication socket ID from host
  const sshAgentSocketID = await client.host().unixSocket(sshAuthSockPath).id()

  const repo = client
    // Retrieve the repository
    .git("git@private-repository.git")
    // Select the main branch, and the filesystem tree associated
    .branch("main")
    .tree({
      sshAuthSocket: sshAgentSocketID,
    })
    // Select the README.md file
    .file("README.md")

  // Retrieve the content of the README file
  const file = await repo.contents()

  console.log(file)
})

"""Clone a Private Git Repository and print the content of the README.md file."""

import os
import sys

import anyio

import dagger


async def main():
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # Collect value of SSH_AUTH_SOCK env var, to retrieve auth socket path
        ssh_auth_path = os.environ.get("SSH_AUTH_SOCK", "")

        # Retrieve authentication socket from host
        ssh_agent_socket = client.host().unix_socket(ssh_auth_path)

        repo = (
            client
            # Retrieve the repository
            .git("git@private-repository.git")
            # Select the main branch, and the filesystem tree associated
            .branch("main").tree(ssh_auth_socket=ssh_agent_socket)
            # Select the README.md file
            .file("README.md")
        )

        # Retrieve the content of the README file
        file = await repo.contents()

    print(file)


anyio.run(main)

Use transient database for application tests

The following code listing creates a temporary MariaDB database service and binds it to an application container for unit/integration testing.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    // create Dagger client
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))

    if err != nil {
        panic(err)
    }
    defer client.Close()

    // get MariaDB base image
    mariadb := client.Container().
        From("mariadb:10.11.2").
        WithEnvVariable("MARIADB_USER", "user").
        WithEnvVariable("MARIADB_PASSWORD", "password").
        WithEnvVariable("MARIADB_DATABASE", "drupal").
        WithEnvVariable("MARIADB_ROOT_PASSWORD", "root").
        WithExposedPort(3306)

    // get Drupal base image
    // install additional dependencies
    drupal := client.Container().
        From("drupal:10.0.7-php8.2-fpm").
        WithExec([]string{"composer", "require", "drupal/core-dev", "--dev", "--update-with-all-dependencies"})

    // add service binding for MariaDB
    // run kernel tests using PHPUnit
    test, err := drupal.
        WithServiceBinding("db", mariadb).
        WithEnvVariable("SIMPLETEST_DB", "mysql://user:password@db/drupal").
        WithEnvVariable("SYMFONY_DEPRECATIONS_HELPER", "disabled").
        WithWorkdir("/opt/drupal/web/core").
        WithExec([]string{"../../vendor/bin/phpunit", "-v", "--group", "KernelTests"}).
        Stdout(ctx)

    if err != nil {
        panic(err)
    }

    fmt.Println(test)
}

import { connect, Client } from "@dagger.io/dagger"

connect(
  async (client: Client) => {
    // get MariaDB base image
    const mariadb = client
      .container()
      .from("mariadb:10.11.2")
      .withEnvVariable("MARIADB_USER", "user")
      .withEnvVariable("MARIADB_PASSWORD", "password")
      .withEnvVariable("MARIADB_DATABASE", "drupal")
      .withEnvVariable("MARIADB_ROOT_PASSWORD", "root")
      .withExposedPort(3306)

    // get Drupal base image
    // install additional dependencies
    const drupal = client
      .container()
      .from("drupal:10.0.7-php8.2-fpm")
      .withExec([
        "composer",
        "require",
        "drupal/core-dev",
        "--dev",
        "--update-with-all-dependencies",
      ])

    // add service binding for MariaDB
    // run unit tests using PHPUnit
    const test = await drupal
      .withServiceBinding("db", mariadb)
      .withEnvVariable("SIMPLETEST_DB", "mysql://user:password@db/drupal")
      .withEnvVariable("SYMFONY_DEPRECATIONS_HELPER", "disabled")
      .withWorkdir("/opt/drupal/web/core")
      .withExec(["../../vendor/bin/phpunit", "-v", "--group", "KernelTests"])
      .stdout()

    // print ref
    console.log(test)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # get MariaDB base image
        mariadb = (
            client.container()
            .from_("mariadb:10.11.2")
            .with_env_variable("MARIADB_USER", "user")
            .with_env_variable("MARIADB_PASSWORD", "password")
            .with_env_variable("MARIADB_DATABASE", "drupal")
            .with_env_variable("MARIADB_ROOT_PASSWORD", "root")
            .with_exposed_port(3306)
        )

        # get Drupal base image
        # install additional dependencies
        drupal = (
            client.container()
            .from_("drupal:10.0.7-php8.2-fpm")
            .with_exec(
                [
                    "composer",
                    "require",
                    "drupal/core-dev",
                    "--dev",
                    "--update-with-all-dependencies",
                ]
            )
        )

        # add service binding for MariaDB
        # run unit tests using PHPUnit
        test = await (
            drupal.with_service_binding("db", mariadb)
            .with_env_variable("SIMPLETEST_DB", "mysql://user:password@db/drupal")
            .with_env_variable("SYMFONY_DEPRECATIONS_HELPER", "disabled")
            .with_workdir("/opt/drupal/web/core")
            .with_exec(["../../vendor/bin/phpunit", "-v", "--group", "KernelTests"])
            .stdout()
        )

    print(test)


anyio.run(main)

Learn more

Invalidate cache

The following code listing demonstrates how to invalidate the Dagger pipeline operations cache and thereby force execution of subsequent pipeline steps, by introducing a volatile time variable at a specific point in the Dagger pipeline.

note

This is a temporary workaround until cache invalidation support is officially added to Dagger.

note

Changes in mounted cache volumes do not invalidate the Dagger pipeline operations cache.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    "dagger.io/dagger"
)

func main() {
    // create Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // invalidate cache to force execution
    // of second WithExec() operation
    output, err := client.Pipeline("test").
        Container().
        From("alpine").
        WithExec([]string{"apk", "add", "curl"}).
        WithEnvVariable("CACHEBUSTER", time.Now().String()).
        WithExec([]string{"apk", "add", "zip"}).
        Stdout(ctx)
    if err != nil {
        panic(err)
    }
    fmt.Println(output)
}

import { connect } from "@dagger.io/dagger"

// create Dagger client
connect(
  async (client) => {
    // invalidate cache to force execution
    // of second withExec() operation
    const output = await client
      .pipeline("test")
      .container()
      .from("alpine")
      .withExec(["apk", "add", "curl"])
      .withEnvVariable("CACHEBUSTER", Date.now().toString())
      .withExec(["apk", "add", "zip"])
      .stdout()

    console.log(output)
  },
  { LogOutput: process.stderr }
)

import sys
from datetime import datetime

import anyio

import dagger


async def main():
    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # invalidate cache to force execution
        # of second with_exec() operation
        output = await (
            client.pipeline("test")
            .container()
            .from_("alpine")
            .with_exec(["apk", "add", "curl"])
            .with_env_variable("CACHEBUSTER", str(datetime.now()))
            .with_exec(["apk", "add", "zip"])
            .stdout()
        )

    print(output)


anyio.run(main)

Outputs

Publish image to registry

The following code listing publishes a container image to a remote registry (Docker Hub). Replace the DOCKER-HUB-USERNAME and DOCKER-HUB-PASSWORD placeholders with your Docker Hub username and password respectively.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    // initialize Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // set secret as string value
    secret := client.SetSecret("password", "DOCKER-HUB-PASSWORD")

    // create container
    c := client.Container(dagger.ContainerOpts{Platform: "linux/amd64"}).
        From("nginx:1.23-alpine").
        WithNewFile("/usr/share/nginx/html/index.html", dagger.ContainerWithNewFileOpts{
            Contents:    "Hello from Dagger!",
            Permissions: 0o400,
        })

    // use secret for registry authentication
    addr, err := c.
        WithRegistryAuth("docker.io", "DOCKER-HUB-USERNAME", secret).
        Publish(ctx, "DOCKER-HUB-USERNAME/my-nginx")
    if err != nil {
        panic(err)
    }

    // print result
    fmt.Println("Published at:", addr)
}

import { connect } from "@dagger.io/dagger"

// initialize Dagger client
connect(
  async (client) => {
    // set secret as string value
    const secret = client.setSecret("password", "DOCKER-HUB-PASSWORD")

    // create container
    const c = client
      .container()
      .from("nginx:1.23-alpine")
      .withNewFile("/usr/share/nginx/html/index.html", {
        contents: "Hello from Dagger!",
        permissions: 0o400,
      })

    // use secret for registry authentication
    const addr = await c
      .withRegistryAuth("docker.io", "DOCKER-HUB-USERNAME", secret)
      .publish("DOCKER-HUB-USERNAME/my-nginx")

    // print result
    console.log(`Published at: ${addr}`)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # set secret as string value
        secret = client.set_secret("password", "DOCKER-HUB-PASSWORD")

        # create container
        ctr = (
            client.container(platform=dagger.Platform("linux/amd64"))
            .from_("nginx:1.23-alpine")
            .with_new_file(
                "/usr/share/nginx/html/index.html",
                contents="Hello from Dagger!",
                permissions=0o400,
            )
        )

        # use secret for registry authentication
        addr = await ctr.with_registry_auth(
            "docker.io", "DOCKER-HUB-USERNAME", secret
        ).publish("DOCKER-HUB-USERNAME/my-nginx")

    print(f"Published at: {addr}")


anyio.run(main)

Learn more

Export image to host

The following code listing exports a container image from a Dagger pipeline to the host.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    // initialize Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // use NGINX container
    // add new webserver index page
    c := client.Container(dagger.ContainerOpts{Platform: "linux/amd64"}).
        From("nginx:1.23-alpine").
        WithNewFile("/usr/share/nginx/html/index.html", dagger.ContainerWithNewFileOpts{
            Contents:    "Hello from Dagger!",
            Permissions: 0o400,
        })

    // export to host filesystem
    val, err := c.Export(ctx, "/tmp/my-nginx.tar")
    if err != nil {
        panic(err)
    }

    // print result
    fmt.Println("Exported image: ", val)
}

import { connect } from "@dagger.io/dagger"

// initialize Dagger client
connect(
  async (client) => {
    // use NGINX container
    // add new webserver index page
    const ctr = client
      .container({ platform: "linux/amd64" })
      .from("nginx:1.23-alpine")
      .withNewFile("/usr/share/nginx/html/index.html", {
        contents: "Hello from Dagger!",
        permissions: 0o400,
      })

    // export to host filesystem
    const result = await ctr.export("/tmp/my-nginx.tar")

    // print result
    console.log(`Exported image: ${result}`)
  },
  { LogOutput: process.stderr }
)

import sys

import anyio

import dagger


async def main():
    # initialize Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # use NGINX container
        # add new webserver index page
        ctr = (
            client.container(platform=dagger.Platform("linux/amd64"))
            .from_("nginx:1.23-alpine")
            .with_new_file(
                "/usr/share/nginx/html/index.html",
                contents="Hello from Dagger!",
                permissions=0o400,
            )
        )

        # export to host filesystem
        val = await ctr.export("/tmp/my-nginx.tar")

    print(f"Exported image: {val}")


anyio.run(main)

Learn more

Export container directory to host

The following code listing exports the contents of a container directory to the host's temporary directory.

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "dagger.io/dagger"
)

func main() {
    hostdir := os.TempDir()

    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    _, err = client.Container().From("alpine:latest").
        WithWorkdir("/tmp").
        WithExec([]string{"wget", "https://dagger.io"}).
        Directory(".").
        Export(ctx, hostdir)
    if err != nil {
        log.Println(err)
        return
    }
    contents, err := os.ReadFile(filepath.Join(hostdir, "index.html"))
    if err != nil {
        log.Println(err)
        return
    }
    fmt.Println(string(contents))
}

Learn more

Publish image to registry with multiple tags

The following code listing tags a container image multiple times and publishes it to a remote registry (Docker Hub). Set the Docker Hub username and password as host environment variables named DOCKERHUB_USERNAME and DOCKERHUB_PASSWORD respectively.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    // create Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // load registry credentials from environment variables
    username := os.Getenv("DOCKERHUB_USERNAME")
    if username == "" {
        panic("DOCKERHUB_USERNAME env var must be set")
    }
    passwordPlaintext := os.Getenv("DOCKERHUB_PASSWORD")
    if passwordPlaintext == "" {
        panic("DOCKERHUB_PASSWORD env var must be set")
    }
    password := client.SetSecret("password", passwordPlaintext)

    // define multiple image tags
    tags := [4]string{"latest", "1.0-alpine", "1.0", "1.0.0"}

    // create and publish image with multiple tags
    ctr := client.Container().
        From("alpine").
        WithRegistryAuth("docker.io", username, password)

    for _, tag := range tags {
        addr, err := ctr.Publish(ctx, fmt.Sprintf("%s/alpine:%s", username, tag))
        if err != nil {
            panic(err)
        }
        fmt.Println("Published: ", addr)
    }
}

import { connect } from "@dagger.io/dagger"

// create Dagger client
connect(
  async (client) => {
    // define tags
    const tags = ["latest", "1.0-alpine", "1.0", "1.0.0"]

    if (!process.env.DOCKERHUB_USERNAME) {
      console.log("DOCKERHUB_USERNAME environment variable must be set")
      process.exit()
    }
    if (!process.env.DOCKERHUB_PASSWORD) {
      console.log("DOCKERHUB_PASSWORD environment variable must be set")
      process.exit()
    }
    const username = process.env.DOCKERHUB_USERNAME
    const password = process.env.DOCKERHUB_PASSWORD

    // set secret as string value
    const secret = client.setSecret("password", password)

    // create and publish image with multiple tags
    const container = client.container().from("alpine")

    for (var tag in tags) {
      let addr = await container
        .withRegistryAuth("docker.io", username, secret)
        .publish(`${username}/my-alpine:${tags[tag]}`)
      console.log(`Published at: ${addr}`)
    }
  },
  { LogOutput: process.stderr }
)

import os
import sys

import anyio

import dagger


async def main():
    # define tags
    tags = ["latest", "1.0-alpine", "1.0", "1.0.0"]

    if "DOCKERHUB_USERNAME" not in os.environ:
        msg = "DOCKERHUB_USERNAME environment variable must be set"
        raise OSError(msg)

    if "DOCKERHUB_PASSWORD" not in os.environ:
        msg = "DOCKERHUB_PASSWORD environment variable must be set"
        raise OSError(msg)

    username = os.environ["DOCKERHUB_USERNAME"]
    password = os.environ["DOCKERHUB_PASSWORD"]

    # create Dagger client
    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # set secret as string value
        secret = client.set_secret("password", password)

        # create and publish image with multiple tags
        container = client.container().from_("alpine")

        for tag in tags:
            addr = await container.with_registry_auth(
                "docker.io", username, secret
            ).publish(f"{username}/my-alpine:{tag}")

            print(f"Published at: {addr}")


anyio.run(main)

Secrets

Expose secret via environment variable

The following code listing demonstrates how to inject an environment variable in a container as a secret.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    // initialize Dagger client
    ctx := context.Background()

    if os.Getenv("GH_SECRET") == "" {
        panic("Environment variable GH_SECRET is not set")
    }

    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // read secret from host variable
    secret := client.SetSecret("gh-secret", os.Getenv("GH_SECRET"))

    // use secret in container environment
    out, err := client.
        Container().
        From("alpine:3.17").
        WithSecretVariable("GITHUB_API_TOKEN", secret).
        WithExec([]string{"apk", "add", "curl"}).
        WithExec([]string{"sh", "-c", `curl "https://api.github.com/repos/dagger/dagger/issues" --header "Accept: application/vnd.github+json" --header "Authorization: Bearer $GITHUB_API_TOKEN"`}).
        Stdout(ctx)
    if err != nil {
        panic(err)
    }

    fmt.Println(out)
}

import { connect } from "@dagger.io/dagger"

// check for required environment variable
if (!process.env["GH_SECRET"]) {
  console.log(`GH_SECRET variable must be set`)
  process.exit()
}

// initialize Dagger client
connect(
  async (client) => {
    // read secret from host variable
    const secret = client.setSecret("gh-secret", process.env["GH_SECRET"])

    // use secret in container environment
    const out = await client
      .container()
      .from("alpine:3.17")
      .withSecretVariable("GITHUB_API_TOKEN", secret)
      .withExec(["apk", "add", "curl"])
      .withExec([
        "sh",
        "-c",
        `curl "https://api.github.com/repos/dagger/dagger/issues" --header "Accept: application/vnd.github+json" --header "Authorization: Bearer $GITHUB_API_TOKEN"`,
      ])
      .stdout()

    // print result
    console.log(out)
  },
  { LogOutput: process.stderr }
)

import os
import sys

import anyio

import dagger


async def main():
    if "GH_SECRET" not in os.environ:
        msg = "GH_SECRET environment variable must be set"
        raise OSError(msg)

    async with dagger.Connection(dagger.Config(log_output=sys.stderr)) as client:
        # read secret from host variable
        secret = client.set_secret("gh-secret", os.environ["GH_SECRET"])

        # use secret in container environment
        out = await (
            client.container(platform=dagger.Platform("linux/amd64"))
            .from_("alpine:3.17")
            .with_secret_variable("GITHUB_API_TOKEN", secret)
            .with_exec(["apk", "add", "curl"])
            .with_exec(
                [
                    "sh",
                    "-c",
                    """curl "https://api.github.com/repos/dagger/dagger/issues" --header "Accept: application/vnd.github+json" --header "Authorization: Bearer $GITHUB_API_TOKEN" """,
                ]
            )
            .stdout()
        )

    print(out)


anyio.run(main)

Learn more

Expose secret via file

The following code listing demonstrates how to inject a file in a container as a secret.

Go
Node.js
Python

package main

import (
    "context"
    "fmt"
    "os"

    "dagger.io/dagger"
)

func main() {
    // initialize Dagger client
    ctx := context.Background()
    client, err := dagger.Connect(ctx, dagger.WithLogOutput(os.Stderr))
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // read file
    config, err := os.ReadFile("/home/USER/.config/gh/hosts.yml")
    if err != nil {
        panic(err)
    }

    // set secret to file contents
    secret := client.SetSecret("ghConfig", string(config))

    // mount secret as file in container
    out, err := client.
        Container().
        From("alpine:3.17").
        

Cookbook

Filesystem​

List host directory contents​

Get host directory with filters​

Mount and read host directory in container​

Mount and write to host directory from container​

Add Git repository as directory to container​

Add Git repository as directory to container with filters​

Builds​

Perform multi-stage build​

Perform matrix build​

Build multi-arch image​

Build multi-arch image with cross-compilation​

Build image from Dockerfile​

Build image from Dockerfile using different build context​

Add OCI annotations to image​

Define build-time variables​

Access private Git repository​

Use transient database for application tests​

Invalidate cache​

Outputs​

Publish image to registry​

Export image to host​

Export container directory to host​

Publish image to registry with multiple tags​

Secrets​

Expose secret via environment variable​

Expose secret via file​

Filesystem

List host directory contents

Get host directory with filters

Mount and read host directory in container

Mount and write to host directory from container

Add Git repository as directory to container

Add Git repository as directory to container with filters

Builds

Perform multi-stage build

Perform matrix build

Build multi-arch image

Build multi-arch image with cross-compilation

Build image from Dockerfile

Build image from Dockerfile using different build context

Add OCI annotations to image

Define build-time variables

Access private Git repository

Use transient database for application tests

Invalidate cache

Outputs

Publish image to registry

Export image to host

Export container directory to host

Publish image to registry with multiple tags

Secrets

Expose secret via environment variable

Expose secret via file