raabf/latex-versions

DockerTeX 与 DockerTeXstudio 镜像文档

镜像概述和主要用途

DockerTeX 与 DockerTeXstudio 是提供多版本TeX Live环境的Docker镜像，基于Debian和Ubuntu系统构建，包含完整的LaTeX包（texlive-full）及常用配套工具（如biber、make、gnuplot等）。DockerTeX提供命令行LaTeX环境，DockerTeXstudio在此基础上集成TeXstudio GUI编辑器，支持直接连接本地X服务器运行，适用于本地文档编辑和持续集成（CI）场景，确保跨环境LaTeX文档编译的一致性。

核心功能和特性

• 多TeX Live版本支持：提供2012年及以后的所有TeX Live版本，可通过TeX Live标签（如texlive2016）或发行版代号（如jessie）指定。
• 完整LaTeX环境：包含texlive-full包，涵盖几乎所有常用LaTeX模块，无需额外安装基础组件。
• TeXstudio GUI集成：DockerTeXstudio镜像内置TeXstudio编辑器，支持直接在本地X服务器运行，无需SSH X转发。
• 常用工具预安装：包含biber、make、gnuplot、inkscape、pandoc、python-pygments等文档处理工具。
• 文件所有权保持：容器内生成或修改的文件自动保留宿主用户的所有权（用户和组ID），避免权限问题。
• 易于安装与使用：支持通过zsh插件管理器、自动化脚本或手动安装，提供简洁的命令行接口。
• GUI功能完整：TeXstudio的“跳转到PDF”“跳转到源代码”（Synctex）及LanguageTool语法检查集成正常工作。
• 跨工具兼容：支持Docker和Podman CLI，可根据系统环境选择使用。
• 跨平台支持：部分标签支持ARM架构（如armhf-texlive2016），适配不同硬件环境。

支持的标签

可通过TeX Live版本或发行版代号指定镜像标签，主要标签信息如下：

¹ TeXstudio不再为该Linux发行版提供构建，容器使用最后可用版本；² 发行版已终止支持（EOL），无更新但镜像仍可使用。

使用场景和适用范围

• 本地文档编辑：通过TeXstudio GUI编辑LaTeX文档，支持多TeX Live版本切换，满足不同文档版本需求。
• 持续集成（CI）：在GitLab CI等环境中自动构建LaTeX文档，生成PDF制品，确保跨环境一致性。
• 多版本测试：验证文档在不同TeX Live版本下的编译兼容性，避免版本差异导致的错误。
• 跨平台支持：支持x86和部分ARM架构，适配桌面和嵌入式设备。

使用方法和配置说明

前提条件

需安装Docker或Podman CLI。DockerTeXstudio镜像包含DockerTeX所有功能，若已安装DockerTeXstudio，DockerTeX会自动使用其镜像以节省磁盘空间。首次使用时，工具会提示拉取所需镜像。

dockertex（命令行工具）

用于在容器中运行LaTeX命令，挂载当前工作目录并保持文件所有权。

基本语法

bash
dockertex [-t|--tag 标签名] 命令

使用示例

1. 编译document.tex（使用TeX Live 2016）：

   bash
   dockertex --tag texlive2016 pdftex document.tex
   

2. 使用Makefile编译（使用Debian Jessie发行版对应的TeX Live版本）：

   bash
   dockertex --tag jessie make all
   

环境变量配置

• 默认标签：设置DOCKERTEX_DEFAULT_TAG指定默认标签，无需每次使用--tag：

  bash
  export DOCKERTEX_DEFAULT_TAG="texlive2016"
  

• 容器引擎：默认优先使用Podman，若需指定Docker，设置DOCKERTEX_ENGINE：

  bash
  export DOCKERTEX_ENGINE="docker"  # 或 "podman"
  

dockertexstudio（GUI工具）

用于启动TeXstudio GUI，挂载用户主目录，支持配置持久化、Synctex跳转和LanguageTool集成。

基本语法

bash
dockertexstudio [-t|--tag 标签名] [-v|--volume 映射]* [texstudio选项]

使用示例

1. 启动TeXstudio（使用最新标签）：

   bash
   dockertexstudio --tag latest
   

2. 挂载额外卷（如将/media/git/映射到容器内/home/git/）：

   bash
   dockertexstudio --tag texlive2016 --volume /media/git/:/home/git/
   

3. 使用x11docker（增强安全性）：

   bash
   x11docker --network=host --share $HOME raabf/texstudio-versions:texlive2019
   

