install/v3/install-github.md
Kuboard 支持多种认证方式：
本文描述了如何配置 Kuboard v3 使其与 github.com / github ee 实现单点登录。
在正式安装 kuboard v3 之前，需做好一个简单的部署计划的设计，在本例中，各组件之间的连接方式，如下图所示：
http://外网IP:80 访问 Kuboard v3；内网IP:80 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。本例子中，假设：
在 github.com （或者 github ee）中导航到 Settings / Developer settings 菜单，如下图所示：
在 Settings / Developer settings 菜单中导航到 OAuth Apps 菜单，如下图所示：
在上图中点击 New OAuth App，并填写如下表单：
| 字段名称 | 字段取值 | 字段描述 |
|---|---|---|
| Application name | kuboard-v3 | 标识用，填写任意名称即可 |
| Homepage URL | http://外网IP:80 | 根据 部署计划，此处应该填写 http://外网IP:80 |
| Application description | Kuboard v3.x | 描述，可以为空 |
| Authorization callback URL | http://外网IP:80/sso/callback | 根据 部署计划，此处应该填写 http://外网IP:80/sso/callback，`/sso/callback` 为 Kuboard 中处理 OAuth 回调的 URL 路径 |
在上图中点击 Register application 按钮之后，将进入新创建的 OAuth application 的详情页面，在该页面可以获得 Client ID 和 Client Secret 两个字段，如下图所示：
使用如下命令启动 Kuboard v3：
sudo docker run -d \
--restart=unless-stopped \
--name=kuboard \
-p 80:80/tcp \
-p 10081:10081/tcp \
-v /root/kuboard-data:/data \
-e KUBOARD_LOGIN_TYPE="github" \
-e KUBOARD_ENDPOINT="http://内网IP:80" \
-e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
-e KUBOARD_ROOT_USER="shaohq" \
-e GITHUB_CLIENT_ID="17577d45e4de7dad88e0" \
-e GITHUB_CLIENT_SECRET="ff738553a8c7e9ad39569c8d02c1d85ec19115a7" \
-e SSO_REDIRECT_URI="http://外网IP:80/sso/callback" \
eipwork/kuboard:v3
# 也可以使用镜像 swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3 ，可以更快地完成镜像下载。
# 请不要使用 127.0.0.1 或者 localhost 作为内网 IP \
# Kuboard 不需要和 K8S 在同一个网段，Kuboard Agent 甚至可以通过代理访问 Kuboard Server \
::: danger
kuboard-agent 知道如何访问 Kuboard Server；/etc/hosts 文件，将不能正常运行；
:::::: tip 参数说明
start-kuboard.sh，后续升级 Kuboard 或恢复 Kuboard 时，需要通过此命令了解到最初安装 Kuboard 时所使用的参数；80 端口，如安装指令的第三行所示，默认映射到了宿主机的 80 端口，您可以根据自己的情况选择宿主机的其他端口；10081 端口 TCP，默认映射到了宿主机的 10081 端口，您可以根据自己的情况选择宿主机的其他端口；/data 目录，默认映射到了宿主机的 /root/kuboard-data 路径，请根据您自己的情况进行调整；KUBOARD_LOGIN_TYPE 为 github （适用于 github.com / github-ee）；KUBOARD_ENDPOINT 环境变量为访问 Kuboard 界面的 URL；（如 部署计划 中所描述，本例子中，使用 http://内网IP:80 作为通过执行此命令启动的 Kuboard 的访问 URL）；此参数不能以 / 结尾；10081，此参数与第 5、6 行中的宿主机端口应保持一致，修改此参数不会改变容器内监听的端口 10081，例如，如果第 5 行为 -p 30081:10081/tcp 则第 9 行应该修改为 -e KUBOARD_AGENT_SERVER_TCP_PORT="30081"；KUBOARD_ROOT_USER，使用该 GitHub 用户登录到 Kuboard 以后，该用户具备 Kuboard 的所有权限；GITHUB_CLIENT_ID，该参数来自于 准备 GitHub 步骤中创建的 GitHub OAuth Application 的 Client ID 字段GITHUB_CLIENT_SECRET，该参数来自于 准备 GitHub 步骤中创建的 GitHub OAuth Application 的 Client Secret 字段SSO_REDIRECT_URI，该参数用于从 github 回调到 Kuboard
:::::: tip GitHub EE 上面的命令行可以用于和 github.com 集成，如果您使用 GitHub Enterprise，需要在命令行中增加如下两个参数：
GITHUB_HOSTNAME，GitHub Enterprise 的 hostname，如
-e GITHUB_HOSTNAME="github.this-is-a-sample.com"
GITHUB_ROOT_CA，如果您的 GitHub Enterprise 使用了自签名证书，则需要指定 GITHUB_ROOT_CA，否则，可以忽略此参数，如：
-v /path/to/your/rootca.crt:/github-root-ca.crt
-e GITHUB_ROOT_CA="/github-root-ca.crt"
:::
在浏览器中输入 http://外网IP:80，您将被重定向到 GitHub 登录界面；
在 GitHub 登录界面使用 docker run 命令中 KUBOARD_ROOT_USER 参数指定的用户完成登录后，GitHub 将提示您是否授权访问 Kuboard，如下图所示：
点击上图中的 Authorize 按钮后，您将成功登录 Kuboard 界面。
::: tip 浏览器兼容性
<li>请使用 Chrome / FireFox / Safari 等浏览器</li> <li>不兼容 IE 以及以 IE 为内核的浏览器</li>:::
默认情况下，只有 KUBOARD_ROOT_USER 参数指定的用户可以执行 Kuboard 中的所有操作，其他用户通过单点登录进入 Kuboard 系统后，除了退出系统，几乎什么事情也做不了。为了让单点登录的用户获得合适的权限，您需要在 Kuboard 中为对应的用户/用户组授权。请参考 为单点登录的用户/用户组授权