docker深入2

zzgzyyz

　　docker深入2-UI之portainer的二次开发
　　2017/10/18
　　

　　


一、准备环境
依赖：Docker, Node.js >= 0.8.4 和 npm
[root@dev_08 ~]# curl --silent --location https://rpm.nodesource.com/setup_7.x | sudo bash -
[root@dev_08 ~]# yum install -y nodejs
[root@dev_08 ~]# npm install -g grunt-cli
二、构建
1、checkout
[root@dev_08 ~]# cd /opt
先 fork 一个 portainer的分支，然后 clone 到本地， 然后在 branch 上开发，例如：
[root@dev_08 opt]# git clone https://github.com/opera443399/portainer.git
[root@dev_08 opt]# cd portainer
[root@dev_08 portainer]# git checkout -b feat-add-container-console-on-task-details
Switched to a new branch 'feat-add-container-console-on-task-details'
[root@dev_08 portainer]# git branch
  develop
* feat-add-container-console-on-task-details

2、使用 npm 安装依赖包
[root@dev_08 portainer]# npm install -g bower && npm install
3、根目录没有这个目录： bower_components 的话则执行
[root@dev_08 portainer]# bower install --allow-root

4、针对 centos 执行
[root@dev_08 portainer]# ln -s /usr/bin/sha1sum /usr/bin/shasum

5、构建 app
[root@dev_08 portainer]# grunt build
如果遇到这样的错误：
Building portainer for linux-amd64
/go/src/github.com/portainer/portainer/crypto/crypto.go:4:2: cannot find package "golang.org/x/crypto/bcrypt" in any of:
/usr/local/go/src/golang.org/x/crypto/bcrypt (from $GOROOT)
/go/src/golang.org/x/crypto/bcrypt (from $GOPATH)
/go/src/github.com/portainer/portainer/http/handler/websocket.go:21:2: cannot find package "golang.org/x/net/websocket" in any of:
/usr/local/go/src/golang.org/x/net/websocket (from $GOROOT)
/go/src/golang.org/x/net/websocket (from $GOPATH)
mv: cannot stat ‘api/cmd/portainer/portainer-linux-amd64’: No such file or directory
Warning: Command failed: build/build_in_container.sh linux amd64
mv: cannot stat ‘api/cmd/portainer/portainer-linux-amd64’: No such file or directory
Use --force to continue.
Aborted due to warnings.
那是因为网络可达性问题，国内访问 golang.org 异常。
[root@dev_08 portainer]# host golang.org
golang.org is an alias for golang-consa.l.google.com.
golang-consa.l.google.com has address 216.239.37.1

导致这2个依赖下载失败：
golang.org/x/crypto/bcrypt
golang.org/x/net/websocket

解决方法：
[root@dev_08 portainer]# go get github.com/golang/crypto/tree/master/bcrypt
[root@dev_08 portainer]# go get github.com/golang/net/tree/master/websocket
[root@dev_08 portainer]# cd $GOPATH/src
[root@dev_08 src]# mkdir golang.org/x -p
[root@dev_08 src]# mv github.com/golang/* golang.org/x/

然后再切换到源码目录，调整构建脚本：
[root@dev_08 src]# cd /opt/portainer
[root@dev_08 portainer]# vim build/build_in_container.sh
挂载本地的 $GOPATH/src/golang.org 到容器路径：/go/src/golang.org
docker run --rm -tv $(pwd)/api:/src -e BUILD_GOOS="$1" -e BUILD_GOARCH="$2" portainer/golang-builder:cross-platform /src/cmd/portainer
调整为：
docker run --rm -tv $(pwd)/api:/src -v $GOPATH/src/golang.org:/go/src/golang.org -e BUILD_GOOS="$1" -e BUILD_GOARCH="$2" portainer/golang-builder:cross-platform /src/cmd/portainer

