1CH-BUILD(1) Charliecloud CH-BUILD(1)
2
6 ch-build - Wrapper for "docker build" that works around some of its
7 annoying behaviors
8
10 $ ch-build -t TAG [ARGS ...] CONTEXT
11
13 Build a Docker image named TAG described by Dockerfile ./Dockerfile or
14 as specified. This is a wrapper for docker build with various enhance‐
15 ments.
16 Sudo privileges are required to run the docker command.
18 Arguments:
20 --file Dockerfile to use (default: ./Dockerfile)
22 -t name (tag) of Docker image to build
24 --help print help and exit
26 --version
28 print version and exit
29 Additional arguments are accepted and passed unchanged to docker build.
31
33 ch-build adds the following features to docker build:
34 · If there is a file Dockerfile in the current working directory and -f
36 is not already specified, add -f $PWD/Dockerfile.
37 · Pass the HTTP proxy environment variables through with --build-arg.
39 NOTE:
41 The suffix :latest is somewhat misleading, as neither ch-build nor
42 bare docker build will notice if the base FROM image has been
43 updated. Use --no-cache to make sure you have the latest base image,
44 at the cost of rebuilding every layer.
45
47 Create a Docker image tagged foo and specified by the file Dockerfile
48 located in the current working directory. Use /bar as the Docker con‐
49 text directory:
50 $ ch-build -t foo /bar
52 Equivalent to above:
54 $ ch-build -t foo --file=./Dockerfile /bar
56 Instead, use the Dockerfile /baz/qux.docker:
58 $ ch-build -t foo --file=/baz/qux.docker /bar
60 Note that calling your Dockerfile anything other than Dockerfile will
62 confuse people.
63
65 If Charliecloud was obtained from your Linux distribution, use your
66 distribution’s bug reporting procedures.
67 Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
69
71 charliecloud(1)
72 Full documentation at: <https://hpc.github.io/charliecloud>
74
76 Docker is a convenient way to build Charliecloud images. While
77 installing Docker is beyond the scope of this documentation, here are a
78 few tips.
79 Understand the security implications of Docker
81 Because Docker (a) makes installing random crap from the internet
82 really easy and (b) is easy to deploy insecurely, you should take care.
83 Some of the implications are below. This list should not be considered
84 comprehensive nor a substitute for appropriate expertise; adhere to
85 your moral and institutional responsibilities.
86 docker equals root
88 Anyone who can run the docker command or interact with the Docker dae‐
89 mon can trivially escalate to root. This is considered a feature.
90 For this reason, don’t create the docker group, as this will allow
92 passwordless, unlogged escalation for anyone in the group.
93 Images can contain bad stuff
95 Standard hygiene for “installing stuff from the internet” applies. Only
96 work with images you trust. The official Docker Hub repositories can
97 help.
98 Containers run as root
100 By default, Docker runs container processes as root. In addition to
101 being poor hygiene, this can be an escalation path, e.g. if you
102 bind-mount host directories.
103 Docker alters your network configuration
105 To see what it did:
106 $ ifconfig # note docker0 interface
108 $ brctl show # note docker0 bridge
109 $ route -n
110 Docker installs services
112 If you don’t want the service starting automatically at boot, e.g.:
113 $ systemctl is-enabled docker
115 enabled
116 $ systemctl disable docker
117 $ systemctl is-enabled docker
118 disabled
119 Configuring for a proxy
121 By default, Docker does not work if you have a proxy, and it fails in
122 two different ways.
123 The first problem is that Docker itself must be told to use a proxy.
125 This manifests as:
126 $ sudo docker run hello-world
128 Unable to find image 'hello-world:latest' locally
129 Pulling repository hello-world
130 Get https://index.docker.io/v1/repositories/library/hello-world/images: dial tcp 54.152.161.54:443: connection refused
131 If you have a systemd system, the Docker documentation explains how to
133 configure this. If you don’t have a systemd system, then
134 /etc/default/docker might be the place to go?
135 The second problem is that Docker containers need to know about the
137 proxy as well. This manifests as images failing to build because they
138 can’t download stuff from the internet.
139 The fix is to set the proxy variables in your environment, e.g.:
141 export HTTP_PROXY=http://proxy.example.com:8088
143 export http_proxy=$HTTP_PROXY
144 export HTTPS_PROXY=$HTTP_PROXY
145 export https_proxy=$HTTP_PROXY
146 export ALL_PROXY=$HTTP_PROXY
147 export all_proxy=$HTTP_PROXY
148 export NO_PROXY='localhost,127.0.0.1,.example.com'
149 export no_proxy=$NO_PROXY
150 You also need to teach sudo to retain them. Add the following to
152 /etc/sudoers:
153 Defaults env_keep+="HTTP_PROXY http_proxy HTTPS_PROXY https_proxy ALL_PROXY all_proxy NO_PROXY no_proxy"
155 Because different programs use different subsets of these variables,
157 and to avoid a situation where some things work and others don’t, the
158 Charliecloud test suite (see below) includes a test that fails if some
159 but not all of the above variables are set.
160
162 Reid Priedhorsky, Tim Randles, and others
163
165 2014–2018, Los Alamos National Security, LLC
166 2019-08-22 00:00 Coordinated Universal Time CH-BUILD(1)