使用docker镜像搭建docusaurus markdown静态网站

什么是Docusaurus

我想引用官方网站上的话。

Docusaurus使维护开源文档网站变得简单。

这个项目提供了什么

我希望这个项目对那些使用Docker来构建他们的服务器的人有用。

特点

核心软件包

我选择了Alpine Linux来构建一个轻量级的服务。
为了进行一些Node.js版本的调整，我选择了node-alpine作为其基础镜像。

因此，这由以下组成，

  • Alpine Linux 3.17

  • Node.js 20.2.0

包括，

  • 最新的Docusaurus 2 beta版本，带有自动更新功能

Docusaurus 2

这个镜像运行的是Docusaurus 2 beta版本，而不是稳定的Docusaurus 1版本。Docusaurus 2目前正在积极开发中，所以我希望它会在不久的将来发布。

我看到当用户将他们的Docusarus 1升级到新的Docusaurus 2时，需要进行一些迁移工作。因此，此刻对于那些准备开始构建自己的网站的人来说，使用Docusaurus 2是合理的。

但是，正式地说，由于这尚处于测试版本，我在此镜像中添加了一个自动更新触发器。这可以通过设置环境变量AUTO_UPDATE=false来禁用。默认情况下，此功能是启用的。

保持备份你的文档

强烈建议始终备份您的文档。出于各种原因，比如意外物理损坏硬盘或在开发和/或维护过程中软件损坏，您必须将数据备份到其他安全位置。

支持多种架构

它通过Github Actions进行构建，以支持多种架构，如AMD64(x86_64)和ARM64、ARMv7、ARMv6。

因此，您可以在支持Docker的大多数计算机上使用此镜像。

我该如何使用这个镜像

从Docker Hub上拉取镜像。

sudo docker pull awesometic/docusaurus

基本用法

您可以使用以下命令进行干运行。'--rm'选项会在交互会话终止时删除容器。

sudo docker run -it --rm -p 8080:80  -v /config/dir:/docusaurus awesometic/docusaurus

此Docker镜像在主机计算机上需要一个映射的卷。

  • /docusaurus：Docusaurus源文件所在的位置

在第一次运行时，从互联网下载/准备整个源代码可能需要几分钟。请参阅下面的我什么时候可以访问我的网站章节。

然后，您就可以创建一个具有以下特征的基本Docusaurus网站。

  • 项目源使用UID 1000和GID 1000进行非根编辑

  • 启用自动更新

  • 名称为“ MyWebsite”

  • 使用“经典”模板进行样式设置

如果您想使用您的参数将此镜像作为守护程序运行，请尝试使用以下命令。

sudo docker run -d --name=interview -p 8080:8080 -v /config/dir:/docusaurus -e TARGET_UID=1000 -e TARGET_GID=1000 -e AUTO_UPDATE=true -e WEBSITE_NAME="interview.nfvschool.cn" -e TEMPLATE=classic awesometic/docusaurus

容器运行后，让您的浏览器浏览以下网址：

http://localhost/

生产模式

此镜像默认以开发模式运行，以便在编辑文档后可以立即看到更改。

但是，您可以通过在创建容器时添加RUN_MODE环境变量来启动此镜像的生产模式。请参见下面的命令。

sudo docker run -d --name=docusaurus \
-p 80:80 \
-v /config/dir:/docusaurus \
-e TARGET_UID=1000 \
-e TARGET_GID=1000 \
-e AUTO_UPDATE=true \
-e WEBSITE_NAME="awesometic-docs" \
-e TEMPLATE=classic \
-e RUN_MODE=production \
awesometic/docusaurus

然后，日志将显示如下。

/* 将以生产模式运行此Node服务... */
/* 构建当前源代码... */
yarn run v1.22.15
$ docusaurus serve --build --port 80 --host 0.0.0.0
2021-10-21 07:18:25,121 INFO success: docusaurus entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

[en] Creating an optimized production build...
ℹ Compiling Client
ℹ Compiling Server
✔ Client: Compiled successfully in 12.17s
✔ Server: Compiled successfully in 14.75s
Success! Generated static files in "build".

