Merge pull request #50 from depot/feat/organize-examples

feat: organize examples

Author: goller

.github/workflows/ci.yml

@@ -52,4 +52,7 @@ jobs:
           go-version: "1.24"
           check-latest: true
           cache: true
-      - run: go build -o bin/example ./examples/build
+      - name: Build examples
+        run: |
+          go build -o bin/llb ./examples/low-level-build-ops
+          go build -o bin/simple ./examples/simple

examples/go.mod

@@ -4,6 +4,7 @@ go 1.24
 
 require (
 	github.com/depot/depot-go v0.0.0-dev
+	github.com/docker/cli v25.0.3+incompatible
 	github.com/moby/buildkit v0.13.2
 	github.com/opencontainers/image-spec v1.1.0
 	golang.org/x/sync v0.12.0
@@ -24,6 +25,8 @@ require (
 	github.com/containerd/ttrpc v1.2.7 // indirect
 	github.com/containerd/typeurl/v2 v2.1.1 // indirect
 	github.com/distribution/reference v0.6.0 // indirect
+	github.com/docker/docker v25.0.3+incompatible // indirect
+	github.com/docker/docker-credential-helpers v0.8.0 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/go-logr/logr v1.4.2 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
@@ -35,6 +38,7 @@ require (
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
 	github.com/grpc-ecosystem/go-grpc-middleware v1.3.0 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.16.0 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
 	github.com/in-toto/in-toto-golang v0.5.0 // indirect
 	github.com/klauspost/compress v1.17.4 // indirect
 	github.com/kr/text v0.2.0 // indirect
@@ -69,6 +73,7 @@ require (
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240429193739-8cf5692501f6 // indirect
 	google.golang.org/grpc v1.63.2 // indirect
 	google.golang.org/protobuf v1.35.2 // indirect
+	gotest.tools/v3 v3.5.2 // indirect
 )
 
 replace github.com/depot/depot-go => ../

examples/go.sum

@@ -57,8 +57,12 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
 github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/cli v25.0.3+incompatible h1:KLeNs7zws74oFuVhgZQ5ONGZiXUUdgsdy6/EsX/6284=
+github.com/docker/cli v25.0.3+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
 github.com/docker/docker v25.0.3+incompatible h1:D5fy/lYmY7bvZa0XTZ5/UJPljor41F+vdyJG5luQLfQ=
 github.com/docker/docker v25.0.3+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/docker-credential-helpers v0.8.0 h1:YQFtbBQb4VrpoPxhFuzEBPQ9E16qz5SpHLS+uswaCp8=
+github.com/docker/docker-credential-helpers v0.8.0/go.mod h1:UGFXcuoQ5TxPiB54nHOZ32AWRqQdECoh/Mg0AlEYb40=
 github.com/docker/go-connections v0.5.0 h1:USnMq7hx7gwdVZq1L49hLXaFtUdTADjXGp+uj1Br63c=
 github.com/docker/go-connections v0.5.0/go.mod h1:ov60Kzw0kKElRwhNs9UlUHAE/F9Fe6GLaXnqyDdmEXc=
 github.com/docker/go-events v0.0.0-20190806004212-e31b211e4f1c h1:+pKlWGMw7gf6bQ+oDZB4KHQFypsfjYlq/C4rfL7D3g8=
@@ -111,6 +115,8 @@ github.com/grpc-ecosystem/go-grpc-middleware v1.3.0 h1:+9834+KizmvFV7pXQGSXQTsaW
 github.com/grpc-ecosystem/go-grpc-middleware v1.3.0/go.mod h1:z0ButlSOZa5vEBq9m2m2hlwIgKw+rp3sdCBRoJY+30Y=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.16.0 h1:YBftPWNWd4WwGqtY2yeZL2ef8rHAxPBD8KFhJpmcqms=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.16.0/go.mod h1:YN5jB8ie0yfIUg6VvR9Kz84aCaG7AsGZnLjhHbUqwPg=
+github.com/hashicorp/go-cleanhttp v0.5.2 h1:035FKYIWjmULyFRBKPs8TBQoi0x6d9G4xc9neXJWAZQ=
+github.com/hashicorp/go-cleanhttp v0.5.2/go.mod h1:kO/YDlP8L1346E6Sodw+PrpBSV4/SoxCXGY6BqNFT48=
 github.com/in-toto/in-toto-golang v0.5.0 h1:hb8bgwr0M2hGdDsLjkJ3ZqJ8JFLL/tgYdAxF/XEFBbY=
 github.com/in-toto/in-toto-golang v0.5.0/go.mod h1:/Rq0IZHLV7Ku5gielPT4wPHJfH1GdHMCq8+WPxw8/BE=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
@@ -306,5 +312,7 @@ gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
+gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

examples/low-level-build-ops/README.md

@@ -0,0 +1,3 @@
+## Low-Level Build Example
+
+This example shows how to use the BuildKit low-level-build operations to build an image using Depot.

examples/build/main.go renamed to examples/low-level-build-ops/main.go

@@ -75,7 +75,9 @@ func buildImage(ctx context.Context, buildkitClient *client.Client) error {
 	ch := make(chan *client.SolveStatus)
 	eg, ctx := errgroup.WithContext(ctx)
 
-	ops := llb.Image("alpine:latest")
+	ops := llb.
+		Image("ubuntu:24.04").       // Like FROM
+		Run(llb.Shlex("apt update")) // Like RUN
 	def, err := ops.Marshal(ctx, llb.LinuxAmd64)
 	if err != nil {
 		return err

examples/simple/README.md

@@ -0,0 +1,3 @@
+## Simple Build with Depot
+
+This example shows how to build and push an image with Depot.

examples/simple/main.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/depot/depot-go/build"
+	"github.com/depot/depot-go/machine"
+	cliv1 "github.com/depot/depot-go/proto/depot/cli/v1"
+	"github.com/docker/cli/cli/config"
+	"github.com/moby/buildkit/client"
+	"github.com/moby/buildkit/session"
+	"github.com/moby/buildkit/session/auth/authprovider"
+)
+
+func main() {
+	// You can use a context with timeout to cancel the build if you would like.
+	ctx := context.Background()
+
+	// Set these environment variables...
+	token := os.Getenv("DEPOT_TOKEN")
+	project := os.Getenv("DEPOT_PROJECT_ID")
+
+	// ... and set these variables.
+	dockerfilePath := "./Dockerfile"
+	workingDir := "."
+	imageTag := "goller/depot-example:latest"
+
+	// 1. Register a new build.  This returns back an id and a temporary build token.
+	req := &cliv1.CreateBuildRequest{
+		ProjectId: project,
+	}
+	build, err := build.NewBuild(ctx, req, token)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Set the buildErr to any error that represents the build failing.
+	var buildErr error
+	defer build.Finish(buildErr)
+
+	// 2. Acquire a buildkit machine.
+	var buildkit *machine.Machine
+	buildkit, buildErr = machine.Acquire(ctx, build.ID, build.Token, "arm64" /* or "amd64" */)
+	if buildErr != nil {
+		return
+	}
+	defer buildkit.Release()
+
+	connectCtx, cancelConnect := context.WithTimeout(ctx, 5*time.Minute)
+	defer cancelConnect()
+
+	var buildkitClient *client.Client
+	buildkitClient, buildErr = buildkit.Connect(connectCtx)
+	if buildErr != nil {
+		return
+	}
+
+	solverOptions := client.SolveOpt{
+		Frontend: "dockerfile.v0", // Interpret the build as a Dockerfile.
+		FrontendAttrs: map[string]string{
+			"filename": filepath.Base(dockerfilePath),
+			"platform": "linux/arm64", // Build for arm64 architecture.
+		},
+		LocalDirs: map[string]string{
+			"dockerfile": filepath.Dir(dockerfilePath),
+			"context":    workingDir,
+		},
+		Exports: []client.ExportEntry{
+			{
+				Type: "image",
+				Attrs: map[string]string{
+					"oci-mediatypes": "true",
+					"push":           "true",   // Push the image to the registry...
+					"name":           imageTag, // ... with this tag.
+				},
+			},
+		},
+		Session: []session.Attachable{
+			// Use credentials sorted by `docker login` command.
+			authprovider.NewDockerAuthProvider(config.LoadDefaultConfigFile(os.Stderr), nil),
+		},
+	}
+
+	// 3. Print all build status updates as JSON to stdout.
+	buildStatusCh := make(chan *client.SolveStatus, 10)
+	go func() {
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		for status := range buildStatusCh {
+			_ = enc.Encode(status)
+		}
+	}()
+
+	// 4. Build and push the image.
+	_, buildErr = buildkitClient.Solve(ctx, nil, solverOptions, buildStatusCh)
+	if buildErr != nil {
+		return
+	}
+}