depot

Documentation

Overview

Package depot provides Depot.dev build backend integration.

This package implements cloud-native container builds through the Depot.dev platform. It provides optimized builds with automatic caching, parallel execution, and direct registry integration for production workflows.

Architecture

The Depot backend integrates with:

• Depot.dev API for build orchestration
• ClickHouse for build telemetry and analytics
• S3 storage for build artifact persistence
• Registry integration for container image management

Key Features

- Cloud-native builds with automatic scaling - Build caching for faster repeated builds - Parallel build execution - Direct registry pushing and management - Build artifact storage and sharing - Real-time build progress tracking - Integration with unkey platform deployment workflows

Usage

Creating Depot build backend:

depotBackend := depot.New(depot.Config{
	InstanceID:     "build-instance-001",
	DB:             database,
	RegistryConfig:  depot.RegistryConfig{
		URL:      "https://registry.depot.dev",
		Username: "x-token",
		Password: "depot-api-token",
	},
	BuildPlatform:  depot.BuildPlatform{
		Platform:     "linux/amd64",
		Architecture: "amd64",
	},
	DepotConfig: depot.DepotConfig{
		APIUrl:        "https://api.depot.dev",
		ProjectRegion:  "us-east-1",
	},
	Clickhouse:     clickhouseClient,
	Storage:        buildStorage,
	Logger:         logger,
})

Build Operations

The backend implements standard BuildService interface methods:

• CreateBuild: Start new container build
• GenerateUploadUrl: Generate pre-signed URLs for build artifacts
• GetBuild: Get build status and metadata
• GetBuildLogs: Stream real-time build logs

Error Handling

Provides comprehensive error handling with proper HTTP status codes for API communication failures and build errors.

Package depot is used to build images and store them in their registry using depot.dev. This gives us isolated and cached builds.

Index

• type BuildPlatform
• type Config
• type Depot
  • func New(cfg Config) *Depot
  • func (s *Depot) CreateBuild(ctx context.Context, req *connect.Request[ctrlv1.CreateBuildRequest]) (*connect.Response[ctrlv1.CreateBuildResponse], error)
  • func (s *Depot) GenerateUploadURL(ctx context.Context, req *connect.Request[ctrlv1.GenerateUploadURLRequest]) (*connect.Response[ctrlv1.GenerateUploadURLResponse], error)
• type DepotConfig
• type RegistryConfig

Types

type BuildPlatform

type BuildPlatform struct {
	Platform     string
	Architecture string
}

type Config

type Config struct {
	InstanceID     string
	DB             db.Database
	Storage        *storage.S3
	DepotConfig    DepotConfig
	Clickhouse     clickhouse.ClickHouse // Clickhouse for telemetry
	RegistryConfig RegistryConfig
	BuildPlatform  BuildPlatform
	Logger         logging.Logger
}

type Depot

type Depot struct {
	ctrlv1connect.UnimplementedBuildServiceHandler
	// contains filtered or unexported fields
}

func New

func New(cfg Config) *Depot

func (*Depot) CreateBuild

func (s *Depot) CreateBuild(
	ctx context.Context,
	req *connect.Request[ctrlv1.CreateBuildRequest],
) (*connect.Response[ctrlv1.CreateBuildResponse], error)

CreateBuild orchestrates the container image build process using Depot.

Steps:

Get or create Depot project
Register a new build with Depot
Acquire a build machine
Connect to the buildkit instance
Prepare build context and configuration
Execute the build with status logging
Return build metadata

func (*Depot) GenerateUploadURL

func (s *Depot) GenerateUploadURL(
	ctx context.Context,
	req *connect.Request[ctrlv1.GenerateUploadURLRequest],
) (*connect.Response[ctrlv1.GenerateUploadURLResponse], error)

type DepotConfig

type DepotConfig struct {
	APIUrl        string
	ProjectRegion string
}

type RegistryConfig

type RegistryConfig struct {
	URL      string
	Username string
	Password string
}