搭建gitlab服务器（使用私有gitlab搭建gitbook持续集成）

在项目实践中，团队需要对用到的知识技术进行总结，即便于分享，也利于传承，而gitbook就是个不错的选择，使用gitbook-cli 对Markdown文档进行编译，生成静态文件，再通过web服务器（e.g. nginx）对外提供服务。gitbook和gitlab搭建持续集成，可实现文档的即时更新，这也是我在DevOps实践的一部分。https://www.gitbook.comhttps://github.com/GitbookIO/gitbook环境搭建#1. 安装 Node.js#gitbook 是一个基于 Node.js 的命令行工具，下载安装 Node.js，安装完成之后，你可以使用下面的命令来检验是否安装成功。$ node -v2. 安装 gitbook#输入下面的命令来安装 gitbooknpm install gitbook-cli -g安装完成之后，你可以使用下面的命令来检验是否安装成功$ gitbook -V更多详情请参照 gitbook 安装文档 来安装 gitbook3. 安装 Gitlab Runner#下载二进制包sudo curl -L –output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64添加执行权限sudo chmod +x /usr/local/bin/gitlab-runner(可选)如果使用Docker，安装Dockercurl -sSL https://get.docker.com/ | sh创建 GitLab CI 用户sudo useradd –comment 'GitLab Runner' –create-home gitlab-runner –shell /bin/bash以Service方式安装sudo gitlab-runner install –user=gitlab-runner –working-directory=/home/gitlab-runner
sudo gitlab-runner start
4. 注册Runner#Runner安装Runner注册运行以下命令sudo gitlab-runner register输入GitLab 实例 URL Please enter the gitlab-ci coordinator URL输入Gitlab注册的token (Gitlab admin权限才能看见)Please enter the gitlab-ci token for this runner xxx输入Runner描述，后面可在Gitlab UI上更新Please enter the gitlab-ci description for this runner输入Runner Tag，后面可在Gitlab UI上更新Please enter the gitlab-ci tags for this runner (comma separated):选择Runner executorPlease enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: shellgitbook 配置#1. 目录结构# .
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
| ├── README.md
| └── something.md
└── chapter-2/
├── README.md
└── something.md
README.mdgitbook第一页内容是从文件 README.md 中提取的。如果这个文件名没有出现在 SUMMARY 中，那么它会被添加为章节的第一个条目book.json该文件主要用来存放配置信息.bookignore将读取.gitignore，.bookignore以及.ignore文件以获得文件和文件夹跳过列表Glossary.md允许指定要显示为注释的术语及其各自的定义。根据这些条款，GitBook将自动构建一个索引并突出显示这些术语SUMMARY.md用于存放GitBook的文件目录信息，左侧的目录就是根据这个文件来生成的，默认对应的文件是 SUMMARY.md，可以在 book.json 重新定义该文件的对应值。它通过Markdown中的列表语法来表示文件的父子关系注意 不被SUMMARY.md包含的文件不会被gitbook处理SUMMARY.md示例：# Summary * [Introduction](README.md) * [Part I](part1/README.md) * [Writing is nice](part1/writing.md) * [gitbook is nice](part1/gitbook.md) * [Part II](part2/README.md) * [We love feedback](part2/feedback_please.md) * [Better tools for authors](part2/better_tools.md) 通过使用 标题 或者 水平分割线 将 gitbook 分为几个不同的部分，如下所示：# Summary ### Part I * [Introduction](README.md) * [Writing is nice](part1/writing.md) * [gitbook is nice](part1/gitbook.md) ### Part II * [We love feedback](part2/feedback_please.md) * [Better tools for authors](part2/better_tools.md) — * [Last part without title](part3/title.md) 目录中的章节可以使用锚点指向文件的特定部分# Summary ### Part I * [Part I](part1/README.md) * [Writing is nice](part1/README.md#writing) * [gitbook is nice](part1/README.md#gitbook) * [Part II](part2/README.md) * [We love feedback](part2/README.md#feedback) * [Better tools for authors](part2/README.md#tools)2. 命令行#gitbook initgitbook项目初始化,会自动生成两个必要的文件 README.md 和 SUMMARY.mdgitbook build [path]构建gitbook项目生成静态网页，会生成一个 _book 文件夹（包含了 .md 对应的.html文件）gitbook serve该命令实际上会首先调用 gitbook build 编译 .md，完成以后会打开一个WEB服务器，监听在本地的4000端口。生产的静态文件可单独放到tomcat或者nginx供静态访问./ ├── _book │ ├── gitbook │ │ ├── fonts │ │ ├── gitbook.js │ │ ├── gitbook-plugin-fontsettings │ │ ├── gitbook-plugin-highlight │ │ ├── gitbook-plugin-livereload │ │ ├── gitbook-plugin-lunr │ │ ├── gitbook-plugin-search │ │ ├── gitbook-plugin-sharing │ │ ├── images │ ├── index.html │ └── search_index.json ├── README.md └── SUMMARY.mdgitbook update #更新gitbook到最新版本gitbook install #安装依赖gitbook builid –debug #输出错误信息gitbook build –log=debug #指定log级别3. 插件#gitbook 提供了丰富插件，默认带有 5 个插件，highlight、search、sharing、font-settings、livereload，如果要去除自带的插件， 可以在插件名称前面加 -，比如： "plugins": [
"-search"
]
插件使用参考https://gitbook.zhangjikai.com/plugins.htmlgitlab 与gitbook集成#.gitlab-ci.yml 示例：# requiring the environment of NodeJS 10
image: node:10

# add 'node_modules' to cache for speeding up builds
cache:
paths:
– node_modules/ # Node modules and dependencies

before_script:
– npm install gitbook-cli -g # install gitbook
– gitbook fetch 3.2.3 # fetch final stable version
– gitbook install # add any requested plugins in book.json

test:
stage: test
script:
– gitbook build . public # build to public path
only:
– branches # this job will affect every branch except 'master'
except:
– master

# the 'pages' job will deploy and build your site to the 'public' path
pages:
stage: deploy
script:
– gitbook build . public # build to public path
artifacts:
paths:
– public
expire_in: 1 week
only:
– master # this job will affect only the 'master' branch