Use `npm run serve` command to test your build locally.


   ┌────────────────────────────────────────────────────────┐
   │                                                        │
   │   Serving "build" directory at "http://0.0.0.0:80/".   │
   │                                                        │
   └────────────────────────────────────────────────────────┘

如果构建顺利完成，您可以在您选择的用于Docusaurus服务的网站源文件目录下找到build目录。

内置的Web服务器提供构建的Web源文件，但您也可以从其他Web服务器（如Nginx或Apache）提供服务。

每当您输入docker restart [container-id]命令时，构建的文件将更新为具有最新内容的文件。

我什么时候可以访问我的网站

在第一次运行中，换句话说，如果在首次运行时没有创建配置文件，那么用户将无法立即访问新创建的Docusaurus网站。这将需要超过1分钟，因为它在初始化过程中从互联网下载了最新的Docusaurus源代码。

查看Docusaurus容器运行时显示的日志。

Variables:
        - UID=1000
        - GID=1000
        - AUTO_UPDATE=true
        - WEBSITE_NAME=awesometic-docs
        - TEMPLATE=classic
        - RUN_MODE=development
/* Register a new cron job for auto updating... */
/* Successfully registered. */
/* Install docusaurus... */
npm WARN exec The following package was not found and will be installed: @docusaurus/init@latest

Creating new Docusaurus project ...
...
[4/4] Building fresh packages...
...
Success! Created awesometic-docs
...
/* Node modules already exist in /docusaurus/awesometic-docs/node_modules */
/* Start supervisord to start Docusaurus... */
2021-02-22 03:14:43,572 INFO Set uid to user 0 succeeded
2021-02-22 03:14:43,584 INFO supervisord started with pid 95
2021-02-22 03:14:44,589 INFO spawned: 'docusaurus' with pid 97
yarn run v1.22.5
$ docusaurus start --port 80 --host 0.0.0.0
2021-02-22 03:14:46,406 INFO success: docusaurus entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
Starting the development server...
Docusaurus website is running at: http://localhost:80/
ℹ Compiling Client
ℹ ｢wds｣: Project is running at http://0.0.0.0:80/
ℹ ｢wds｣: webpack output is served from /
ℹ ｢wds｣: Content not from webpack is served from /docusaurus/awesometic-docs
ℹ ｢wds｣: 404s will fallback to /index.html
✔ Client: Compiled successfully in 27.42s
ℹ Compiling Client
✔ Client: Compiled successfully in 507.94ms

如上所述，我们可以看到日志，在初始化过程中，它从互联网下载了完整的源代码。然后它构建源代码，最后它以指定的端口号启动。此时的日志为，

$ docusaurus start --port 80 --host 0.0.0.0
2021-02-22 03:14:46,406 INFO success: docusaurus entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
Starting the development server...
Docusaurus website is running at: http://localhost:80/
ℹ Compiling Client
ℹ ｢wds｣: Project is running at http://0.0.0.0:80/
ℹ ｢wds｣: webpack output is served from /
ℹ ｢wds｣: Content not from webpack is served from /docusaurus/awesometic-docs
ℹ ｢wds｣: 404s will fallback to /index.html
✔ Client: Compiled successfully in 27.42s
ℹ Compiling Client
✔ Client: Compiled successfully in 507.94ms

因此，即使在运行此Docker镜像后无法访问它，容器本身可能没有损坏。等待1到2分钟，然后您就可以看到网站首页。

待处理事项

  • 生产模式 - 目前，此镜像始终以开发模式运行Docusaurus。开发模式允许管理员在编辑他们的网站时进行实时更新，但这并不是那么可靠，因为访问者也可以看到“正在编辑”的内容。目前可以接受，但将根据要求添加生产模式。

  • 支持HTTPS - 即使生成了准备好的证书文件，此镜像也不支持SSL，但是如果您有外部的Let's Encrypt程序和/或像"linuxserver/letsencrypt"这样的反向代理服务器，您可以应用SSL。

原文：https://github.com/awesometic/docker-docusaurus