Docker / CI 설정

자신의 컴퓨터에 TeX를 설치할 필요는 없습니다. Docker 이미지는 전체 조판 환경을 패키지하므로 어디에서나 동일한 절차를 통해 .tex를 PDF로 바꿀 수 있습니다. 이는 GitHub Actions와 같은 CI(지속적 통합)과 자연스럽게 결합됩니다. 모든 푸시는 자동으로 PDF를 빌드하고 아티팩트로 저장할 수 있습니다. 이 페이지에서는 인기 있는 texlive/texlive 이미지와 TeX 빌드를 CI에서 자동화하고 재현 가능하게 만드는 방법을 다룹니다.

컨테이너에 조판하는 이유

배포판이 "TeX 환경 자체"(배포판 참조)인 경우 Docker 이미지는 OS와 함께 고정된 해당 환경을 배송하는 상자입니다. 상자 안에는 특정 버전의 TeX Live, 엔진, 패키지 및 글꼴이 있습니다. 따라서 호스트가 Windows, macOS 또는 CI 서버인지에 관계없이 동일한 상자를 열면 동일한 환경이 제공됩니다. 가장 큰 이점은 "내 컴퓨터에서는 작동하지만 내 동료의 설정에서는 실패하거나 CI에서 실패합니다"라는 불일치를 피하는 것입니다.

컨테이너와 데스크톱 설치는 상호 배타적이지 않습니다. 일반적인 분할은 편집자와 로컬 TeX(데스크탑 설치 참조)를 사용하여 일상적인 작업을 작성하고 최종 빌드, 협업 또는 게시만 컨테이너 또는 CI에 전달하는 것입니다. 핵심 단어는 재현성입니다. 버전을 태그로 고정하고 반년 후에 다시 빌드해도 여전히 동일한 PDF가 생성됩니다.

texlive/texlive 이미지

TeX Live에 널리 사용되는 이미지는 texlive/texlive이며, Docker Hub(docker.io/texlive/texlive) 및 GitLab(registry.gitlab.com/islandoftex/images/texlive)에 Island of TeX 이미지로 게시됩니다. 내부에는 latexmk와 같은 엔진, 패키지 및 도구가 포함된 TeX Live(2026년 안정 릴리스는 TeX Live 2026)가 있습니다. 주간 빌드는 CTAN 업데이트를 추적합니다.

태그를 사용하면 구성표(크기 등급)를 선택할 수 있습니다. minimal, basic, small, medium, full의 5가지가 있으며 latest는 가장 큰 full(모든 패키지)에 매핑됩니다. 문서 및 소스 포함 여부와 이를 결합할 수 있습니다. 기본 태그에는 둘 다 포함되지 않고, -doc는 문서를 추가하고, -src는 소스를 추가하고, -doc-src는 둘 다 추가합니다. 문서와 소스는 부피가 큽니다. CI는 거의 필요하지 않으므로 단순하거나 작은 구성표가 더 빨리 가져옵니다. ConTeXt 사용자를 위한 -context 변형도 있습니다.

사용법은 간단합니다. 현재 디렉터리가 컨테이너에 마운트된 docker run를 사용하고 그 안에서 latexmk를 실행합니다. 다음은 로컬 main.tex의 일회성 빌드입니다. --rm는 나중에 컨테이너를 삭제하고, -v "$PWD":/work는 현재 위치를 /work에 매핑하고, -w /work는 해당 위치를 작업 디렉터리로 만듭니다. 결과 PDF는 폴더에 바로 다시 저장됩니다.

docker run --rm -v "$PWD":/work -w /work texlive/texlive latexmk -pdf main.tex

일본어 문서의 경우 일반 latexmk 대신 특정 엔진을 실행합니다. .latexmkrc를 제공하면 LuaLaTeX의 경우 latexmk -lualatex main.tex, upLaTeX + dvipdfmx 경로의 경우 latexmk main.tex입니다. 마운트는 동일한 방식으로 작동합니다. 입력과 출력이 모두 로컬 디렉터리에 있습니다.

재현성을 위해 환경을 동결합니다. latest는 매주 새로운 TeX Live 스냅샷으로 이동하므로 이를 논문의 최종 빌드 또는 출시된 교육 자료의 기본값으로 두지 마십시오. 먼저 TeX Live 릴리스 연도와 버전을 선택하고 적절한 경우 과거 릴리스 태그를 사용하십시오. 그러나 Docker Hub가 언급한 것처럼 기본 OS 이미지가 업데이트되면 기록 이미지도 다시 빌드할 수 있습니다. 나중에 완전히 동일한 컨테이너가 필요한 경우 이미지 다이제스트와 태그를 고정하거나 알려진 양호한 이미지를 자체 레지스트리에 저장하세요.

GitHub Actions를 사용한 자동화된 빌드

