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

NAME

6       ch-build  -  Wrapper  for  "docker build" that works around some of its
7       annoying behaviors
8

SYNOPSIS

10          $ ch-build -t TAG [ARGS ...] CONTEXT
11

DESCRIPTION

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
17       Sudo privileges are required to run the docker command.
18
19       Arguments:
20
21          --file Dockerfile to use (default: ./Dockerfile)
22
23          -t     name (tag) of Docker image to build
24
25          --help print help and exit
26
27          --version
28                 print version and exit
29
30       Additional arguments are accepted and passed unchanged to docker build.
31

IMPROVEMENTS OVER PLAIN DOCKER BUILD

33       ch-build adds the following features to docker build:
34
35       · If there is a file Dockerfile in the current working directory and -f
36         is not already specified, add -f $PWD/Dockerfile.
37
38       · Pass the HTTP proxy environment variables through with --build-arg.
39
40       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

EXAMPLES

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
51          $ ch-build -t foo /bar
52
53       Equivalent to above:
54
55          $ ch-build -t foo --file=./Dockerfile /bar
56
57       Instead, use the Dockerfile /baz/qux.docker:
58
59          $ ch-build -t foo --file=/baz/qux.docker /bar
60
61       Note that calling your Dockerfile anything other than  Dockerfile  will
62       confuse people.
63

REPORTING BUGS

65       If  Charliecloud  was  obtained  from your Linux distribution, use your
66       distribution’s bug reporting procedures.
67
68       Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
69

SEE ALSO

71       charliecloud(1)
72
73       Full documentation at: <https://hpc.github.io/charliecloud>
74

DOCKER TIPS

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
80   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
87   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
91       For  this  reason,  don’t  create  the docker group, as this will allow
92       passwordless, unlogged escalation for anyone in the group.
93
94   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
99   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
104   Docker alters your network configuration
105       To see what it did:
106
107          $ ifconfig    # note docker0 interface
108          $ brctl show  # note docker0 bridge
109          $ route -n
110
111   Docker installs services
112       If you don’t want the service starting automatically at boot, e.g.:
113
114          $ systemctl is-enabled docker
115          enabled
116          $ systemctl disable docker
117          $ systemctl is-enabled docker
118          disabled
119
120   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
124       The  first  problem  is that Docker itself must be told to use a proxy.
125       This manifests as:
126
127          $ 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
132       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
136       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
140       The fix is to set the proxy variables in your environment, e.g.:
141
142          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
151       You also need to teach sudo  to  retain  them.  Add  the  following  to
152       /etc/sudoers:
153
154          Defaults env_keep+="HTTP_PROXY http_proxy HTTPS_PROXY https_proxy ALL_PROXY all_proxy NO_PROXY no_proxy"
155
156       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

AUTHOR

162       Reid Priedhorsky, Tim Randles, and others
163
165       2014–2018, Los Alamos National Security, LLC
166
167
168
169
170                  2019-08-22 00:00 Coordinated Universal Time      CH-BUILD(1)
Impressum