最后重新构建一次：
[root@dev_08 portainer]# grunt build
（略）
Cleaning "dist/js/angular.37dfac18.js"...OK
Cleaning "dist/js/portainer.cab56db9.js"...OK
Cleaning "dist/js/vendor.4edc9b0f.js"...OK
Cleaning "dist/css/portainer.e7f7fdaa.css"...OK
Done, without errors.

看到上述输出，表示符合预期。


6、运行（可以自动重启）
[root@dev_08 portainer]# grunt run-dev
访问 UI 地址： http://localhost:9000

7、不要忘记 lint 代码
[root@dev_08 portainer]# grunt lint

8、release（通常我们使用 linux-amd64 这个平台，具体过程请参考脚本 build.sh）
[root@dev_08 portainer]# grunt "release:linux:amd64"
(略)
Done, without errors.
[root@dev_08 portainer]# ls dist/
css  fonts  ico  images  index.html  js  portainer-linux-amd64
[root@dev_08 portainer]# mv dist/portainer-linux-amd64 dist/portainer

9、打包成镜像
[root@dev_08 portainer]# docker build -t 'opera443399/portainer:dev' -f build/linux/Dockerfile .

10、测试上述镜像
[root@dev_08 portainer]# mkdir -p /data/portainer_dev
[root@dev_08 portainer]# docker run -d -p 9001:9000 -v /var/run/docker.sock:/var/run/docker.sock -v /data/portainer_dev:/data --name portainer_dev opera443399/portainer:dev
[root@dev_08 portainer]# docker ps -l
CONTAINER ID        IMAGE                                   COMMAND             CREATED             STATUS              PORTS                    NAMES
cbd986df765b        opera443399/portainer:dev               "/portainer"        8 seconds ago       Up 7 seconds        0.0.0.0:9001->9000/tcp   portainer_dev
首次使用时将初始化一个管理员账户（本例使用 httpie 来提交）
[root@dev_08 portainer]# http POST :9001/api/users/admin/init Username="admin" Password="Develop"
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8
Date: Tue, 10 Oct 2017 08:18:19 GMT
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
访问页面：your_dev_ip:9001
验证功能：符合预期
清理：
[root@dev_08 portainer]# docker rm -f portainer_dev


三、开发需求示例
可结合 github 的搜索功能来查找关键字。
1、需求：在 'Container list' 页面，设定初始化时，默认不显示所有容器（即默认不勾选 'Show all containers' 这个复选框）
注1：从 1.14.1 版本开始使用 cookie 来记录是否显示所有的状态（Persist the status of the show all containers filter: #1198），其实完全可以不更改代码，去掉 checkbox 的选择后，下次登录还是 unchecked 的状态，本例仅作为修改代码的一个 howto 来展示。
注2：从 1.14.1 版本开始，新增了针对资源的限制（Add the ability to manage CPU/MEM limits & reservations for Swarm services: #516），不妨一试。
https://github.com/portainer/portainer/releases

为了达到我们的小目标，需要调整 filter_containerShowAll 在初始化时的默认值为 false 即可。
[root@dev_08 portainer]# diff -u /tmp/localStorage.js app/services/localStorage.js
--- /tmp/localStorage.js2017-09-26 15:11:41.062167776 +0800
+++ app/services/localStorage.js2017-09-26 15:21:11.604992708 +0800
@@ -50,7 +50,7 @@
     getFilterContainerShowAll: function() {
       var filter = localStorageService.cookie.get('filter_containerShowAll');
       if (filter === null) {
-        filter = true;
+        filter = false;
       }
       return filter;
     }

2、需求：在 'Service details' 页面的 'Tasks' 标签页中增加一个过滤器
当前操作列出了所有的 tasks
而我有时候只需要查看处于 running 状态的 tasks 即可，因而需要一个过滤器，改动代码如下：
[root@dev_08 portainer]# diff -u /tmp/tasks.html app/components/service/includes/tasks.html
--- /tmp/tasks.html2017-09-26 18:00:45.893169748 +0800
+++ app/components/service/includes/tasks.html2017-09-26 18:22:10.188208664 +0800
@@ -12,6 +12,11 @@
       </select>
       </div>
     </rd-widget-header>
