Skip to content

Commit 350143d

Browse files
gemfieldgemfield
committed
refactor docs
1 parent c4247c1 commit 350143d

File tree

2 files changed

+156
-149
lines changed

2 files changed

+156
-149
lines changed

‎README.md

Lines changed: 17 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ MLab是为云上炼丹师服务的云基础设施。由以下部分组成：
1212

1313
# MLab HomePod
1414
迄今为止最先进的容器化PyTorch训练环境。
15-
MLab HomePod以Docker image形式封装，也是我们的深度学习训练环境。HomePod有着鲜明的特点：
15+
MLab HomePod以Docker image形式封装，是我们的深度学习训练环境。 HomePod有着鲜明的特点：
1616
- 基于最新的Ubuntu LTS(20.04)；
1717
- 基于最新的KDE Plasma(5.21.4);
1818
- 基于最新的KDE Framework(5.82.0);
@@ -30,174 +30,42 @@ MLab HomePod以Docker image形式封装，也是我们的深度学习训练环
3030

3131
## 1. 部署
3232
MLab HomePod有三种部署方式：
33-
- 纯粹的Docker命令行方式：
33+
- 纯粹的Docker命令行方式，部署且运行后只能在命令行里工作。
3434
```bash
3535
docker run --gpus all -it --entrypoint=/bin/bash gemfield/homepod:1.1
3636
```
37-
部署且运行后只能在命令行里工作。
38-
- 图形化的Docker部署方式：
37+
38+
- 图形化的Docker部署方式，部署后可以在vnc客户端和浏览器中访问图形界面。
3939
```bash
4040
docker run --gpus all -it -p 7030:7030 -p 5900:5900 gemfield/homepod:1.1
4141
```
42-
部署后可以在vnc客户端和浏览器中访问图形界面。
43-
- k8s集群部署方式（需要k8s集群运维经验，适合小团队的协作管理）：
44-
```bash
45-
#针对自身的集群环境修改yaml后
46-
kubectl apply -f HomePod/homepod.yaml
47-
kubectl apply -f HomePod/airlock.yaml
48-
kubectl apply -f HomePod/uploadmlab.yaml
49-
kubectl apply -f HomePod/network.yaml
50-
```
51-
部署后可以在vnc客户端和浏览器中访问图形界面，这种方式适合小团队的协作和管理。
42+
43+
- k8s集群部署方式（需要k8s集群运维经验，适合小团队的协作管理）。
44+
请访问[基于k8s部署HomePod](./docs/k8s_usage.md)以获得更多注意事项。
5245