GitHub 저장소의 경우 GitHub Actions는 푸시할 때마다 .tex를 컴파일할 수 있습니다. 인기 있는 선택은 xu-cheng/latex-action@v4입니다. 내부에 TeX Live가 있는 컨테이너를 사용하고 기본적으로 latexmk를 호출하므로 워크플로는 단 몇 줄에 불과합니다. 다음은 푸시할 때마다 저장소 루트에 main.tex를 빌드하고 PDF를 빌드 아티팩트로 저장하는 최소 예입니다.

name: Build LaTeX document
on: [push]

jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repository
        uses: actions/checkout@v6

      - name: Compile the document
        uses: xu-cheng/latex-action@v4
        with:
          root_file: main.tex

      - name: Upload the PDF
        uses: actions/upload-artifact@v6
        with:
          name: PDF
          path: main.pdf

푸시 시 컨테이너는 GitHub의 실행기에서 시작되고 root_file에 명명된 main.tex는 latexmk에 의해 컴파일됩니다. 기본 latexmk 인수는 -pdf -file-line-error -halt-on-error -interaction=nonstopmode입니다. 이는 오류 발생 시 중지되고 프롬프트 없이 끝까지 실행되는 CI 친화적인 설정입니다. 완성된 PDF는 작업 실행 페이지에서 아티팩트로 다운로드할 수 있습니다.

주요 입력(with:)을 알아보세요. root_file는 빌드 대상입니다(글로브 허용). LuaLaTeX의 경우 latexmk_use_lualatex: true 또는 XeLaTeX의 경우 latexmk_use_xelatex: true로 엔진을 전환하세요(일본어의 경우 LuaLaTeX가 더 쉬운 경로입니다). texlive_version는 2020–2026 또는 latest를 선택하므로 재현성을 위해 연도별로 고정할 수 있습니다. os는 기본 운영 체제입니다. 기본값은 경량 alpine이며 필요할 때 debian를 사용할 수 있습니다. \write18를 사용하는 패키지의 경우 latexmk_shell_escape: true를 설정하십시오.

빌드를 더 빠르게 만들기 위해 actions/cache를 통해 실행할 때마다 다시 설치되거나 다시 다운로드되는 항목을 캐시할 수 있습니다. 즉, latex-action는 이미 상당한 TeX Live를 번들로 제공하므로 대부분의 프로젝트는 기본적으로 실제 속도로 실행됩니다. 최소한의 설정으로 시작하고 속도 저하가 실제로 문제가 될 때만 최적화하십시오.

GitLab CI는 동일한 접근 방식을 취합니다

GitLab CI는 동일한 아이디어를 따르며, 전용 작업을 사용하는 대신 이미지 이름을 직접 지정하면 됩니다. 작업의 image:를 texlive/texlive:latest(또는 날짜 고정 태그)로 설정하고, script:에서 latexmk -pdf main.tex를 실행하고, artifacts:를 통해 PDF를 저장합니다. 동일한 이미지에 있기 때문에 GitHub Actions와 동일한 조판 결과를 얻습니다.

build:
  image: texlive/texlive:latest
  script:
    - latexmk -pdf main.tex
  artifacts:
    paths:
      - main.pdf

본질은 모든 서비스에서 동일합니다. 버전 고정 이미지 내에서 latexmk가 원샷 빌드를 구동하고 결과 PDF를 아티팩트로 수집하도록 합니다. 이는 컨테이너 또는 CI에서 TeX를 실행하기 위한 공유 패턴입니다. 일상적인 자동화 빌드의 메커니즘은 "CI" 및 "자동 빌드" 페이지에서 자세히 살펴봅니다.

원고 CI를 준비하세요

CI에서 잘 작동하는 원고는 편집기 설정에 의존하지 않습니다. 루트 파일, 엔진, 도우미 명령 및 출력 위치가 저장소에 기록됩니다. 일본어 작업의 경우 main.tex 옆에 .latexmkrc를 넣고 명시적으로 upLaTeX 또는 LuaLaTeX를 선택하세요. 랩톱과 CI가 모두 동일한 latexmk main.tex를 실행하는 경우 마지막 순간에 "내 컴퓨터에서만 빌드합니다" 오류를 피할 수 있습니다.

# .latexmkrc: upLaTeX + dvipdfmx
$latex = "uplatex -interaction=nonstopmode -halt-on-error %O %S";
$bibtex = "upbibtex %O %B";
$dvipdf = "dvipdfmx %O -o %D %S";
$pdf_mode = 3;

이 .latexmkrc를 커밋하면 Docker와 GitHub Actions는 동일한 규칙에 따라 PDF를 빌드합니다. 실행할 때마다 tlmgr install를 사용하여 임시 패키지를 설치하는 대신 프로젝트에 필요한 내용이 이미 포함되어 있는 TeX Live 구성표 또는 고정된 이미지 태그를 선택하십시오. 빌드가 더 빠르고 실패를 추적하기가 더 쉽습니다.