zbpack

repository·main·Indexed 43 days ago

An automated build tool that analyzes source code to detect languages, frameworks, and versions to automatically generate and build container images or other deployment forms. Used primarily by the Zeabur platform, it provides a CLI for manual builds and a Go library for platform integration.

Tokens: 1.9K
Snippets: 5
Records: 8
Agent score: 54%

What's inside zbpack

Overview of zbpack
main
What is zbpack?
zbpack (pronounced “Zeabur Pack”) is a tool designed to automatically analyze source code to determine the language, version, and framework used. It then packages the service into the most suitable deployment form, such as static resources, cloud functions, or containers.
It is primarily used as the build tool on the Zeabur platform to automatically determine code types and build container images without requiring manual Dockerfiles.
Core Components
- Planners: Located in the internal directory, these are responsible for analyzing source code and determining the code type.
- zeaburpack library: Located in pkg/zeaburpack, this library can be integrated directly into your own platform.
- CLI: Located in cmd/zbpack, this is the command-line interface used for testing and manual builds.
https://github.com/zeabur/zbpack/blob/main/README.md
Set up zbpack for local development
main
To prepare the zbpack environment on your local machine, follow these steps:
1. Clone the repository: Fork and clone the repository to your local machine.
2. Install Go: Ensure Go is installed (available at https://golang.org/dl/).
3. Download dependencies: Navigate to the project root and run:
  go mod download
4. Install Buildkit: Ensure buildctl is installed and buildkitd is currently running.
https://github.com/zeabur/zbpack/blob/main/README.md
Use the zbpack CLI to analyze and build projects
main
The zbpack CLI analyzes your project, constructs image recipes, and builds the container image automatically.
Build the CLI binary
First, compile the binary from the source:
```
go build -o zbpack ./cmd/zbpack/main.go
```
Run the analysis and build
Execute the binary by passing the directory you wish to analyze:
```
./zbpack [the directory to analyze and build]
```
When running, the output will include:
- Build Plan: A block showing metadata and the "recipes" (e.g., provider, startCmd, packageManager, framework, nodeVersion, installCmd) used to build the image.
- Build Log: The actual container image build logs outputted by docker build.
```
$ ./zbpack corepack-project
```
https://github.com/zeabur/zbpack/blob/main/README.md
Use the zbpack CLI to build Docker images
main
zbpack is a command-line tool designed to help you build your project as a Docker image in one click. The tool is invoked via the zbpack command, which executes the core logic provided by the zbpack package.
```
# Example usage (command name depends on installation)
zbpack
```
https://github.com/zeabur/zbpack/blob/main/cmd/zbpack/main.go

View only the build plan with zbpack

main

If you want to inspect the detected metadata and build recipes without triggering a full container build, use the -i or --info flag.

Example output:

╔══════════════════════════ Build Plan ═════════════════════════╗
║ provider         │ nodejs                                     ║
║───────────────────────────────────────────────────────────────║
║ startCmd         │ node index.js                              ║
║───────────────────────────────────────────────────────────────║
║ packageManager   │ pnpm                                       ║
║───────────────────────────────────────────────────────────────║
║ framework        │ none                                       ║
║───────────────────────────────────────────────────────────────║
║ nodeVersion      │ 16                                         ║
║───────────────────────────────────────────────────────────────║
║ installCmd       │ pnpm install                               ║
╚═══════════════════════════════════════════════════════════════╝

$ ./zbpack --info corepack-project

zbpack CLI command reference
main
The following flags are available for the zbpack CLI:
Flag Long Flag Description
-i --info Show the build plan (metadata/recipes) only, without building the image.
-h --help Show help information and usage instructions.
https://github.com/zeabur/zbpack/blob/main/README.md
Build an image with Build()
main
The Build function is the primary entry point for analyzing a project, determining a build plan, and constructing a container image. It automatically handles project analysis (via a planner), Dockerfile generation, image building, and output transformation.
To use it, provide a BuildOptions pointer. If Path is not provided, it defaults to the current working directory. If ResultImage is not provided, it defaults to the base name of the project path (lowercased and with underscores replaced by hyphens).
Key features:
- Automatic Planning: Analyzes the filesystem to determine the PlanType and PlanMeta.
- Custom Dockerfiles: If the DOCKERFILE environment variable is set, it bypasses automatic planning and uses that file.
- Callbacks: Use HandlePlanDetermined to intercept the build plan before the image is built.
- Pushing: Set PushImage: true to push the resulting image to a registry.
```
err := zeaburpack.Build(&zeaburpack.BuildOptions{
	Path:         ptr.String("./my-project"),
	SubmoduleName: ptr.String("my-service"),
	ResultImage:  ptr.String("my-custom-image"),
	PushImage:    true,
	LogWriter:    os.Stdout,
})
if err != nil {
	log.Fatal(err)
}
```
https://github.com/zeabur/zbpack/blob/main/pkg/zeaburpack/main.go

Flag	Long Flag	Description
`-i`	`--info`	Show the build plan (metadata/recipes) only, without building the image.
`-h`	`--help`	Show help information and usage instructions.

Configure BuildOptions

main

The BuildOptions struct defines the configuration for the Build process.

Field	Type	Description
`SubmoduleName`	`*string`	The name of the submodule to build (e.g., the service name in Zeabur). Used to locate files in `cmd` directories.
`HandlePlanDetermined`	`*func(types.PlanType, types.PlanMeta)`	A callback triggered once the build plan is determined. Useful for inspecting or modifying the build strategy.
`LogWriter`	`io.Writer`	Destination for log output. Defaults to `os.Stderr` if `nil`.
`Path`	`*string`	Absolute or relative path to the project directory. Defaults to current working directory.
`ResultImage`	`*string`	The name of the image to be built. Defaults to the directory name (lowercased, hyphens instead of underscores).
`UserVars`	`*map[string]string`	A map of variables to be injected into the Dockerfile via `ARG` or `ENV`.
`Interactive`	`*bool`	If `true`, enables interactive mode and prints run commands upon success.
`CacheFrom`	`*string`	Docker cache source.
`CacheTo`	`*string`	Docker cache destination.
`ProxyRegistry`	`*string`	The registry to be used for the image.
`PushImage`	`bool`	Whether to push the built image to the registry.

type BuildOptions struct {
	SubmoduleName        *string
	HandlePlanDetermined *func(types.PlanType, types.PlanMeta)
	LogWriter            io.Writer
	Path                 *string
	ResultImage          *string
	UserVars             *map[string]string
	Interactive          *bool
	CacheFrom            *string
	CacheTo              *string
	ProxyRegistry        *string
	PushImage            bool
}

zbpack

What's inside zbpack

What is zbpack?

Core Components

Build the CLI binary

Run the analysis and build