+    <rd-widget-taskbar classes="col-lg-12">
+      <div class="pull-right">
+        <input type="text" id="filter" ng-model="state.filter" placeholder="Filter..." class="form-control input-sm" />
+      </div>
+    </rd-widget-taskbar>
     <rd-widget-body classes="no-padding">
       <table class="table">
       <thead>
@@ -48,7 +53,7 @@
         </tr>
       </thead>
       <tbody>
-        <tr dir-paginate="task in (filteredTasks = ( tasks | orderBy:sortType:sortReverse | itemsPerPage: state.pagination_count))">
+        <tr dir-paginate="task in (filteredTasks = ( tasks | filter:state.filter | orderBy:sortType:sortReverse | itemsPerPage: state.pagination_count))">
         <td><a ui-sref="task({ id: task.Id })" class="monospaced">{{ task.Id }}</a></td>
         <td><span class="label label-{{ task.Status.State|taskstatusbadge }}">{{ task.Status.State }}</span></td>
         <td ng-if="service.Mode !== 'global'">{{ task.Slot }}</td>

具体请参考：
https://github.com/portainer/portainer/pull/1242

3、需求：在 'Service details > Tasks > Task details' 页面增加一个 Container Console 按钮
当前操作要找到 service 下所有容器的 Console 并打开，则要执行下述步骤:
1 个 service 对应 N 个 tasks(containers) (运行在 M nodes 中)
    -> 打开 'Service Details' 页面，过滤处于 running 状态的 tasks 并注意对应的 node 名称  
    -> 选择 node N1 并切换到 endpoint N1
    -> 在 N1 的 'Container List' 页面上通过过滤器找到 container C1
    -> 在 'Container Details' 页面打开 Console

为了简化操作，实现咱们的小目标，改动代码如下：
    -> 在 'Service details > tasks' 页面，打开 'Task details' 页面时跳转到新的标签页
    -> 在 'Task details' 页面，新增 container console 按钮，新增一个提示框，提示后续步骤遇到错误时如何处理
    -> 点击 Console 按钮打开 'Container console' 页面时，跳转到新的标签页
            如果该 Container 不在当前 endpoint 中运行，则有一个错误通知：
                'Failure: Docker container identifier not found'
            此时，我们要做的就是一个 endpoint 切换的操作
    -> 当我们切换 endpoint 时，不是跳转页面到 dashboard 页面，而仅仅使用一个消息通知，然后等待页面刷新后，得到的页面即我们想要的。
    -> 如果我们切换到 swarm worker node 则后续需要一个切换回 swarm manager node 的操作
    -> 小结：用户体验有点糟糕，但能工作。


[root@dev_08 portainer]# diff -u /tmp/tasks.html app/components/service/includes/tasks.html
--- /tmp/tasks.html2017-10-12 11:55:23.247181711 +0800
+++ app/components/service/includes/tasks.html2017-10-12 10:12:52.653767466 +0800
@@ -54,7 +54,7 @@
       </thead>
       <tbody>
         <tr dir-paginate="task in (filteredTasks = ( tasks | filter:state.filter | orderBy:sortType:sortReverse | itemsPerPage: state.pagination_count))">
-        <td><a ui-sref="task({ id: task.Id })" class="monospaced">{{ task.Id }}</a></td>
+        <td><a ui-sref="task({ id: task.Id })" class="monospaced" target="_blank">{{ task.Id }}</a></td>
         <td><span class="label label-{{ task.Status.State|taskstatusbadge }}">{{ task.Status.State }}</span></td>
         <td ng-if="service.Mode !== 'global'">{{ task.Slot }}</td>
         <td>{{ task.NodeId | tasknodename: nodes }}</td>
         
