Skip to content

Commit f0dbb82

Browse files
vsochvsoch
committed
updating docker docs to explain entrypoint vs. cmd spec
1 parent 0dc7e94 commit f0dbb82

1 file changed

Lines changed: 68 additions & 22 deletions

File tree

‎pages/docs/user-docs/docs-docker.md‎

Lines changed: 68 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -19,34 +19,35 @@ The Docker engine communicates with the Docker Hub via the <a href="https://docs
1919
```bash
2020
sudo singularity create --size 4000 tensorflow.img
2121
sudo singularity import tensorflow.img docker://tensorflow/tensorflow:latest
22-
tensorflow/tensorflow:latest
23-
Downloading layer: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
24-
Downloading layer: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
25-
Downloading layer: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
26-
Downloading layer: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
27-
Downloading layer: sha256:b4c3589c6b3abaeb9d70269ad62f6fc522a00670ec7064b1ca42fa74f4b6f588
28-
Downloading layer: sha256:d63463802d368b6cb92c18e92ea3e5a5e3fd4a18c283ec19c0d56eef224748b5
29-
Downloading layer: sha256:709fc41158c625a33847d53e95ffe051fa80adbb9607ce8554f493c024cef300
30-
Downloading layer: sha256:528276ea4b2d54c35820437985d7ad944a2fcafb4bda4d98fa60976c657470e1
31-
Downloading layer: sha256:46d4527e85d3385ae7ac24f4dd442268b82d5e5e2de6c22a1eecf02ec8b79d42
32-
Downloading layer: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
33-
Downloading layer: sha256:da76ab5d6dffb48a4a7358699b84f0b7390640cc2c71a5421bfd9d73821ecb56
34-
Downloading layer: sha256:70d51ddf7c958a8df097423a32ec9ab9c02aff5c2e18758e51cf636a115a856c
35-
Downloading layer: sha256:ff4090f99abc02fe3e4604da28b87a8b770492158e20954b87e40e1b599b20f5
36-
Downloading layer: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
37-
Downloading layer: sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
38-
Downloading layer: sha256:c8144262002cd241e607d7d3ecda450ce4ae8edf7dac8dbf46897d498ac667d8
39-
Downloading layer: sha256:cee0974db2b868f0408f7e3eaba93c11fce3a38f612674477653b04c10369da0
40-
Downloading layer: sha256:390957b2f4f0cd72b8577795cd8076cdc21d45c7823bbb5c895a494ae6038267
41-
Downloading layer: sha256:064f9af025390d8da3dfab763fac261dd67f8807343613239d66304cda8f5d16
22+
Cache folder set to /home/vanessa/.singularity/docker
23+
Extracting /home/vanessa/.singularity/docker/sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4.tar.gz
24+
Extracting /home/vanessa/.singularity/docker/sha256:182b64c1f020de1cb4b2783b3a13fbeb07ec4087bc911352d0f5ef40c8eec8cf.tar.gz
25+
Extracting /home/vanessa/.singularity/docker/sha256:bfc1d5e3de1cf70353afb2b81fbbeab16bad961352b86f60901bc1da1396f2b4.tar.gz
26+
Extracting /home/vanessa/.singularity/docker/sha256:d819f1ec59a06c001b37e66dd1639c591e606029ea7584fac704ff741cda249b.tar.gz
27+
Extracting /home/vanessa/.singularity/docker/sha256:f5d83de9c6786bff4160679ed4bde332970367225ede609944bbe686edb1c25b.tar.gz
28+
Extracting /home/vanessa/.singularity/docker/sha256:c1f8f4c880d49d70a8280860e3bc5ee559a95d4e1dc44f9128b638eb2240324c.tar.gz
29+
Extracting /home/vanessa/.singularity/docker/sha256:9528c5352798ec3a134be13b66bc4dc71e7cdd029e268ae3cdfeb0719a4c8b8b.tar.gz
30+
Extracting /home/vanessa/.singularity/docker/sha256:c145c1f339f57690f80bd64e86caa3b00e0635a6a383bc8be7726a3baf22a0d2.tar.gz
31+
Extracting /home/vanessa/.singularity/docker/sha256:ebb77ce6e1c6769c1849194c1319dc6978e19575c76fd1fa942a623b6f2996a4.tar.gz
32+
Extracting /home/vanessa/.singularity/docker/sha256:51900bc9e720db035e12f6c425dd9c06928a9d1eb565c86572b3aab93d24cfca.tar.gz
33+
Extracting /home/vanessa/.singularity/docker/sha256:f8419ea7c1b5d667cf26c2c5ec0bfb3502872e5afc6aa85caf2b8c7650bdc8d9.tar.gz
34+
Extracting /home/vanessa/.singularity/docker/sha256:3eed5ff20a90a40b0cb7909e79128740f1320d29bec2ae9e025a1d375555db15.tar.gz
35+
Extracting /home/vanessa/.singularity/docker/sha256:6c953ac5d795ea26fd59dc5bdf4d335625c69f8bcfbdd8307d6009c2e61779c9.tar.gz
4236
Adding Docker CMD as Singularity runscript...
37+
/run_jupyter.sh
4338
Bootstrap initialization
4439
No bootstrap definition passed, updating container
4540
Executing Prebootstrap module
4641
Executing Postbootstrap module
4742
Done.
4843
```
4944

