Documentation
¶
Overview ¶
Package build turns an app's source code into an image. It runs in the core, but the source is untrusted, so everything that reads or runs it happens inside containers. The core itself only moves files around and imports the finished image.
A build has up to three steps, each a fresh container:
- unpack: extract the source archive. No network, nothing else mounted.
- plan: if there is no Dockerfile, Railpack works out how to build the app. It downloads tools, so it gets the network, but no build cache.
- build: BuildKit builds the image, each step in a sandbox of its own. Only this container may run nested containers.
After every build, a last container trims the app's build cache, and then those of a few other apps if they are above their part of the limit. Every app has a BuildKit state of its own: a Dockerfile can name any cache mount, or bring its own frontend, so with a shared state one app could plant files that another app's build then compiles into its image.
Keeping unpack apart matters: an archive can hold symlinks, and a container that extracts one must not have anything worth reaching through them.
Index ¶
Constants ¶
const ( // Both images are pinned by digest, like the binaries the engine // installs, so a moved tag cannot change what runs. BuilderImage = "docker.io/moby/buildkit:v0.33.0@sha256:6c2fa84a6b61ccd72899dde4239f8d5717f05f9a8ca6f3cad185fb1a95a94de3" RailpackFrontend = "ghcr.io/railwayapp/railpack-frontend:v0.40.0@sha256:fc6d5fa434c9310500dc18bebb0a4eb4854fee8546a6d7a090e7a36e39d9d153" // Network is where build steps that download things run. It is a // network of its own, so builds cannot reach running apps. Network = "zelie-build" // MaxSource is the largest source archive accepted. MaxSource = 512 << 20 )
Variables ¶
var ErrSourceTooLarge = fmt.Errorf("the source is larger than %d MB", MaxSource>>20)
ErrSourceTooLarge is returned for a source archive over MaxSource.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
Engine Engine
Paths engine.Paths
// Dir holds the build caches and the files of the build in progress.
Dir string
MemoryBytes int64
CPUs float64
// contains filtered or unexported fields
}
Builder runs builds one at a time, so a single BuildKit runs at once and builds do not compete for memory.
func (*Builder) Build ¶
Build builds the source into an image. The output of every step is written to out as it happens.
func (*Builder) RemoveCache ¶
RemoveCache deletes an app's build cache: BuildKit's own and the tools Railpack downloaded.
type Engine ¶
type Engine interface {
Run(ctx context.Context, s engine.Spec) error
Wait(ctx context.Context, id string) (uint32, error)
Remove(ctx context.Context, id string) error
ImportImage(ctx context.Context, r io.Reader, name string) error
}
Engine is what a build needs from the container engine.
type Request ¶
type Request struct {
App string // the app's ID, which names the image
Version string // names this build of it, such as a commit hash
// Source is a gzipped tar with the code in a single top-level
// directory, the way GitHub hands out repository archives.
Source io.Reader
// Vars are the app's variables, which the build can read too.
Vars []Var
}
Request is one build.
type Result ¶
type Result struct {
Image string
// TestCommand is how the app's tests can probably be run in the image,
// or empty if no tests were found.
TestCommand string
// How the image was built: "dockerfile" or "railpack", and for
// Railpack the commands it chose, to show next to the user's own.
Builder string
BuildCommand string
StartCommand string
}
Result is what a build produced.
Source Files