You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
New in Singularity version 2.4 you can use the `instance` command group to run instances of containers in the background. This is useful for running services like databases and web servers. The `instance.list` command lets you keep track of the named instances running in the background.
10
+
11
+
{% include toc.html %}
12
+
13
+
## Overview
14
+
After initiating one or more named instances to run in the background with the `instance.start` command you can list them with the `instance.list` command.
15
+
16
+
## Examples
17
+
These examples use a container from Singularity Hub, but you can use local containers or containers from Docker Hub as well. For a more detailed look at `instance` usage see [Running Instances](docs-instances).
18
+
19
+
### Start a few named instances from containers on Singularity Hub
New in Singularity version 2.4 you can use the `instance` command group to run instances of containers in the background. This is useful for running services like databases and web servers. The `instance.start` command lets you initiate a named instance in the background.
10
+
11
+
{% include toc.html %}
12
+
13
+
## Overview
14
+
To initiate a named instance of a container, you must call the `instance.start` command with 2 arguments: the name of the container that you want to start and a unique name for an instance of that container. Once the new instance is running, you can join the container's namespace using a URI style syntax like so:
15
+
16
+
```
17
+
$ singularity shell instance://<instance_name>
18
+
```
19
+
20
+
You can specify options such as bind mounts, overlays, or custom namespaces when you initiate a new instance of a container with `instance.start`. These options will persist as long as the container runs.
21
+
22
+
For a complete list of options see the output of:
23
+
24
+
```
25
+
singularity help instance.start
26
+
```
27
+
28
+
## Examples
29
+
These examples use a container from Singularity Hub, but you can use local containers or containers from Docker Hub as well. For a more detailed look at `instance` usage see [Running Instances](docs-instances).
30
+
31
+
### Start an instance called cow1 from a container on Singularity Hub
New in Singularity version 2.4 you can use the `instance` command group to run instances of containers in the background. This is useful for running services like databases and web servers. The `instance.stop` command lets you stop instances once you are finished using them
10
+
11
+
{% include toc.html %}
12
+
13
+
## Overview
14
+
After initiating one or more named instances to run in the background with the `instance.start` command you can stop them with the `instance.stop` command.
15
+
16
+
## Examples
17
+
These examples use a container from Singularity Hub, but you can use local containers or containers from Docker Hub as well. For a more detailed look at `instance` usage see [Running Instances](docs-instances).
18
+
19
+
### Start a few named instances from containers on Singularity Hub
Copy file name to clipboardExpand all lines: pages/docs/user-docs/docs-instances.md
+24-5Lines changed: 24 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,27 +20,27 @@ service nginx start
20
20
21
21
With older versions of Singularity, if you were to do something like this, from inside the container you would happily see the service start, and the web server running! But then if you were to log out of the container what would happen?
22
22
23
-
Ghost process within unreachable namespaces! It's like the walking dead!
23
+
Orphan process within unreachable namespaces!
24
24
25
-
You would lose control of the process. It would still be running, but you couldn't easily kill or interface with it. This is a called a ghost process, and it means that for running persistent services, Singularity was a non-starter.
25
+
You would lose control of the process. It would still be running, but you couldn't easily kill or interface with it. This is a called a orphan process. Singularity versions less than 2.4 were not designed to handle running services properly.
26
26
27
27
## Container Instances in Singularity
28
-
With Singularity 2.4 and the addition of container instances, the ability to cleanly, reliably, and safely run services in a container is here. First, let's put the commands of how to start our service into a script. Let's call it a `startscript`. And we can imagine this fitting into a build definition file like this:
28
+
With Singularity 2.4 and the addition of container instances, the ability to cleanly, reliably, and safely run services in a container is here. First, let's put some commands that we want our instance to execute into a script. Let's call it a `startscript`. This fits into a definition file like so:
29
29
30
30
```
31
31
%startscript
32
32
33
33
service nginx start
34
34
```
35
35
36
-
Now let's say we build a container with that startscript into an image called `nginx.img` and we want to run an nginx service. All we need to do is start the instance and the startscript will get run inside the container automatically:
36
+
Now let's say we build a container with that startscript into an image called `nginx.img` and we want to run an nginx service. All we need to do is start the instance with the [`instance.start`](docs-instance-start) command, and the startscript will run inside the container automatically:
37
37
38
38
```
39
39
[command] [image] [name of instance]
40
40
$ singularity instance.start nginx.img web
41
41
```
42
42
43
-
When we run that command, Singularity creates an isolated environment for the container instances' processes/services to live inside. We can confirm that this command started an instance by running the following command:
43
+
When we run that command, Singularity creates an isolated environment for the container instances' processes/services to live inside. We can confirm that this command started an instance by running the [`instance.list`](docs-instance-list) command like so:
When using `run` with an instance URI, the `runscript` will be executed inside of the instance. Similarly with `exec`, it will execute the given command in the instance.
92
92
93
+
When you are finished with your instance you can clean it up with the [`instance.stop`](docs-instance-stop) command like so:
94
+
95
+
```
96
+
$ singularity instance.stop web1
97
+
```
98
+
99
+
If you have multiple instances running and you want to stop all of them, you can do so with a wildcard:
100
+
101
+
```
102
+
$ singularity instance.stop \*
103
+
```
104
+
105
+
Note that you must escape the wildcard with a backslash like this `\*` to pass it properly.
106
+
93
107
## Putting it all together
94
108
95
109
In this section, we will demonstrate an example of packaging a service into a container and running it. The service we will be packaging is an API server that converts a web page into a PDF, and can be found [here](https://github.com/alvarcarto/url-to-pdf-api). The final example can be found [here on GitHub](https://github.com/bauerm97/instance-example), and [here on SingularityHub](https://singularity-hub.org/collections/bauerm97/instance-example/). If you wish to just download the final image directly from Singularity Hub, simply run `singularity pull shub://bauerm97/instance-example`.
@@ -240,6 +254,11 @@ $ ls out/
240
254
google.pdf
241
255
```
242
256
257
+
When you are finished, use the `instance.stop` command to close all running instances.
0 commit comments