45+
Note that if you want (much) more detailed output for debugging to the console, you need to enable `--verbose` mode:
46+
47+
```bash
48+
sudo singularity --verbose import tensorflow.img docker://tensorflow/tensorflow:latest
49+
```
50+
5051
Now I can shell into it, and import tensorflow:
5152

5253
```bash
@@ -62,13 +63,29 @@ Type "help", "copyright", "credits" or "license" for more information.
6263
>>>
6364
```
6465

66+
### How does the runscript work?
67+
Docker has two commands in the `DOCKERFILE` that have something to do with execution, `CMD` and `ENTRYPOINT`. The differences are subtle, but the best description I've found is the following:
68+
69+
>> A `CMD` is to provide defaults for an executing container.
70+
71+
and
72+
73+
>> An `ENTRYPOINT` helps you to configure a container that you can run as an executable.
74+
75+
Given the definition, the `ENTRYPOINT` is most appropriate for the Singularity `%runscript`, and so using the default bootstrap (whether from a `docker://` endpoint or a `Singularity` spec file) will set the `ENTRYPOINT` variable as the runscript. You can change this behavior by specifying `IncludeCmd: yes` in the Spec file (see below). If you provide any sort of `%runscript` in your Spec file, this overrides anything provided in Docker. In summary, the order of operations is as follows:
76+
77+
1. If a `%runscript` is specified in the `Singularity` spec file, this takes prevalence over all
78+
2. If no `%runscript` is specified, or if the `import` command is used as in the example above, the `ENTRYPOINT` is used as runscript.
79+
3. If no `%runscript` is specified, but the user has a `Singularity` spec with `IncludeCmd`, then the Docker `CMD` is used.
80+
81+
6582
### Use a Spec File
6683
Do a barrel role! Use a spec file! Many times, you want to bootstrap an image, and then either change the `%runscript` or add additional software or commands in the `%post` section. To achieve this, you can create a specification file. Currently, these are distributed with the naming format `[myfile].def`, however (soon) we will use a standard name, `Singularity` so all specification files can be automatically found. Here is what the spec file would look like for tensorflow:
6784

85+
6886
```bash
6987
Bootstrap: docker
7088
From: tensorflow/tensorflow:latest
71-
IncludeCmd: yes
7289

7390
%runscript
7491

@@ -79,7 +96,36 @@ IncludeCmd: yes
7996
echo "Post install stuffs!"
8097
```
8198

82-
The solution above would be ideal for saving the specification of an image to build at some runtime.
99+
In the example above, I am overriding any Dockerfile `ENTRYPOINT` because I have defined a `%runscript`. If I want the Dockerfile `ENTRYPOINT` to take preference, I would remove the `%runscript` section:
100+
101+
```bash
102+
Bootstrap: docker
103+
From: tensorflow/tensorflow:latest
104+
105+
%post
106+
107+
echo "Post install stuffs!"
108+
```
109+
110+
Note that the spec file above would be (almost) equivalent to the command:
111+
112+
```bash
113+
sudo singularity import tensorflow.img docker://tensorflow/tensorflow:latest
114+
```
115+
116+
minus the useless echo at the end. If I want the `CMD` to take preference, I would add `IncludeCmd`:
117+
118+
```bash
119+
Bootstrap: docker
120+
From: tensorflow/tensorflow:latest
121+
IncludeCmd: yes
122+
123+
%post
124+
125+
echo "Post install stuffs!"
126+
```
127+
128+
The solutions above would be ideal for saving a custom specification of an image to build at some runtime.
83129

84130

85131
### Run a Singularity Shell from a Docker image

0 commit comments

Comments
 (0)