.\" Man page generated from reStructuredText.
.
.TH "CH-BUILD" "1" "2020-12-20 14:44 Coordinated Universal Time" "0.21" "Charliecloud"
.SH NAME
ch-build \- Build an image and place it in the builder's back-end storage
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-build [\-b BUILDER] [\-\-builder\-info] \-t TAG [ARGS ...] CONTEXT
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Build an image named \fBTAG\fP described by a Dockerfile. Place the result
into the builder’s back\-end storage.
.sp
Using this script is \fInot\fP required for a working Charliecloud image. You can
also use any builder that can produce a Linux filesystem tree directly,
whether or not it is in the list below. However, this script hides the
vagaries of making the supported builders work smoothly with Charliecloud and
adds some conveniences (e.g., pass HTTP proxy environment variables to the
build environment if the builder doesn’t do this by default).
.sp
Supported builders, unprivileged:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBbuildah\fP: Buildah in “rootless” mode with no setuid helpers, using
\fBch\-run\fP (via \fBch\-run\-oci\fP) for \fBRUN\fP instructions. This
requires Buildah v1.10.1+; see the install instructions.
.IP \(bu 2
\fBch\-image\fP: Our internal builder.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Supported builders, privileged:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBbuildah\-runc\fP: Buildah in “rootless” mode with setuid
helpers, using the default \fBrunc\fP for \fBRUN\fP instructions.
.IP \(bu 2
\fBbuildah\-setuid\fP: Buildah in “rootless” mode with setuid helpers,
using \fBch\-run\fP (via \fBch\-run\-oci\fP) for \fBRUN\fP
instructions.
.IP \(bu 2
\fBdocker\fP: Docker.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Specifying the builder, in descending order of priority:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fB\-b\fP, \fB\-\-builder BUILDER\fP
Command line option.
.TP
.B \fB$CH_BUILDER\fP
Environment variable
.TP
.B Default
\fBdocker\fP if Docker is installed; otherwise, \fBch\-image\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Other arguments:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fB\-\-builder\-info\fP
Print the builder to be used and its version, then exit.
.TP
.B \fB\-f\fP, \fB\-\-file DOCKERFILE\fP
Dockerfile to use (default: \fB$CONTEXT/Dockerfile\fP)
.TP
.B \fB\-t TAG\fP
Name (tag) of Docker image to build.
.TP
.B \fB\-\-help\fP
Print help and exit.
.TP
.B \fB\-\-version\fP
Print version and exit.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Additional arguments are accepted and passed unchanged to the underlying
builder.
.SH BUGS
.sp
The tag suffix \fB:latest\fP is somewhat misleading, as by default neither
\fBch\-build\fP nor bare builders will notice if the base \fBFROM\fP image
has been updated. Use \fB\-\-pull\fP to make sure you have the latest base
image.
.SH EXAMPLES
.sp
Create an image tagged \fBfoo\fP and specified by the file
\fBDockerfile\fP located in the context directory. Use \fB/bar\fP as the
Docker context directory. Use the default builder.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-build \-t foo /bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Equivalent to above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-build \-t foo \-\-file=/bar/Dockerfile /bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Instead, use \fB/bar/Dockerfile.baz\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-build \-t foo \-\-file=/bar/Dockerfile.baz /bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Equivalent to the first example, but use \fBch\-image\fP even if Docker is
installed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ch\-build \-b ch\-image \-t foo /bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Equivalent to above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export CH_BUILDER=ch\-image
$ ch\-build \-t foo /bar
.ft P
.fi
.UNINDENT
.UNINDENT
.SH REPORTING BUGS
.sp
If Charliecloud was obtained from your Linux distribution, use your
distribution’s bug reporting procedures.
.sp
Otherwise, report bugs to: <\fI\%https://github.com/hpc/charliecloud/issues\fP>
.SH SEE ALSO
.sp
charliecloud(7)
.sp
Full documentation at: <\fI\%https://hpc.github.io/charliecloud\fP>
.SH COPYRIGHT
2014–2020, Triad National Security, LLC
.\" Generated by docutils manpage writer.
.