关键特性

• 配置持久化：TeXstudio配置保存在本地目录，执行dockertexstudio --help可查看路径。
• 菜单条目：安装后生成桌面菜单条目，支持直接打开.tex文件（需文件路径内外一致）。
• Synctex跳转：支持“跳转到PDF”和“跳转到源代码”功能。
• LanguageTool集成：在宿主启动LanguageTool（默认本地端口），容器通过共享网络访问。

TeXstudio显示故障排除

授权问题

使用Docker时若出现“Authorization required, but no authorization protocol specified”，需在宿主执行：

bash
xhost local:root

（允许root用户访问本地X服务器）。

进一步认证

若仍有认证问题，可能需要将宿主xauth list生成的令牌传递给容器，参考https://gitlab.com/raabf/dockertex/-/issues/1#note_***%E3%80%82

DISPLAY变量问题

若提示找不到显示，尝试修改dockertexstudio.sh中的--env='DISPLAY'为-e DISPLAY=unix$DISPLAY。

安装方法

zsh插件管理器（推荐）

通过zsh插件管理器（如zplug）安装，可自动更新。支持安装TeXstudio菜单条目。

zplug配置示例

在~/.zshrc中添加：

zsh
zplug raabf/dockertex, \
    from:gitlab, \
    hook-build:"./posthook.sh --menu-tag latest --menu-volume /media/ext/=/home/ext/"

--menu-tag指定菜单条目使用的标签，--menu-volume用=替代:指定额外卷映射。

自动化脚本

适用于非zsh用户，支持安装CLI和菜单条目。

安装命令（带菜单条目）

bash
curl https://gitlab.com/raabf/dockertex/raw/master/install.sh | bash -s -- --menu-tag latest --menu-volume "/media/ext/:/home/ext/"

系统级安装

bash
curl https://gitlab.com/raabf/dockertex/raw/master/install.sh | bash -s -- --system --menu-tag latest --menu-volume /media/ext/:/home/ext/

手动安装

1. 复制CLI脚本到PATH目录：

   bash
   sudo cp bin/dockertex.sh /usr/local/bin/dockertex
   sudo cp bin/dockertexstudio.sh /usr/local/bin/dockertexstudio
   chmod a+x /usr/local/bin/dockertex*
   

2. 复制TeXstudio图标：

   bash
   cp misc/icons/hicolor/scalable/apps/texstudio.svg /usr/local/share/icons/hicolor/scalable/apps/
   

3. 创建菜单条目：

   bash
   cp misc/dockertexstudio.desktop /usr/local/share/applications/dockertexstudio-stretch.desktop
   echo "Name=Docker TexStudio (stretch)
   Exec=/usr/local/bin/dockertexstudio --tag latest %F
   Icon=/usr/local/share/icons/hicolor/scalable/apps/texstudio.svg" >> /usr/local/share/applications/dockertexstudio-stretch.desktop
   

持续集成（CI）配置示例

GitLab CI

1. 注册Runner：在安装Docker的服务器上注册Runner，选择docker执行器：

   bash
   sudo gitlab-runner register --url https://gitlab.com/ --executor "docker" --tag-list "docker, latex, dockertex" --docker-image "raabf/latex-versions:latest"
   

2. 配置.gitlab-ci.yml：

   yaml
   ---
   stages:
     - latex
   
   before_script:
     - lsb_release --all
     - latex --version
   
   make_texlive2016:
     image: docker.xuanyuan.run/raabf/latex-versions:texlive2016
     stage: latex
     tags:
       - docker
     script:
       - make all
     artifacts:
       paths:
         - ./thesis.pdf
       expire_in: 1 week
   
   make_texlive2017:
     image: docker.xuanyuan.run/raabf/latex-versions:texlive2017
     stage: latex
     tags:
       - docker
     script:
       - make all
     artifacts:
       paths:
         - ./thesis.pdf
       expire_in: 1 week
   

上述配置在不同TeX Live版本下编译文档，生成thesis.pdf作为制品并保留1周。

贡献

项目托管于https://gitlab.com/raabf/dockertex/%EF%BC%8C%E6%AC%A2%E8%BF%8E%E9%80%9A%E8%BF%87https://gitlab.com/raabf/dockertex/issues%E5%8F%8D%E9%A6%88%E9%97%AE%E9%A2%98%E6%88%96%E6%8F%90%E4%BA%A4%E8%B4%A1%E7%8C%AE%E3%80%82