[root@dev_08 portainer]# diff -u /tmp/task.html app/components/task/task.html
--- /tmp/task.html2017-10-11 14:22:29.782178036 +0800
+++ app/components/task/task.html2017-10-12 10:13:28.367767064 +0800
@@ -44,7 +44,12 @@
             </tr>
             <tr ng-if="task.Status.ContainerStatus.ContainerID">
               <td>Container ID</td>
-              <td>{{ task.Status.ContainerStatus.ContainerID }}</td>
+              <td title="Notify 'Failure: Docker container identifier not found' -> Try 'Switch endpoint to the node where the container is running'">
+                {{ task.Status.ContainerStatus.ContainerID }}
+                <a class="btn btn-outline-secondary" target="_blank" type="button" ui-sref="console({id: task.Status.ContainerStatus.ContainerID})">
+                  <i class="fa fa-terminal space-right" aria-hidden="true"></i>Console
+                </a>
+              </td>
             </tr>
           </tbody>
         </table>
         
[root@dev_08 portainer]# diff -u /tmp/sidebarController.js app/components/sidebar/sidebarController.js
--- /tmp/sidebarController.js2017-10-12 11:57:10.063180508 +0800
+++ app/components/sidebar/sidebarController.js2017-10-12 09:37:32.314244435 +0800
@@ -14,7 +14,7 @@
     EndpointProvider.setEndpointPublicURL(endpoint.PublicURL);
     StateManager.updateEndpointState(true)
     .then(function success() {
-      $state.go('dashboard');
+      Notifications.success('switch endpoint to: ', endpoint.Name);
     })
     .catch(function error(err) {
       Notifications.error('Failure', err, 'Unable to connect to the Docker endpoint');

具体请参考：
https://github.com/portainer/portainer/pull/1271

四、源码分析示例
1、在 UI 界面中是如何请求 docker api 来完成 container list 之类的请求的？
分析过程：
1）例如，在 Container list 页面，有如下请求：
/api/endpoints/1/docker/containers/json?all=0
列出了处于 running 状态的容器，我们去找找相关的代码。

2）找找 js 代码
[root@dev_08 portainer]# find ./app -type f -name '*.js' -exec grep -l 'docker\/containers' {} \;
./app/rest/docker/container.js
./app/rest/docker/containerLogs.js
[root@dev_08 portainer]#
[root@dev_08 portainer]# vim app/rest/docker/container.js
angular.module('portainer.rest')
.factory('Container', ['$resource', 'API_ENDPOINT_ENDPOINTS', 'EndpointProvider', function ContainerFactory($resource, API_ENDPOINT_ENDPOINTS, EndpointProvider) {
  'use strict';
  return $resource(API_ENDPOINT_ENDPOINTS + '/:endpointId/docker/containers/:id/:action', {
    name: '@name',
    endpointId: EndpointProvider.endpointID
  },
  
3）找找 go 代码
[root@dev_08 portainer]# find ./api -type f -name '*.go' -exec grep -l '\/api\/endpoints' {} \;
./api/http/handler/handler.go
[root@dev_08 portainer]#

[root@dev_08 portainer]# vim api/http/handler/handler.go
func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
        case strings.HasPrefix(r.URL.Path, "/api/endpoints"):                                   // 该请求的 URL 是 /api/endpoints 开头的
                if strings.Contains(r.URL.Path, "/docker") {                                    // 且URL 包含 /docker
                        http.StripPrefix("/api/endpoints", h.DockerHandler).ServeHTTP(w, r)     // 去掉 /api/endpoints 变成 /1/docker/containers/json?all=0  然后交给 DockerHandler 来处理
                        
[root@dev_08 portainer]# vim api/http/handler/docker.go
func (handler *DockerHandler) proxyRequestsToDockerAPI(w http.ResponseWriter, r *http.Request) {
        http.StripPrefix("/"+id+"/docker", proxy).ServeHTTP(w, r)                               // 去掉 /1/docker 变成 /containers/json?all=0  （这就是最终请求 docker api 的路径）
        
通过上述代理行为，最终变成请求类似这样的 docker api （具体的请求是走的本地 socket 还是 tcp 的行为尚未分析）
curl -s \
    --unix-socket /var/run/docker.sock \
    http:/containers/json?all=0
或者：
curl -s \
    http://endpoint_ip:port/containers/json?all=0

   
五、FAQ
1、为何不能统一管理 swarm mode 集群下的资源？
状态：
我理解，这个UI的开发理念是一个简单通用的docker UI
目前的方式是：每个 node 都是一个 endpoint，要切换 endpoint 来执行 docker API 指令获取该 node 上的容器等信息。
未来计划增加 swarm mode 集群管理的功能。
具体的讨论，还请跟踪下这个 issue 相关的内容：
[FEATURE REQUEST] Be able to use all the Portainer built-in functionalities in all the containers running in a swarm cluster #461
https://github.com/portainer/portainer/issues/461

2、如何提交 github PR 来为本项目共享代码？
请先阅读：https://github.com/portainer/portainer/blob/develop/CONTRIBUTING.md
贡献代码的指引
1）通用
先看看有没有相关的 PR/issues 已经存在，如果没有则进入下一步
打开一个 issue 讨论你要带来的一些变化（也可以在已经存在 的 issue 上讨论），包括功能合理性和技术可行性等方面，在解决方案上讨论出一个解决，一致同意后，再去开发【这一步很重要，不能跨过】
在一个特定主题的分支上开发，不要在 master/develop 分支开发！
新建分支时，有一些命名规则，例如：
(type)(issue number)-text-desc
举例：
你在提交一个 bugfix 来解决 issue #361 则分支可以命名为： fix361-template-selection.
参考这里的讨论：
https://github.com/portainer/portainer/issues/1271#issuecomment-336033282
2）为已经打开的 issues 贡献代码
想做却不知道如何开始？
有一些 issues 的标签是 exp/ 开头的，意味着可以供大家去开发，但有难度的区分：
beginner: 针对不太熟系该项目代码的开发者
intermediate: 针对该项目代码有一定理解，或对 AngularJS or Golang 有使用经验的开发者
advanced: 针对该项目代码有深入理解的开发者
可以使用 Github filters 来过滤出 issues:
beginner labeled issues: https://github.com/portainer/portainer/labels/exp%2Fbeginner
intermediate labeled issues: https://github.com/portainer/portainer/labels/exp%2Fintermediate
advanced labeled issues: https://github.com/portainer/portainer/labels/exp%2Fadvanced
3）代码 Linting
检查代码使用 grunt lint 然后再提交 PR

4）提交的信息格式
<type>(<scope>): <subject>
不要超过 100 字符，整洁的 commit log 示例：
#271 feat(containers): add exposed ports in the containers view
#270 fix(templates): fix a display issue in the templates view
#269 style(dashboard): update dashboard with new layout

有如下几类 type
feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor: A code change that neither fixes a bug or adds a feature
test: Adding missing tests
chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
Scope
关于 scope ：表示
提交的代码是改动了哪一块的内容，例如：networks, containers, images 可以使用 area 标签来关联 issue (例如：标签 area/containers 使用 containers 作为a scope)
关于 subject ：表示
简明的描述本次提交做了那些改变
使用祈使句和现在时： "change" not "changed" nor "changes"
不要大些第一个字母
语句最后不要使用点 (.)
   
ZYXW、参考
1、doc
https://portainer.readthedocs.io/en/latest/contribute.html
2、国内下载golang.org的包有什么好办法么？
https://gocn.io/question/362
3、github
https://github.com/portainer/portainer/issues/461
https://github.com/portainer/portainer/pull/1242
https://github.com/portainer/portainer/issues/1271#issuecomment-336033282