Singularity使用

1. 基本介绍

2024-12-04 更新：应该是最后一次更新该文档了，因为 singularity3.8之后改名为apptainer，后面使用的版本将变为apptainer，如有需要后面会更新相关apptainer文档(不一定哈，apptainer目前是完全兼容singularity命令，只是改了个名而已)。

Singularity User Guide: https://apptainer.org/user-docs/3.7/ , https://docs.sylabs.io/guides/3.7/user-guide/

Singularity使用户能够完全控制其操作系统环境。这意味着用户可以将主机上的操作系统“交换”给其他人。因此，如果主机系统运行RHEL6，但是您的应用程序在Ubuntu中运行，则可以创建一个Ubuntu映像，将应用程序安装到该映像中，将映像复制到另一个主机，并在该主机的本机Ubuntu环境中运行应用程序，总的来说Singularity类似于Docker。Singularity允许利用所在宿主机的资源。这包括HPC互连，资源管理器，文件系统，GPU和/或加速器等。 Singularity和Docker优缺点对比。

avatar

2. 安装

Ubuntu：
sudo apt-get update && sudo apt-get install python dh-autoreconf build-essential

Centos：
sudo yum update && sudo yum groupinstall 'Development Tools'

# clone可以选择release版本进行安装
$ git clone https://github.com/singularityware/singularity.git
$ cd singularity
$ ./autogen.sh
$ ./configure --prefix=/usr/local --sysconfdir=/etc
$ make
$ sudo make install

如果要安装singularity，可以参考官方文档：https://docs.sylabs.io/guides/3.7/admin-guide/installation.html#id4

3. 创建镜像

singularity 2.x版本

2024-12-04 更新：更新后请忽略2.x版本，版本过早，只要没有特别版本标注，都是在3.7的版本运行的。

$ singularity create container.img
# 默认创建镜像大小是768M,也可以指定大小进行创建
$ singularity create --size 2048 container2.img
Initializing Singularity image subsystem
Opening image file: container2.img
Creating 2048MiB image
Binding image to loop
Creating file system within image
Image is done: container2.img

singularity 3.x版本

build构建的几种方式：

以 library:// 开头的 URI，用于从容器库构建
以 docker:// 开头的 URI，用于从 Docker Hub 构建
以 shub:// 开头的 URI ，用于从 Singularity Hub 构建
本地机器上现有容器的路径
从沙箱构建的目录路径
Singularity定义文件的路径

构建镜像命令：

$ singularity build 镜像名 [构建文件|镜像地址]
# singularity build nginx.sif docker://nginx            # 从dockerhub上拉取镜像构建
# singularity build --sandbox nginx/ docker://nginx     # 创建沙盒镜像,从而对镜像进行调整
# singularity build nginx.sif nginx/                    # 把沙河镜像转化为容器镜像
# singularity build nginx.sif nginx.def                 # 根据nginx.def文件内容创建镜像

4. 定制化镜像

创建定义化镜像需要写一个singularity定义文件(简称’def文件’)，用于说明如何构建自定义容器。它包括有关要构建的基本操作系统或要从中启动的基本容器、要安装的软件、运行时要设置的环境变量、要从主机系统添加的文件以及容器元数据的具体信息。

下面以创建一个Tensorflow gpu镜像为例：

定义一个singularity文件：vi tensorflow.def

Bootstrap: docker
From: nvidia/cuda:8.0-cudnn5-devel-centos7

%files        # 把本地文件copy到容器内
    /my_test.py /opt

%environment  # 定义容器运行时的环境变量
    export LC_ALL=C

%post         # 创建容器时执行的命令
    # install other needed packages
    yum clean all
    yum -y update
    yum -y install epel-release
    yum -y install python-pip

    # install tensorflow
    pip install --upgrade pip
    pip install tensorflow-gpu

当文件定义好之后，创建镜像

singularity build tensorflow.sif tensorflow.def

