Skip to content
使用 Docker 构建的 GitBook 服务器
Dockerfile
Branch: master
Clone or download
Latest commit 5e42e13 Dec 23, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
gitbook
img
.gitignore
Dockerfile
LICENSE
README.md

README.md

GitBook-Server-Docker

使用 Docker 构建的 GitBook 服务器


简介

使用 GitBook 的初衷主要是为了可以利用 Github 为数据载体,在线上和线下同时搭建个人博客。

但是在线下搭建 GitBook 服务器最大的问题是环境部署复杂,因此本文利用 Docker 实现一键部署服务器。

在线上部署的方法则比较多:
 利用 GitBook 官方提供的免费空间
 利用 GitHub Pages (有 300M 免费空间)
 租用个人云服务器,同样可以用 Docker 搭建


运行环境

 

注:
 因为 gitbook 服务是运行在 Docker 中,所以不论使用哪个平台,都要预装好 Docker 环境
 但是本文所使用的基础镜像是基于 Linux 的,因此 Docker in Windows 是无法直接安装的
 所以针对 Windows 10 ,推荐使用 WSL ( Windows Subsystem for Linux )
 通过 WSL 安装 Ubuntu 系统,然后再在 Ubuntu 里面安装 Docker Deamon
 最后 Docker in Windows 做端口映射,就可以实现 Windows 到 Linux 的无缝对接
 具体的 Windows Docker 环境部署方法可参考 《简书: Win10 内置 Ubuntu 完美使用 Docker in Windows
 至于 Linux 和 Mac 则简单得多,直接安装 Docker Deamon 即可使用,具体方法自行谷歌

展开查看图片


使用方法

构建 GitBook 镜像

首先安装 git 命令行工具,然后 clone 本仓库到本地:

git clone https://github.com/lyy289065406/gitbook-server-docker

在命令行环境下 打开本地仓库目录 。 Docker 脚本已经编排好在 ./Dockerfile 中,可以不修改直接使用。

构建 Docker 镜像(镜像名称 exp/gitbook-server 可根据 Docker 规范自定义修改):

docker build . -t exp/gitbook-server:latest

至此镜像已经安装完毕,下文主要是测试 GitBook 镜像是否可用。

初始化 GitBook 项目

在 Docker 镜像中执行命令 gitbook init

docker run --rm -v "$PWD/gitbook:/gitbook" exp/gitbook-server gitbook init

 该命令会自动创建用于 示例 的 GitBook 文件 。
 实际效果就是在工作目录 ./gitbook 下创建两个符合 GitBook 语法的文件 README.mdSUMMARY.md
 更多的 GitBook 语法详见 《GitBook 学习笔记

构建 GitBook 项目

在 Docker 镜像中执行命令 gitbook build

docker run --rm -v "$PWD/gitbook:/gitbook" exp/gitbook-server gitbook build

 该命令会根据 GitBook 文件 README.mdSUMMARY.md 构建 html 项目 。
 实际效果就是在工作目录 ./gitbook 下构建目录名为 _book 的静态网页文件 。
 本地可以通过 ./gitbook/_book/index.html 测试访问 。

启动 GitBook 服务

在 Docker 镜像中执行命令 gitbook serve

docker run --rm -v "$PWD/gitbook:/gitbook" -p 4000:4000 exp/gitbook-server gitbook serve

该命令效果就是构建一个可以访问 ./gitbook/_book/index.html 的 Web 服务。


FAQ

0x01 前文中 Docker 命令的参数是什么含义?

docker run --rm -v "$PWD/gitbook:/gitbook" -p 4000:4000 exp/gitbook-server <Command>

  • docker run:运行镜像
  • --rm:退出镜像后自动删除运行时产生的数据(此镜像目的是提供 GitBook 服务的运行环境,因此没必要保留数据)
  • -v "$PWD/gitbook:/gitbook":把本地工作目录 $PWD/gitbook 挂载到镜像的工作目录 /gitbook (这样运行 GitBook 期间的工作数据就会从本地映射到镜像内,即使镜像退出运行,数据依旧会保留在本地)
  • -p 4000:4000:把镜像内 GitBook 的 4000 服务端口暴露到本地物理机的 4000 端口
  • exp/gitbook-server:目标镜像名称
  • <Command>:要在镜像内执行的命令,如 gitbook serve 等,更多命令可见 gitbook-cli

0x02 怎样以后台运行方式启动 GitBook 服务?

增加 -d 参数即可:

docker run -d --rm -v "$PWD/gitbook:/gitbook" -p 4000:4000 exp/gitbook-server gitbook serve

0x04 怎样停止 GitBook 服务?

先用 docker ps 命令查看正在运行的 GitBook 容器,然后执行命令 docker stop <CONTAINER ID> 即可 。

0x05 怎样进入这个 Docker 镜像?

执行下面命令即可:

docker run --rm -v "$PWD/gitbook:/gitbook" -it exp/gitbook-server /bin/sh

  • -it:表示以交互方式运行
  • /bin/sh:此镜像的基础镜像是 node:8.5-alpine ,shell 只支持 /bin/sh

0x06 怎样安装 GitBook 插件?

GitBook 的精粹在于丰富的插件以扩展其功能,插件可通过工作目录下的 book.json 配置并控制,相关说明见 官方文档

推荐 GitBook 安装的插件可参考 这份清单

根据插件命名约定,若 插件名称prism ,则其对应 安装包名称gitbook-plugin-prism

prism 插件为例,安装方式有两种:

  • 通过 GitBook 安装:把插件名称 prism 添加到 book.jsonplugins 列表,执行 gitbook install 命令
  • 通过 nodejs 安装:执行 npm install gitbook-plugin-prism 命令安装指定插件,然后把插件名称 prism 配置到 book.jsonplugins 列表使其生效

 方法一每次执行都会检查现有插件是否需要更新。
 方法二只有特定插件受影响,适合于存在自定义修改过插件代码的情况。

注意, Guthub Pages 不支持使用了 Octopress 框架的插件,详见 《About GitHub Pages and Jekyll》 。

若使用了这类插件,Guthub Pages 是无法发布成功的。 判定是不是使用了这类插件的方法也很简单:

  • 提交变更内容后,点击 Github 仓库下的 branch 查看 master 分支
  • master 分支会提示最近提交内容的 Guthub Pages 构建情况
  • 若构建失败,可以点击 Details 查看详情
  • 假如提示 is not a recognised Liquid tag 说明就是采用了 Octopress 框架的插件

0x06 怎样开发 GitBook 自定义插件?

参考这里

展开查看更多

0x08 怎样共享这个 Docker 镜像?

先执行 docker login 命令登陆,然后提交到个人的 Docker Hub 仓库:

docker push exp/gitbook-server:latest

若提示 denied: requested access to the resource is denied 提交失败,是因为镜像 tag 名称 / 前面部分的空间名不是个人的用户名,先修改 tag 名称即可(例如我的用户名是 expm02 ):

docker tag fdc060ba7253 expm02/gitbook-server:latest

0x09 怎样获取共享的 Docker 镜像?

直接执行以下命令即可(这样就不用执行前文的安装步骤了):

docker pull expm02/gitbook-server:latest


版权声明

 Copyright (C) 2016-2020 By EXP License: GPL v3


You can’t perform that action at this time.