mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-07-20 01:01:30 -05:00
Vijay Janapa Reddi
71c9afa0d7
Previously install-tl-collections.sh exited 0 even when collections in
tl_packages failed to install, so the Linux Docker image would tag and
publish as :latest with missing fonts/packages. The failure surfaced
hours later as a downstream PDF render error
('LaTeX Error: File `newpxtext.sty` not found') in book-build-container,
making the chain of causation hard to spot.
Every collection listed in tl_packages is required by the book PDF
build — there is no soft-dependency tier. If any of them cannot be
installed, exit non-zero so the container build fails fast and the
broken image is never published.
Also tighten the 'tlmgr not available' branch to fail rather than skip:
no tlmgr means no PDF build, so silently moving on is wrong.
Quarto Build Container
This directory contains the Docker container configuration for the MLSysBook build system.
Purpose
The container pre-installs all dependencies to eliminate the 30-45 minute setup time for Linux builds, reducing build times from 45 minutes to 5-10 minutes.
Structure
docker/quarto-build/
├── Dockerfile # Container definition
├── README.md # This file
└── .dockerignore # Files to exclude from build
Container Contents
- Base: Ubuntu 22.04
- TeX Live: Full distribution (texlive-full)
- R: R-base with all required packages
- Python: Python 3.13 with all requirements
- Quarto: Version 1.9.27
- Tools: Inkscape, Ghostscript, fonts
- Dependencies: All from
tools/dependencies/
Build Process
The container is built and tested via GitHub Actions:
# Trigger container build
gh workflow run build-container.yml
Usage
The container is used in the containerized build workflow:
container:
image: ghcr.io/harvard-edge/cs249r_book/quarto-build:latest
options: --user root
Testing
The container build includes 17 comprehensive tests:
- Quarto functionality
- Python packages (all from requirements.txt)
- R packages (all from install_packages.R)
- TeX Live and LaTeX engines
- Inkscape SVG to PDF conversion
- Ghostscript PDF compression
- Fonts and graphics libraries
- Quarto render test
- TikZ compilation test
- System resources check
- Network connectivity
- Book structure compatibility
- Quarto configuration files
- Dependencies files accessibility
- Quarto check (same as workflow)
- Actual build process simulation
- Memory and disk space verification
Registry
- Registry: GitHub Container Registry (ghcr.io)
- Image:
ghcr.io/harvard-edge/cs249r_book/quarto-build - Tags:
latest,main,dev, branch-specific tags - Size: ~2-3GB (includes TeX Live, R, Python packages)
Performance
The container reduces build times significantly:
- Traditional Linux build: 45 minutes (including dependency installation)
- Containerized build: 5-10 minutes (dependencies pre-installed)
- Container size: ~2-3GB (optimized with multi-layer cleanup)
- Build phases: 11 optimized phases with progress tracking
Recent Improvements (2025)
- Fixed dependency path issues after repository restructuring
- Improved error handling and progress tracking
- Optimized TeX Live package installation
- Enhanced cleanup procedures for smaller image size
- Added comprehensive testing (17 test scenarios)
- Fixed PATH environment variables for all tools
Build Phases
- System Dependencies - Core Ubuntu packages and libraries
- Inkscape Installation - SVG to PDF conversion capability
- Quarto Installation - Latest Quarto CLI (v1.9.27)
- TeX Live Installation - Complete LaTeX distribution
- Ghostscript Installation - PDF processing capabilities
- R Installation - R base and development packages
- Python Installation - Python 3 with pip
- Python Packages - All production requirements
- R Packages - All required R libraries
- R Package Verification - Validation of successful installation
- Comprehensive Cleanup - Size optimization and cache clearing
- Traditional build: 45 minutes
- Containerized build: 5-10 minutes
- Improvement: 80-90% time reduction