Singularity也支持多阶段构建，具体请参阅【官方文档：https://docs.sylabs.io/guides/3.7/user-guide/definition_files.html】

5.常用命令

构建容器

$ singularity build 容器名 构建文件
# 例：singularity build centos.sif Singularity_centos
$ singularity build --sandbox 目录 构建文件 # 创建沙盒容器
# 例：singularity build --sandbox centos.sif Singularity_centos

交互模式运行

$ singularity shell centos.simg  # docker中：docker exec

$ singularity shell --writable 沙盒镜像目录 # 修改沙盒容器，比如修改容器内的脚本等

执行一个命令并退出

$ singularity exec ubuntu.simg bash -c  "pwd && id"
# SINGULARITYENV_环境变量名=变量  # 传入环境变量
# 例：SINGULARITYENV_myenv="test" singularity exec ubuntu.simg bash -c  "echo $myenv" # 在ubuntu镜像中输出myenv

运行一个容器
```
$ singularity run ubuntu.simg
```

共享文件 -B

$ singularity shell -B /test:/yangyang centos.simg  # 类似docker中：-v挂载
# 另一种写法
$ export SINGULARITY_BIND="/test:/home,/test1:/etc" # 定义挂载目录：
$ singularity shell centos.simg

启动容器(后台运行)
```
$ export SINGULARITY_TMPDIR=/home/tom/tmp
$ export TMPDIR=/home/tom/tmp

$ singularity instance start --nv \
	# --fakeroot \
    -B /home/tom:/home/tom,/home/tom/dataset:/home/dataset \
    /home/tom/singularity-images/caffe-2.1.simg \
    caffe-2
```
类似docker的 docker run,其中：
- --nv 启用 gpu 支持，类似 docker 之 --gpus all
- --fakeroot 确保容器内有权限（其实目前不加好像也完全可以）
  - 加了这个参数，会产生 rootfs-* 目录，见下一条。
- 两行 export 更改 Temporary Folders，防止 /tmp 被撑爆。
  - /tmp 可能磁盘容量少，就需要改去一个容量大的位置。
  - 加 --fakeroot 会在这个指定的 tmp dir 下生成形如 rootfs-* 的目录，stop 容器之后还在，要手动删。
- -B 挂载目录，类似 docker 之 -v。多个挂载点用逗号 , 分隔。
- caffe-2 是容器名（instance name），自己随便取，连接容器时要用。

查看已启动的容器

$ singularity instance list  # docker中：docker ps

关闭(并删除)容器
```
$ singularity instance stop caffe-2
```
关了就没有了！不像 docker stop，用 docker ps -a 还可以看到、可以重新 start。更像是 docker stop + docker rm。

所以没事别 stop，exit 就好。而如果加了 --fakeroot 记得 stop 之后删掉产生的 rootfs-* 目录。

6.docker镜像转singularity镜像

从本地缓存的docker image开始

假设本地有cvat_test镜像

$ sudo docker images
REPOSITORY             TAG       IMAGE ID       CREATED        SIZE
cvat_test              latest    99864098b836   18 hours ago   5.03GB

那么通过如下命令可从本地docker镜像构建SIF文件：

$ sudo singularity build cvat.sif docker-daemon://cvat_test:latest

从镜像tar文件开始

首先需要将docker镜像转成tar文件：

先查看当前的docker镜像

$ sudo docker images
REPOSITORY             TAG       IMAGE ID       CREATED        SIZE
cvat_test              latest    99864098b836   18 hours ago   5.03GB

使用如下命令将hello-world镜像转成tar文件，这里save后面的参数就是REPOSITORY，即上面输出的第一列，也可以用IMAGE ID

$ sudo docker save cvat_test > cvat_server.tar.gz

这样当前目录就出现了cvat_server.tar.gz文件

接着，将该tar文件转成singularity镜像，命令与输出如下：

