ch-build(1)

1CH-BUILD(1)                      Charliecloud                      CH-BUILD(1)
2
3
4

NAME

6       ch-build  - Build an image and place it in the builder's back-end stor‐
7       age
8

SYNOPSIS

10          $ ch-build [-b BUILDER] [--builder-info] -t TAG [ARGS ...] CONTEXT
11

DESCRIPTION

13       Build an image named TAG described by a Dockerfile.  Place  the  result
14       into the builder’s back-end storage.
15
16       Using this script is not required for a working Charliecloud image. You
17       can also use any builder that  can  produce  a  Linux  filesystem  tree
18       directly,  whether or not it is in the list below. However, this script
19       hides the vagaries of making the supported builders work smoothly  with
20       Charliecloud and adds some conveniences (e.g., pass HTTP proxy environ‐
21       ment variables to the build environment if the builder doesn’t do  this
22       by default).
23
24       Supported builders, unprivileged:
25
26          · buildah:  Buildah in “rootless” mode with no setuid helpers, using
27            ch-run (via  ch-run-oci)  for  RUN  instructions.  This  currently
28            requires a patched Buildah; see the install instructions.
29
30          · ch-grow: Our internal builder.
31
32       Supported builders, privileged:
33
34          · buildah-runc:  Buildah  in  “rootless”  mode  with setuid helpers,
35            using the default runc for RUN instructions.
36
37          · buildah-setuid: Buildah in “rootless” mode  with  setuid  helpers,
38            using ch-run (via ch-run-oci) for RUN instructions.
39
40          · docker: Docker.
41
42       Specifying the builder, in descending order of priority:
43
44          -b, --builder BUILDER
45                 Command line option.
46
47          $CH_BUILDER
48                 Environment variable
49
50          Default
51                 docker if Docker is installed; otherwise, ch-grow.
52
53       Other arguments:
54
55          --builder-info
56                 Print the builder to be used and its version, then exit.
57
58          -f, --file DOCKERFILE
59                 Dockerfile to use (default: $CONTEXT/Dockerfile)
60
61          -t TAG Name (tag) of Docker image to build.
62
63          --help Print help and exit.
64
65          --version
66                 Print version and exit.
67
68       Additional  arguments are accepted and passed unchanged to the underly‐
69       ing builder.
70

BUGS

72       The tag suffix :latest is somewhat misleading, as  by  default  neither
73       ch-build  nor bare builders will notice if the base FROM image has been
74       updated. Use --pull to make sure you have the latest base image.
75

EXAMPLES

77       Create an image tagged foo and specified by the file Dockerfile located
78       in the context directory. Use /bar as the Docker context directory. Use
79       the default builder.
80
81          $ ch-build -t foo /bar
82
83       Equivalent to above:
84
85          $ ch-build -t foo --file=/bar/Dockerfile /bar
86
87       Instead, use /bar/Dockerfile.baz:
88
89          $ ch-build -t foo --file=/bar/Dockerfile.baz /bar
90
91       Equivalent to the first example, but use  ch-grow  even  if  Docker  is
92       installed:
93
94          $ ch-build -b ch-grow -t foo /bar
95
96       Equivalent to above:
97
98          $ export CH_BUILDER=ch-grow
99          $ ch-build -t foo /bar
100

REPORTING BUGS

102       If  Charliecloud  was  obtained  from your Linux distribution, use your
103       distribution’s bug reporting procedures.
104
105       Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
106

DOCKER TIPS

113       Docker  is  a  convenient  way  to  build  Charliecloud  images.  While
114       installing Docker is beyond the scope of this documentation, here are a
115       few tips.
116
117   Understand the security implications of Docker
118       Because Docker (a) makes  installing  random  crap  from  the  internet
119       really easy and (b) is easy to deploy insecurely, you should take care.
120       Some of the implications are below. This list should not be  considered
121       comprehensive  nor  a  substitute  for appropriate expertise; adhere to
122       your moral and institutional responsibilities.
123
124   docker equals root
125       Anyone who can run the docker command or interact with the Docker  dae‐
126       mon can trivially escalate to root.  This is considered a feature.
127
128       For  this  reason,  don’t  create  the docker group, as this will allow
129       passwordless, unlogged escalation for anyone in the group.
130
131   Images can contain bad stuff
132       Standard hygiene for “installing stuff from the internet” applies. Only
133       work  with  images  you trust. The official Docker Hub repositories can
134       help.
135
136   Containers run as root
137       By default, Docker runs container processes as  root.  In  addition  to
138       being  poor  hygiene,  this  can  be  an  escalation  path, e.g. if you
139       bind-mount host directories.
140
141   Docker alters your network configuration
142       To see what it did:
143
144          $ ifconfig    # note docker0 interface
145          $ brctl show  # note docker0 bridge
146          $ route -n
147
148   Docker installs services
149       If you don’t want the service starting automatically at boot, e.g.:
150
151          $ systemctl is-enabled docker
152          enabled
153          $ systemctl disable docker
154          $ systemctl is-enabled docker
155          disabled
156
157   Configuring for a proxy
158       By default, Docker does not work if you have a proxy, and it  fails  in
159       two different ways.
160
161       The  first  problem  is that Docker itself must be told to use a proxy.
162       This manifests as:
163
164          $ sudo docker run hello-world
165          Unable to find image 'hello-world:latest' locally
166          Pulling repository hello-world
167          Get https://index.docker.io/v1/repositories/library/hello-world/images: dial tcp 54.152.161.54:443: connection refused
168
169       If you have a systemd system, the Docker documentation explains how  to
170       configure   this.   If   you   don’t   have   a  systemd  system,  then
171       /etc/default/docker might be the place to go?
172
173       The second problem is that Docker containers need  to  know  about  the
174       proxy  as  well. This manifests as images failing to build because they
175       can’t download stuff from the internet.
176
177       The fix is to set the proxy variables in your environment, e.g.:
178
179          export HTTP_PROXY=http://proxy.example.com:8088
180          export http_proxy=$HTTP_PROXY
181          export HTTPS_PROXY=$HTTP_PROXY
182          export https_proxy=$HTTP_PROXY
183          export ALL_PROXY=$HTTP_PROXY
184          export all_proxy=$HTTP_PROXY
185          export NO_PROXY='localhost,127.0.0.1,.example.com'
186          export no_proxy=$NO_PROXY
187
188       You also need to teach sudo  to  retain  them.  Add  the  following  to
189       /etc/sudoers:
190
191          Defaults env_keep+="HTTP_PROXY http_proxy HTTPS_PROXY https_proxy ALL_PROXY all_proxy NO_PROXY no_proxy"
192
193       Because  different  programs  use different subsets of these variables,
194       and to avoid a situation where some things work and others  don’t,  the
195       Charliecloud  test suite (see below) includes a test that fails if some
196       but not all of the above variables are set.
197

COPYRIGHT

199       2014–2018, Los Alamos National Security, LLC
200
201
202
203
204                  2020-01-28 00:00 Coordinated Universal Time      CH-BUILD(1)