Merge pull request #3 from muxiyun/dev-andrew

update docs and turn some parameters into configurable

README.md

@@ -1,25 +1,67 @@
 # [muxi application engine(Mae)](https://github.com/muxiyun/Mae/tree/master)
 
+```
+                 _      _      _
+              __(.)< __(.)> __(.)=
+              \___)  \___)  \___)
+                     _      _      _
+                  __(.)< __(.)> __(.)=
+                  \___)  \___)  \___)
+                 _      _      _
+              __(.)< __(.)> __(.)=
+              \___)  \___)  \___)
+                     _      _      _
+                  __(.)< __(.)> __(.)=
+                  \___)  \___)  \___)
+
+```
+
 PaaS of Muxi-Studio. An easier way to manage Kubernetes cluser.
 
 Click [http://zxc0328.github.io/2017/05/27/mae/](http://zxc0328.github.io/2017/05/27/mae/) to view details.
 
 
-TODO:
-- [x] api design
-- [x] domain UML & database UML
-- [x] user system
-- [x] casbin access control
-- [x] application (abstract entity)
-- [x] service (abstract entity)
-- [x] version (abstract entity)
-- [x] log query
-- [x] web terminal
-- [x] email notification for admin
-NEXT:
+## Feature:
+- [x] fast and sliding version switch and management
+- [x] application management for microservices
+- [x] casbin access control(RBAC with domains/tenants)
+- [x] log query of sepcific container
+- [x] web terminal of specific container
+- [x] email confirm and email notification
+
+## Build
+Clone the source code and cd to the root dir of this project and execute the command below to install the dependencies.
+``` bash
+$ glide install
+```
+Users of mainland China may encounter some problem here. This project uses some dependencies that are blocked by the GWF. So you have to do terminal proxy configuration. How to config it? You can refer to this article:[https://andrewpqc.github.io/2018/04/30/let-the-terminal-penetrate-the-firewall.](https://andrewpqc.github.io/2018/04/30/let-the-terminal-penetrate-the-firewall)
+you can also refer to [`glide mirror`](https://glide.readthedocs.io/en/latest/commands/#glide-mirror) to resove the problem.
+
+Before you run Mae, you firstly have to config it. How to config? 
+
+Firstly, you have to get the admin's kubeconfig file, and make sure the name of this file is `admin.kubeconfig`(if not so, you may have to rename it). Then put the `admin.kubeconfig` file in the `conf` folder of this project. the `admin.kubeconfig` is the link between this program and the kubernets cluster. So it's really important.
+
+Secondly, You have to edit `conf/config.yaml` to config the mysql database connection information, the listen address and other configurable options. There are a lot of annotations in the config file, so you can view that to know more.
+
+After you have finished the config part, you can build and run it by typing the following command in you shell.
+``` bash
+$ go build && ./Mae
+```
+Then, you can check `/api/v1.0/sd/health` to see whether it work properly or not.
+
+## Test
+After you have finished the config part, you can just to use the following command to run the whole test.
+``` bash
+$ go test -v -cover=true
+```
+But we don't suggest you to do so. In order to prevent the rapid consumption of cluster resources and the interaction between test cases, we recommend that you run the test cases one by one in you integrated development environment(suggest [Goland](https://www.jetbrains.com/go/)).
 
-1.现在版本的切换采取的是删除原版本的资源之后创建新版本的资源，后面改为灰度发布
+## Next:
 
-2.优化int类型的使用，重构部分代码
+1. Grayscale release
+2. Optimize the use of int types
+3. Optimize the organization of the code
+4. Further improve the documentation
 
-3.文档
+## Thanks
+Thanks for developers of kubernetes,client-go,iris and mysql.

conf/config.yaml

@@ -3,9 +3,10 @@ addr: :8080                  # HTTP绑定端口
 name: mae_apiserver              # API Server的名字
 url: http://127.0.0.1:8080   # pingServer函数请求的API服务器的ip:port
 max_ping_count: 10           # pingServer函数try的次数
-jwt_secret: Rtg8BPKNEf2mB4mgvKONGPZZQSaJWNLijxR42qRgq0iBb5
+jwt_secret: Rtg8BPKNEf2mB4mgvKONGPZZQSaJWNLijxR42qRgq0iBb5  #46字符的随机字符串
 casbinmodel: conf/casbinmodel.conf
 kubeconfig: conf/admin.kubeconfig
+tokenEffectiveTime: 60  #token默认有效期时长，默认60分钟,请求时可以传参改变改值
 tls:
   addr: :8081
   cert: conf/example.com+4.pem
@@ -20,7 +21,27 @@ log:
   log_rotate_size: 1
   log_backup_count: 7
 db:
+  #数据库名，跑之前提前建好
   name: mae
+  #数据库地址
   addr: 127.0.0.1:3306
+  #用户名
   username: root
+  #密码
   password: pqc19960320
+
+mail:
+  #邮件服务器地址
+  host: smtp.qq.com
+  #邮件服务端口
+  port: 25
+  username: 3480437308@qq.com　
+  senderNickName: Mae notification robot　
+  password: iifwjwzfjxvxchig
+  #与邮件服务器连接的最大时长，默认30秒，即30秒之内没有需要发送的邮件则断开与邮件服务器的连接
+  maxFreeTime: 30
+  #邮件通道缓冲区大小，默认20
+  chanCache: 20
+  #认证邮件中的链接的有效期时长,默认30分钟之后认证邮件过期
+  confirmTime: 30
+

doc/apidoc.markdown.md

@@ -1,16 +1,25 @@
 ## Mae维护文档
 
 ### 关于用户认证
-1.Mae认证采取Basic认证的方式
+Mae认证采取Basic Auth认证的方式,首先携带 `Authorization:base64.encode(username:password)`请求头到/api/v1.0/token取到token。之后需要登录的操作携带` Authorization:base64.encode(token:)`请求头即可以。
+
+用户注册要求提供的邮箱真实有效，注册完毕之后，系统会发送一封邮件验证邮箱是否真实。验证的handler还会赋予该用户对应的权限(user/admin)。就是说，如果用户没有点击验证邮件中的链接，该用户的绝大部分操作都会被Forbidden.
 
 ### 关于权限管理
+Mae采用casbin的RBAC with domains/tenants 的访问控制模型。系统中所有的操作被分为三类:`roleAdmin`,`roleUser`,`roleAnonymous`。这三种类型也被称为三种角色(role)或者三个组(group).
+一个操作是这样定义的`username,`
+
 
 ### 关于错误码管理
 
 ### 创建Version注意事项
 
 ### 关于app,service的删除
+系统中实体之间的逻辑关系大致是这样的。系统中可以创建多个app(应用)，一个应用之下有一个或多个service(服务)，一个服务则有一个或者多个version(版本)。每一个版本其实就是一个在数据库中的用来在集群中创建deployment和service的配置文件的记录(序列化之后存成一个字段)。每一个版本有两个状态activa和unactive，active表明当前版本在集群中对应有资源，unactive则表明当前版本在集群中不存在资源。同时灭一个service也会有一个字段用来记录当前service对应的active版本是哪一个(一般来讲，一个service只有一个版本是active的)。
 
+由于app,service,version这些抽象实体之间是一种树状的结构，所以在删除时采取的是级联删除的方式
 ### 关于邮件通知系统
+当系统中发生向删除app,service对象这样的操作时，会发送邮件通知所有的管理员用户
 
 ### 关于namespace,deployment name,service naem的名称问题
+namespace,deloyment name,service name这些对象的命名必须采取与Kubernetes对象的命名相同的规则