Packer文档网站构建镜像

镜像概述和主要用途

本镜像是用于构建和生成Packer官方文档网站的专用工具镜像。基于文档生成引擎（如Hugo）构建，集成了文档渲染、静态资源处理及依赖管理功能，支持本地预览、静态文件生成及CI/CD流程集成，旨在简化Packer文档的开发、构建与部署流程。

核心功能和特性

• Hugo文档引擎集成：内置HashiCorp官方文档常用的Hugo引擎及主题，确保文档风格与官方一致。
• 依赖自动管理：预安装文档构建所需的所有依赖（如主题、插件、Markdown处理器），无需手动配置。
• 静态资源生成：支持将Markdown源文件转换为可直接部署的静态HTML/CSS/JS资源。
• 本地预览支持：提供Web服务器功能，可在本地启动预览服务，实时查看文档渲染效果。
• 版本控制集成：支持通过环境变量指定文档版本，便于多版本文档并行构建。
• 轻量级设计：基于Alpine Linux，镜像体积小，启动速度快，适合CI/CD环境。

使用场景和适用范围

使用方法和配置说明

前提条件

• 已安装Docker Engine（20.10+）或Docker Desktop。
• 本地已克隆Packer文档源码（通常位于[***]）。

基本使用命令

1. 本地预览文档（开发模式）

启动本地Web服务器，实时预览文档（修改源码后自动刷新）：

docker run -d \
  --name packer-docs-dev \
  -p 1313:1313 \  # 映射预览端口（默认1313）
  -v /path/to/packer-docs:/docs \  # 挂载本地文档源码目录
  hashicorp/packer-docs-builder:latest \
  hugo server --bind 0.0.0.0 --source /docs

访问 http://localhost:1313 即可预览文档。

2. 构建静态文档文件

生成可部署的静态HTML文件至本地目录：

docker run --rm \
  -v /path/to/packer-docs:/docs \  # 文档源码目录
  -v /local/output:/output \  # 本地输出目录（挂载到容器内/output）
  hashicorp/packer-docs-builder:latest \
  hugo --source /docs --destination /output

静态文件将生成到 /local/output 目录，可直接部署至Nginx、S3等服务。

挂载自定义配置

如需覆盖默认配置（如Hugo主题、文档结构），可挂载自定义配置文件：

docker run -d \
  -p 1313:1313 \
  -v /path/to/packer-docs:/docs \
  -v /local/custom-config:/docs/config \  # 挂载自定义配置目录（覆盖默认config.toml）
  hashicorp/packer-docs-builder:latest \
  hugo server --source /docs

环境变量说明

通过环境变量可自定义构建行为，支持以下参数：

Docker Compose配置示例

创建 docker-compose.yml 实现本地开发环境一键启动：

version: '3.8'
services:
  packer-docs:
    image: hashicorp/packer-docs-builder:latest
    ports:
      - "1313:${PORT:-1313}"  # 使用环境变量PORT，默认1313
    volumes:
      - ./packer-docs:/docs  # 本地文档源码目录（需提前克隆）
      - ./output:${OUTPUT_DIR:-/output}  # 静态文件输出目录
    environment:
      - DOCS_VERSION=v1.10.0
      - HUGO_THEME=hashicorp-learn
      - HUGO_FLAGS=--minify
    command: hugo server --bind 0.0.0.0 --source /docs

启动命令：

docker-compose up -d

访问 http://localhost:1313 预览文档，修改本地 packer-docs 目录文件后自动刷新。