[root@c1 cvat]# singularity build cvat.sif docker-archive://cvat_server.tar.gz
INFO:    Starting build...
Getting image source signatures
Copying blob 9f54eef41275 done  
Copying blob 02c9f2e52249 done  
Copying blob 86d3d150e62f done  
Copying blob 796e447f15d5 done  
Copying blob 7e82a140165d done  
Copying blob ecc7ee1bbc79 done  
Copying blob 857e5e0df091 done  
Copying blob 2cbe67cb4d23 done  
Copying blob c5bb6a7e3fa0 done  
Copying blob 1986e09a140d done  
Copying blob 4e21c169f069 done  
Copying blob 8c29af9d2e02 done  
Copying blob ee99ec45a8d9 done  
Copying blob 006f21023169 done  
Copying blob 1fb603f1640f done  
Copying blob 915e9f113b03 done  
Copying blob 546ced48c199 done  
Copying blob 4daab99c84ff done  
Copying config 04a3d041a2 done  
Writing manifest to image destination
Storing signatures
2021/12/07 03:18:36  info unpack layer: sha256:3b24facde3338a2702e333fe4508620811f065e8e7afd5c63659a7db8d873a85
2021/12/07 03:18:38  info unpack layer: sha256:ab529cd020627c4d33ee6ef15db880d8bbcc7ec1c79a667f47560933be5e72ed
2021/12/07 03:18:46  info unpack layer: sha256:9a51e28feb649d8446bbf948f3085b8e6901032ff492da5b8520cc516d8c2124
2021/12/07 03:18:46  info unpack layer: sha256:32f4885e7ac0c753b2b7cde222759689abef07b0516f12ee04301593e47ab6b6
2021/12/07 03:18:49  info unpack layer: sha256:837844c97cf8c8e5f447ab68f3938bc1ba7ce5568dca5a2535d0f8b740fa345d
2021/12/07 03:18:49  info unpack layer: sha256:5fe35ce69bd84d8ce9ccbb1c691320fb6937de4d3b923ef747721f2feac95508
2021/12/07 03:19:05  info unpack layer: sha256:3c0c839ed1250cb584affe4e1ebc5bd9b0566168a3a8da6849d86133206ee6f9
2021/12/07 03:19:05  info unpack layer: sha256:592379e47a6c7187ea111ed8046c98f0f08fa757d79fcc62b1449db966b27dcd
2021/12/07 03:19:48  info unpack layer: sha256:a8387041d4e4b5986c72901609614dddfe982ab1cfe337172d486c722b8ae050
2021/12/07 03:19:49  info unpack layer: sha256:8d2e92a0917b2e71ab84890e533c4b86bf9ee8ef4ce9f19aa05cf7f34c306abc
2021/12/07 03:19:49  info unpack layer: sha256:dd06917032e5828b93169586f8513a5aa36c059e413d6210ad3ae84e1b58b863
2021/12/07 03:19:49  info unpack layer: sha256:a03d3c79dad7cf6cc9d04987570f4438a2f17ab3164a1f42446e46d4ad2d0cfc
2021/12/07 03:19:49  info unpack layer: sha256:ae44033ceecd65c30d546b8c7e66d244e1b484986cc76abf9da63decd3d7560d
2021/12/07 03:19:49  info unpack layer: sha256:84422a2384d290f8a209f7012229bbdabc72073ed3b013ee1885982e11d4cf85
2021/12/07 03:19:49  info unpack layer: sha256:637558fd3aedcaf10a44407e0201b800856b9135600af4f1c461a3db75e5e880
2021/12/07 03:19:49  info unpack layer: sha256:2182a701fef9794262f8e3050b4e101d75c9936d78a8704f64398731185bdddb
2021/12/07 03:19:49  info unpack layer: sha256:16845234d72cf5a9f326acdcbcb857c664a3adc87763ee74b3dbae887b6ce1aa
2021/12/07 03:19:49  info unpack layer: sha256:3922c234a70e9b703212a63060756a5b33c472d8fdb974e9a6df4272b6f986bb
INFO:    Creating SIF file...
INFO:    Build complete: cvat.sif
[root@c1 cvat]# ls