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 build cache.
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 cache 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. The cache is shared between apps, and with one build at a time a build never has to wait on another's locks.
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 the tools Railpack downloaded for an app. What the app left in the shared cache ages out with the rest.
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