|
| 1 | +--- |
| 2 | +title: Singularity Pull |
| 3 | +sidebar: user_docs |
| 4 | +permalink: docs-pull |
| 5 | +folder: docs |
| 6 | +toc: false |
| 7 | +--- |
| 8 | + |
| 9 | +Singularity `pull` is the command that you would want to use to communicate with a container registry. The command does exactly as it says - there exists an image external to my host, and I want to pull it here. We currently support pull for both <a href="https://hub.docker.com/" target="_blank">Docker</a> and <a href="https://singularity-hub.org" target="_blank">Singularity Hub</a> images, and will review usage for both. |
| 10 | + |
| 11 | + |
| 12 | +## Singularity Hub |
| 13 | +Singularity differs from Docker in that we serve entire images, as opposed to layers. This means that pulling a Singularity Hub means downloading the entire (compressed) container file, and then having it extract on your local machine. The basic command is the following: |
| 14 | + |
| 15 | +``` |
| 16 | +singularity pull shub://vsoch/hello-world |
| 17 | +Progress |===================================| 100.0% |
| 18 | +Done. Container is at: ./vsoch-hello-world-master.img |
| 19 | +``` |
| 20 | + |
| 21 | + |
| 22 | +### How do tags work? |
| 23 | +On Singularity Hub, a `tag` coincide with a branch. So if you have a repo called `vsoch/hello-world`, by default the file called `Singularity` (your build recipe file) will be looked for in the base of the master branch. The command that we issued above would be equivalent to doing: |
| 24 | + |
| 25 | +``` |
| 26 | +singularity pull shub://vsoch/hello-world:master |
| 27 | +``` |
| 28 | + |
| 29 | +To enable other branches to build, they must be turned on in your collection (more details are available in the <a href="https://singularity-hub.org/faq" target="_blank">Singularity Hub docs</a>). If you then put another `Singularity` file in a branch called development, you would pull it as follows: |
| 30 | + |
| 31 | +``` |
| 32 | +singularity pull shub://vsoch/hello-world:development |
| 33 | +``` |
| 34 | + |
| 35 | +The term `latest` in Singularity Hub will pull, across all of your branches, the most recent image. If `development` is more recent than `master`, it would be pulled, for example. |
| 36 | + |
| 37 | +### Image Names |
| 38 | +As you can see, since we didn't specify anything special, the default naming convention is to use the username, reponame, and the branch (tag). You have three options for changing this: |
| 39 | + |
| 40 | +``` |
| 41 | +PULL OPTIONS: |
| 42 | + -n/--name Specify a custom container name (first priority) |
| 43 | + -C/--commit Name container based on Github commit (second priority) |
| 44 | + -H/--hash Name container based on file hash (second priority) |
| 45 | +``` |
| 46 | + |
| 47 | +### Custom Name |
| 48 | + |
| 49 | +``` |
| 50 | +singularity pull --name meatballs.img shub://vsoch/hello-world |
| 51 | +Progress |===================================| 100.0% |
| 52 | +Done. Container is at: ./meatballs.img |
| 53 | +``` |
| 54 | + |
| 55 | +### Name by commit |
| 56 | +Each container build on Singularity Hub is associated with the Github commit of the repo that was used to build it. You can specify to name your container based on the commit with the `--commit` flag, if, for example, you want to match containers to their build files: |
| 57 | + |
| 58 | +``` |
| 59 | +singularity pull --commit shub://vsoch/hello-world |
| 60 | +Progress |===================================| 100.0% |
| 61 | +Done. Container is at: ./4187993b8b44cbfa51c7e38e6b527918fcdf0470.img |
| 62 | +``` |
| 63 | + |
| 64 | +### Name by hash |
| 65 | +If you prefer the hash of the file itself, you can do that too. |
| 66 | + |
| 67 | +``` |
| 68 | +singularity pull --hash shub://vsoch/hello-world |
| 69 | +Progress |===================================| 100.0% |
| 70 | +Done. Container is at: ./4db5b0723cfd378e332fa4806dd79e31.img |
| 71 | +``` |
| 72 | + |
| 73 | +### Pull to different folder |
| 74 | +For any of the above, if you want to specify a different folder for your image, you can define the variable `SINGULARITY_PULLFOLDER`. By default, we will first check if you have the `SINGULARITY_CACHEDIR` defined, and pull images there. If not, we look for `SINGULARITY_PULLFOLDER`. If neither of these are defined, the image is pulled to the present working directory, as we showed above. Here is an example of pulling to `/tmp`. |
| 75 | + |
| 76 | +``` |
| 77 | +SINGULARITY_PULLFOLDER=/tmp |
| 78 | +singularity pull shub://vsoch/hello-world |
| 79 | +Progress |===================================| 100.0% |
| 80 | +Done. Container is at: /tmp/vsoch-hello-world-master.img |
| 81 | +``` |
| 82 | + |
| 83 | +## Docker |
| 84 | +Docker pull is similar (on the surface) to a Singularity Hub pull, and we would do the following: |
| 85 | + |
| 86 | + |
| 87 | +``` |
| 88 | +singularity pull docker://ubuntu |
| 89 | +Initializing Singularity image subsystem |
| 90 | +Opening image file: ubuntu.img |
| 91 | +Creating 223MiB image |
| 92 | +Binding image to loop |
| 93 | +Creating file system within image |
| 94 | +Image is done: ubuntu.img |
| 95 | +Docker image path: index.docker.io/library/ubuntu:latest |
| 96 | +Cache folder set to /home/vanessa/.singularity/docker |
| 97 | +Importing: base Singularity environment |
| 98 | +Importing: /home/vanessa/.singularity/docker/sha256:b6f892c0043b37bd1834a4a1b7d68fe6421c6acbc7e7e63a4527e1d379f92c1b.tar.gz |
| 99 | +Importing: /home/vanessa/.singularity/docker/sha256:55010f332b047687e081a9639fac04918552c144bc2da4edb3422ce8efcc1fb1.tar.gz |
| 100 | +Importing: /home/vanessa/.singularity/docker/sha256:2955fb827c947b782af190a759805d229cfebc75978dba2d01b4a59e6a333845.tar.gz |
| 101 | +Importing: /home/vanessa/.singularity/docker/sha256:3deef3fcbd3072b45771bd0d192d4e5ff2b7310b99ea92bce062e01097953505.tar.gz |
| 102 | +Importing: /home/vanessa/.singularity/docker/sha256:cf9722e506aada1109f5c00a9ba542a81c9e109606c01c81f5991b1f93de7b66.tar.gz |
| 103 | +Importing: /home/vanessa/.singularity/metadata/sha256:fe44851d529f465f9aa107b32351c8a0a722fc0619a2a7c22b058084fac068a4.tar.gz |
| 104 | +Done. Container is at: ubuntu.img |
| 105 | +``` |
| 106 | + |
| 107 | +If you specify the tag, the image would be named accordingly (eg, `ubuntu-latest.img`). Did you notice that the output looks similar to if we did the following? |
| 108 | + |
| 109 | +``` |
| 110 | +singularity create ubuntu.img |
| 111 | +singularity import ubuntu.img docker://ubuntu |
| 112 | +``` |
| 113 | + |
| 114 | +this is because the same logic is happening on the back end. Thus, the pull command with a docker uri also supports arguments `--size` and `--name` Here is how I would pull an ubuntu image, but make it bigger, and name it something else. |
| 115 | + |
| 116 | +``` |
| 117 | +singularity pull --size 2000 --name jellybelly.img docker://ubuntu |
| 118 | +Initializing Singularity image subsystem |
| 119 | +Opening image file: jellybelly.img |
| 120 | +Creating 2000MiB image |
| 121 | +Binding image to loop |
| 122 | +Creating file system within image |
| 123 | +Image is done: jellybelly.img |
| 124 | +Docker image path: index.docker.io/library/ubuntu:latest |
| 125 | +Cache folder set to /home/vanessa/.singularity/docker |
| 126 | +Importing: base Singularity environment |
| 127 | +Importing: /home/vanessa/.singularity/docker/sha256:b6f892c0043b37bd1834a4a1b7d68fe6421c6acbc7e7e63a4527e1d379f92c1b.tar.gz |
| 128 | +Importing: /home/vanessa/.singularity/docker/sha256:55010f332b047687e081a9639fac04918552c144bc2da4edb3422ce8efcc1fb1.tar.gz |
| 129 | +Importing: /home/vanessa/.singularity/docker/sha256:2955fb827c947b782af190a759805d229cfebc75978dba2d01b4a59e6a333845.tar.gz |
| 130 | +Importing: /home/vanessa/.singularity/docker/sha256:3deef3fcbd3072b45771bd0d192d4e5ff2b7310b99ea92bce062e01097953505.tar.gz |
| 131 | +Importing: /home/vanessa/.singularity/docker/sha256:cf9722e506aada1109f5c00a9ba542a81c9e109606c01c81f5991b1f93de7b66.tar.gz |
| 132 | +Importing: /home/vanessa/.singularity/metadata/sha256:fe44851d529f465f9aa107b32351c8a0a722fc0619a2a7c22b058084fac068a4.tar.gz |
| 133 | +Done. Container is at: jellybelly.img |
| 134 | +``` |
0 commit comments