5346
## 2. 登录
54-
三种方式中的第一种无需赘述，后两种部署方式都使用的是图形界面，支持两种方式访问：
47+
三种部署方式中的第一种无需赘述，后两种部署成功后使用图形界面进行登录和使用。支持两种使用方式：
5548
- 1，浏览器(http://your_host:7030);
56-
- 2，realvnc客户端：https://www.realvnc.com/en/connect/download/viewer/ 。
49+
- 2，realvnc客户端：https://www.realvnc.com/en/connect/download/viewer/ 。realvnc公司承诺viewer永远免费使用。
5750

5851
其中，浏览器方式的优点是方便；VNC客户端方式的优点是流畅，且功能更多。
5952

6053
## 3. 密码与登出
61-
HomePod默认提供了一个普通用户和root用户：
62-
- 普通用户初始密码为：gemfield
63-
- root用户初始密码为：<请咨询maintainer>
54+
HomePod默认提供了用户:gemfield，初始密码:gemfield。
55+
56+
如果要改变该默认行为，请在docker命令行上（或者k8s yaml中）注入以下环境变量：
57+
- DEEPVAC_USER=your_name
58+
- DEEPVAC_PASSWORD=your_password
59+
- HOME=/home/your_name
6460

6561
为了安全，用户在初始登录HomePod后，需要：
6662
- 修改自己的用户密码；
67-
- 修改root用户的密码；
63+
- 使用sudo命令修改root用户的密码；
6864
- 公司和家庭以外环境使用HomePod需要提前报备；
6965
- 离开电脑5分钟以上，需要手工锁定屏幕（KDE -> Leave -> Lock(Lock screen)）。
7066

7167
## 4. 文件权限问题解决
72-
在HomePod中工作的时候，默认都在自己的用户下工作。如果遇到历史遗留文件的权限问题，那么切换为root用户：
68+
在HomePod中工作的时候，默认都在自己的用户下工作。如果遇到历史遗留文件的权限问题，那么可以使用sudo命令(1.1版本及以后)：
7369
- 如果该文件是自己所有，则使用chown命令将文件的owner更改为自己；
7470
- 如果该文件是公共所有，则使用chmod命令将文件的read权限为所有人打开。
7571

76-
完成权限的更改后，再通过exit命令从root用户退回到自己的用户。注意：**不能在root会话中新建会话！！！**。
77-
78-
## 5. 网络策略（仅限k8s集群部署方式）
79-
HomePod为组织内部使用的开发环境，因此默认配有较为严格的防火墙策略。在HomePod上，用户**只能连接MLab代码服务**。除此之外，用户无法访问（也不应该访问）**其它任何服务器**（首次发现某个漏洞的人，发30元红包）。
80-
81-
然而，用户在HomePod上仍然会有一些合理的（或者半合理的）联网需求，我们总结如下：
82-
- 上传或者下载一些数据集到HomePod上（合理需求）；
83-
- HomePod上使用包管理工具（pip、apt等）安装软件包（半合理需求）；
84-
- 下载HomePod上训练结果的输出，分发给客户或其它测试人员（半合理需求）。
85-
86-
为了实现这些合理或者半合理需求，我们提供了**Airlock Pod**（ai5.gemfield.org:27031）。Airlock Pod和HomePod共享一个docker镜像，且共享/opt/public/airlock目录。区别在于3点：
87-
- Airlock Pod可以访问外部网络；
88-
- Airlock Pod对/opt/public/airlock 目录有写权限；
89-
- Airlock Pod没有隐私可言。
90-
91-
#### 5.1 上传或者下载一些数据集到HomePod上
92-
使用Airlock Pod。一旦数据来到Airlock Pod的/opt/public/airlock目录下，用户可以从自己的HomePod中拷贝到自己的HomePod本地。
93-
那么数据如何来到Airlock Pod的/opt/public/airlock目录下呢？有多种方法：
94-
- 在Airlock Pod上使用ftp、wget、scp、git等工具，从外部环境下载到此目录；
95-
- 使用http://ai5.gemfield.org:5212 上传服务上传（该服务支持webdav挂载到本地，详情请咨询管理员）。
96-
97-
#### 5.2 HomePod上使用包管理工具（pip、apt等）安装软件包
98-
软件包按照被使用的普及程度分为两类：基础型软件包、特定软件包。
99-
基础性软件包就是几乎人人都会用到的，比如numpy、cmake、cv2等；
100-
特定软件包就是几乎只有自己的特定项目会使用到，比如fonttools。
101-
102-
基础软件包和特定软件包都提供了临时安装方法（所谓临时安装，就是在HomePod重启后会丢失）：
103-
- pip包临时安装：
104-
```bash
105-
# 在airlock上
106-
gemfield@airlock:/opt/public/airlock/pip$ pip download <pip-package>
107-
108-
# 切换到homepod上
109-
username@homepod:/opt/public/airlock/pip$ pip install *
110-
```
111-
- apt包临时安装：
112-
```
113-
# 在airlock上（这种方式下载deb包到当前目录）
114-
gemfield@airlock:/opt/public/airlock/apt$ apt-get download <apt-package>
115-
# 或者（这种方式下载该包及所有的依赖包到/var/cache/apt/archives）
116-
gemfield@airlock:/opt/public/airlock/apt$ apt-get install --download-only <apt-package>
117-
118-
119-
# 切换到homepod上
120-
root@homepod:/opt/public/airlock/apt$ dpkg -i <apt-package>
121-
```
122-
123-
此外，基础软件包应该固化到HomePod的image中。用户按照如下的方法提交固化申请：
124-
- 将安装步骤封装为bash脚本，在Airlock Pod上测试成功（一定要测试成功！！！）；
125-
- 然后该脚本连同安装需求描述提交到https://github.com/DeepVAC/MLab 的issues里，通知管理员。
126-
127-
#### 5.3 下载HomePod上训练结果的输出，分发给客户或其它测试人员
128-
这个是罕见需求，目前只能：
129-
- 联系管理员。
130-
131-
## 6. 在HomePod上维护github项目（仅限k8s集群部署方式）
132-
通常情况下，如果想要参与github项目的开发维护，则直接在自己的私人电脑或者办公电脑上完成即可。但有时候，这些项目的开发维护需要借助MLab HomePod上的资源（比如CUDA设备、数据集、已训练模型等），但由于HomePod的网络策略，我们并没有办法直接在HomePod上访问github这样的外网。那则么办呢？借助MLab代码服务。
133-
#### 6.1 申请在HomePod上维护某github项目
134-
只有符合产品研发需要的github项目才会被批准。批准的标志就是该github项目会出现在MLab代码服务上。下文我们就以DeepVAC项目为例(https://github.com/DeepVAC/deepvac)。
135-
HomePod用户向管理员发出在HomePod上维护DeepVAC的申请，管理员批准，DeepVAC项目出现在MLab代码服务上：http://ai1.gemfield.org/deepvac/deepvac
136-
137-
#### 6.2 在办公电脑上配置git
138-
- 在github上fork DeepVAC仓库；
139-
- 克隆你的fork：git clone https://github.com/<your_name>/deepvac
140-
- 在仓库中添加remote（注意，由于前述的clone仓库，git已经默认帮你配好了origin这个默认的remote）：
141-
```bash
142-
#添加mlab remote
143-
git remote add mlab http://ai1.gemfield.org/deepvac/deepvac
144-
145-
#添加upstream
146-
git remote add upstream https://github.com/DeepVAC/deepvac
147-
```
148-
- 验证remote添加成功
149-
```bash
150-
gemfield@ThinkPad-X1C:/github/deepvac$ git remote -v
151-
mlab http://ai1.gemfield.org/deepvac/deepvac (fetch)
152-
mlab http://ai1.gemfield.org/deepvac/deepvac (push)
153-
origin https://github.com/<your_name>/deepvac (fetch)
154-
origin https://github.com/<your_name>/deepvac (push)
155-
upstream https://github.com/DeepVAC/deepvac (fetch)
156-
upstream https://github.com/DeepVAC/deepvac (push)
157-
```
158-
#### 6.3 在办公电脑上新建轻量级工作分支
159-
假设你现在需要往deepvac提交feature1。则需要在办公电脑上（想想为什么？）按照如下的步骤：
160-
```bash
161-
#同步上游
162-
git fetch upstream
163-
git rebase upstream/master
164-
#新建工作分支
165-
git checkout -b feature_1
166-
#同步到MLab
167-
git push mlab feature_1
168-
```
169-
注意：完成上述步骤后，办公电脑上该仓库就停留在feature_1分支上。
170-
171-
#### 6.4 在HomePod上开发、测试、提交
172-
以下步骤在HomePod上：
173-
```bash
174-
#克隆代码
175-
git clone http://ai1.gemfield.org/deepvac/deepvac
176-
177-
#切换（注意不是新建）
178-
git checkout feature_1
179-
180-
#开发、测试
181-
......
182-
git add
183-
git commit -m "xxx"
184-
185-
#将feature_1同步到mlab上
186-
git push feature_1
187-
```
188-
189-
#### 6.5 在办公电脑上同步feature_1分支
190-
以下步骤在办公电脑上，且在之前停留的feature_1分支上：
191-
```bash
192-
#同步feature_1分支
193-
git fetch mlab
194-
git rebase mlab/feature_1
195-
196-
#同步到自己fork的deepvac上
197-
git push feature_1
198-
```
199-
200-
#### 6.6 在github上创建PR
201-
在github网页上，切换到自己fork的deepvac项目上，创建PR。
202-
203-
**注意：自始至终，办公电脑上没有发生任何的开发。这不是必须的，但不这么做会增加git流程的复杂度。**

‎docs/k8s_usage.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# 在K8s集群中使用MLab HomePod
2+
在K8s集群上部署MLab HomePod，一方面可以获得更灵活和多元的功能，另外一方面也可以更好的对数据进行权限控制。
3+
4+
## 1. 部署
5+
使用kubectl命令进行部署，部署后可以在vnc客户端和浏览器中访问图形界面。这种方式适合小团队的协作和管理。
6+
```bash
7+
#针对自身的集群环境修改yaml后
8+
kubectl apply -f HomePod/homepod.yaml
9+
kubectl apply -f HomePod/airlock.yaml
10+
kubectl apply -f HomePod/uploadmlab.yaml
11+
kubectl apply -f HomePod/network.yaml
12+
```
13+
14+
## 2. 网络策略
15+
HomePod为组织内部使用的开发环境，因此默认配有较为严格的防火墙策略。在HomePod上，用户**只能连接MLab代码服务**。除此之外，用户无法访问（也不应该访问）**其它任何服务器**（首次发现某个漏洞的人，发30元红包）。
16+
17+
然而，用户在HomePod上仍然会有一些合理的（或者半合理的）联网需求，我们总结如下：
18+
- 上传或者下载一些数据集到HomePod上（合理需求）；
19+
- HomePod上使用包管理工具（pip、apt等）安装软件包（半合理需求）；
20+
- 下载HomePod上训练结果的输出，分发给客户或其它测试人员（半合理需求）。
21+
22+
为了实现这些合理或者半合理需求，我们提供了**Airlock Pod**（ai5.gemfield.org:27031，该地址取决于你的实际部署）。Airlock Pod和HomePod共享一个docker镜像，且共享/opt/public/airlock目录。区别在于3点：
23+
- Airlock Pod可以访问外部网络；
24+
- Airlock Pod对/opt/public/airlock 目录有写权限；
25+
- Airlock Pod没有隐私可言。
26+
27+
#### 2.1 上传或者下载一些数据集到HomePod上
28+
使用Airlock Pod。一旦数据来到Airlock Pod的/opt/public/airlock目录下，用户可以从自己的HomePod中拷贝到自己的HomePod本地。
29+
那么数据如何来到Airlock Pod的/opt/public/airlock目录下呢？有多种方法：
30+
- 在Airlock Pod上使用ftp、wget、scp、git等工具，从外部环境下载到此目录；
31+
- 使用http://ai5.gemfield.org:5212 （该地址取决于你的实际部署）上传服务上传（该服务支持webdav挂载到本地，详情请咨询管理员）。
32+
33+
#### 2.2 HomePod上使用包管理工具（pip、apt等）安装软件包
34+
软件包按照被使用的普及程度分为两类：基础型软件包、特定软件包。
35+
基础性软件包就是几乎人人都会用到的，比如numpy、cmake、cv2等；
36+
特定软件包就是几乎只有自己的特定项目会使用到，比如fonttools。
37+
38+
基础软件包和特定软件包都提供了临时安装方法（所谓临时安装，就是在HomePod重启后会丢失）：
39+
- pip包临时安装：
40+
```bash
41+
# 在airlock上
42+
gemfield@airlock:/opt/public/airlock/pip$ pip download <pip-package>
43+
44+
# 切换到homepod上
45+
username@homepod:/opt/public/airlock/pip$ pip install *
46+
```
47+
- apt包临时安装：
48+
```
49+
# 在airlock上（这种方式下载deb包到当前目录）
50+
gemfield@airlock:/opt/public/airlock/apt$ apt-get download <apt-package>
51+
# 或者（这种方式下载该包及所有的依赖包到/var/cache/apt/archives）
52+
gemfield@airlock:/opt/public/airlock/apt$ apt-get install --download-only <apt-package>
53+
54+
55+
# 切换到homepod上
56+
root@homepod:/opt/public/airlock/apt$ dpkg -i <apt-package>
57+
```
58+
59+
此外，基础软件包应该固化到HomePod的image中。用户按照如下的方法提交固化申请：
60+
- 将安装步骤封装为bash脚本，在Airlock Pod上测试成功（一定要测试成功！！！）；
61+
- 然后该脚本连同安装需求描述提交到https://github.com/DeepVAC/MLab 的issues里，通知管理员。
62+
63+
#### 2.3 下载HomePod上训练结果的输出，分发给客户或其它测试人员
64+
这个是罕见需求，目前只能：
65+
- 联系管理员。
66+
67+
## 3. 在HomePod上维护github项目
68+
通常情况下，如果想要参与github项目的开发维护，则直接在自己的私人电脑或者办公电脑上完成即可。但有时候，这些项目的开发维护需要借助MLab HomePod上的资源（比如CUDA设备、数据集、已训练模型等），但由于HomePod的网络策略，我们并没有办法直接在HomePod上访问github这样的外网。那则么办呢？借助MLab代码服务。
69+
#### 3.1 申请在HomePod上维护某github项目
70+
只有符合产品研发需要的github项目才会被批准。批准的标志就是该github项目会出现在MLab代码服务上。下文我们就以DeepVAC项目为例(https://github.com/DeepVAC/deepvac)。
71+
HomePod用户向管理员发出在HomePod上维护DeepVAC的申请，管理员批准，DeepVAC项目出现在MLab代码服务上：http://ai1.gemfield.org/deepvac/deepvac
72+
73+
#### 3.2 在办公电脑上配置git
74+
- 在github上fork DeepVAC仓库；
75+
- 克隆你的fork：git clone https://github.com/<your_name>/deepvac
76+
- 在仓库中添加remote（注意，由于前述的clone仓库，git已经默认帮你配好了origin这个默认的remote）：
77+
```bash
78+
#添加mlab remote
79+
git remote add mlab http://ai1.gemfield.org/deepvac/deepvac
80+
81+
#添加upstream
82+
git remote add upstream https://github.com/DeepVAC/deepvac
83+
```
84+
- 验证remote添加成功
85+
```bash
86+
gemfield@ThinkPad-X1C:/github/deepvac$ git remote -v
87+
mlab http://ai1.gemfield.org/deepvac/deepvac (fetch)
88+
mlab http://ai1.gemfield.org/deepvac/deepvac (push)
89+
origin https://github.com/<your_name>/deepvac (fetch)
90+
origin https://github.com/<your_name>/deepvac (push)
91+
upstream https://github.com/DeepVAC/deepvac (fetch)
92+
upstream https://github.com/DeepVAC/deepvac (push)
93+
```
94+
#### 3.3 在办公电脑上新建轻量级工作分支
95+
假设你现在需要往deepvac提交feature1。则需要在办公电脑上（想想为什么？）按照如下的步骤：
96+
```bash
97+
#同步上游
98+
git fetch upstream
99+
git rebase upstream/master
100+
#新建工作分支
101+
git checkout -b feature_1
102+
#同步到MLab
103+
git push mlab feature_1
104+
```
105+
注意：完成上述步骤后，办公电脑上该仓库就停留在feature_1分支上。
106+
107+
#### 3.4 在HomePod上开发、测试、提交
108+
以下步骤在HomePod上：
109+
```bash
110+
#克隆代码
111+
git clone http://ai1.gemfield.org/deepvac/deepvac
112+
113+
#切换（注意不是新建）
114+
git checkout feature_1
115+
116+
#开发、测试
117+
......
118+
git add
119+
git commit -m "xxx"
120+
121+
#将feature_1同步到mlab上
122+
git push feature_1
123+
```
124+
125+
#### 3.5 在办公电脑上同步feature_1分支
126+
以下步骤在办公电脑上，且在之前停留的feature_1分支上：
127+
```bash
128+
#同步feature_1分支
129+
git fetch mlab
130+
git rebase mlab/feature_1
131+
132+
#同步到自己fork的deepvac上
133+
git push feature_1
134+
```
135+
136+
#### 3.6 在github上创建PR
137+
在github网页上，切换到自己fork的deepvac项目上，创建PR。
138+
139+
**注意：自始至终，办公电脑上没有发生任何的开发。这不是必须的，但不这么做会增加git流程的复杂度。**

0 commit comments

Comments
 (0)