awesometic/docusaurus

docker-docusaurus

![]([] ![]([]

![]([] ![]([] ![]([***]

镜像概述和主要用途

什么是Docusaurus

引用官方网站的描述：

Docusaurus 便于维护开源文档网站。

本项目提供的功能

本镜像旨在为使用Docker构建服务器的用户提供便利，简化Docusaurus文档网站的部署和管理流程。

核心功能和特性

基础包

采用Alpine Linux作为基础以实现轻量级服务，并选择node-alpine作为基础镜像以支持Node.js版本的灵活调整。主要包含：

• Alpine Linux 3.15
• Node.js 17.4.0

同时内置：

• 最新的Docusaurus 2 beta版本，支持自动更新

Docusaurus 2

本镜像运行Docusaurus 2 beta版本（而非稳定版Docusaurus 1）。Docusaurus 2目前处于积极开发阶段，预计将在不久后正式发布。

!Docusaurus 2首页

从Docusaurus 1升级到Docusaurus 2需要进行迁移工作，因此建议新构建文档网站的用户直接使用Docusaurus 2。由于当前为beta版本，镜像默认启用自动更新机制，可通过设置环境变量AUTO_UPDATE=false禁用。

数据备份建议

强烈建议定期备份文档数据。由于硬盘物理损坏、开发或维护过程中的软件故障等原因，需将数据备份至安全位置。

多架构支持

通过GitHub Actions构建，支持多种架构，包括AMD64(x86_64)、ARM64、ARMv7和ARMv6，可在大多数支持Docker的设备上使用。

使用场景和适用范围

适用于需要通过Docker快速部署文档网站的用户，尤其是：

• 开源项目文档站点维护者
• 需要跨架构部署文档服务的场景
• 希望简化Docusaurus环境配置的开发者

使用方法和配置说明

拉取镜像

从Docker Hub拉取镜像：

bash
docker pull awesometic/docusaurus

基本用法

可通过以下命令进行试运行（--rm选项会在终止交互会话时删除容器）：

bash
docker run -it --rm \
-p 80:80 \
-v /config/dir:/docusaurus \
awesometic/docusaurus

该镜像需要映射主机的一个卷：

• /docusaurus：Docusaurus源代码文件所在目录

首次运行时，由于需要从互联网下载和准备完整源码，可能需要几分钟时间。详见下文“何时可以访问网站”章节。

首次运行后，将生成具有以下特性的基础Docusaurus网站：

• 项目源码使用UID 1000和GID 1000，支持非root用户编辑
• 启用自动更新
• 网站名称为“MyWebsite”
• 使用“classic”模板

若需以守护进程模式运行并自定义参数，可使用以下命令：

bash
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 \
awesometic/docusaurus

容器运行后，通过浏览器访问：

http
http://localhost/

生产模式

默认情况下，镜像以开发模式运行，支持文档编辑后实时预览。若需构建源码并以生产模式运行，可通过设置RUN_MODE环境变量实现：

bash
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

生产模式运行时日志示例：

shell
/* 将以生产模式运行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服务器会提供构建后的静态文件，也可通过Nginx或Apache等其他Web服务器提供服务。执行docker restart [container-id]命令可更新构建文件。

何时可以访问网站

首次运行（即首次创建配置文件时），用户无法立即访问网站，因为初始化过程需要从互联网下载最新Docusaurus源码，耗时通常超过1分钟。可通过容器日志判断是否就绪：

Variables:
        - UID=1000
        - GID=1000
        - AUTO_UPDATE=true
        - WEBSITE_NAME=awesometic-docs
        - TEMPLATE=classic
        - RUN_MODE=development
/* 注册自动更新的定时任务... */
/* 注册成功。 */
/* 安装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已存在于/docusaurus/awesometic-docs/node_modules */
/* 启动supervisord以运行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 website is running at: http://localhost:80/且编译成功后，即可访问网站。若运行后无法立即访问，无需担心容器故障，等待1-2分钟即可。

待办事项

• 生产模式 - 目前默认以开发模式运行（支持实时更新，但访问者可能看到编辑中的内容），已支持通过环境变量切换至生产模式。
• HTTPS支持 - 镜像暂不直接支持SSL，但可通过外部Let's Encrypt程序或反向代理服务器（如"linuxserver/letsencrypt"）实现。

许可证

本项目采用MIT许可证。详见许可证文件。