As a LaTeX user with a Mac machine, I wanted a clean, containerized setup for document writing in VSCode. However, most of the containers were built for AMD64 devices, with platform compatibility issues for ARM64 users. Here’s how I configured a minimal LaTeX environment using Docker and the LaTeX Workshop extension, on the Apple Silicon platform.

The Docker Solution

I created a lightweight LaTeX Docker image (noahwu/minimal-latex) specifically optimized for ARM64 architecture. The image is based on debian:bullseye-slim and includes only the essential LaTeX packages needed for most document writing tasks.

The Docker image includes:

• Basic texlive distribution
• Common LaTeX extras (texlive-latex-extra)
• Scientific and picture packages
• latexmk for building
• Supporting tools (git, wget, python3-pygments)

Getting Started

1. Install Docker and VSCode
2. Install the LaTeX Workshop extension for VSCode. Restart it if the LaTeX Workshop icon does not show up on the sidebar after installation.
3. Copy the configuration below to your settings.json
4. Compile a .tex file (compile icon would show up in the upper right corner as a triangle if you are opening a .tex file), and it initializes for you. Or manually, pull the Docker image: docker pull noahwu/minimal-latex:latest
5. Start writing your LaTeX documents!

The PDF viewer is configured to open in a new tab within VSCode, making it easy to see your changes as you write.

VSCode Configuration

For the extension

Here’s the essential configuration for settings.json:

{
  "latex-workshop.docker.enabled": true,
  "latex-workshop.docker.platform": "linux/arm64",
  "latex-workshop.docker.image.latex": "noahwu/minimal-latex:latest"
}

Build Recipes

I’ve set up two build recipes:

1. A simple latexmk workflow
2. A traditional pdflatex + bibtex workflow

"latex-workshop.latex.recipes": [
  {
    "name": "latexmk",
    "tools": ["latexmk"]
  },
  {
    "name": "pdflatex",
    "tools": ["pdflatex", "bibtex", "pdflatex", "pdflatex"]
  }
],

LaTeX Tools Configuration

An essential part of the setup is configuring the LaTeX tools that will be used for compilation, e.g., the recipes above. Here’s how I configured the three main tools:

"latex-workshop.latex.tools": [
    {
      "name": "latexmk",
      "command": "latexmk",
      "args": [
        "-synctex=1",           // Enable SyncTeX for source-PDF synchronization
        "-interaction=nonstopmode",  // Keep compiling even if there are errors
        "-file-line-error",     // Show file and line number for errors
        "-pdf",                 // Generate PDF output
        "-outdir=%OUTDIR%",     // Output directory
        "%DOC%"                 // Input file
      ]
    },
    {
      "name": "pdflatex",
      "command": "pdflatex",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-recorder",            // Record dependencies in .fls file
        "%DOC%"
      ]
    },
    {
      "name": "bibtex",
      "command": "bibtex",
      "args": ["%DOCFILE%"]     // Process bibliography
    }
]

Let’s break down each tool:

1. latexmk: This is a Perl script that automates the process of generating a LaTeX document. It determines which commands need to be run and in what order, making it particularly useful for documents with bibliographies and cross-references.
2. pdflatex: This is the traditional LaTeX compiler that directly produces PDF output. The configuration includes options for better error reporting and synchronization between the source and output.
3. bibtex: This tool processes bibliography files (.bib) to generate the formatted bibliography in your document.

The arguments for each tool are carefully chosen to provide:

• Detailed error reporting (-file-line-error)
• Continuous compilation even when errors occur (-interaction=nonstopmode)
• Source-PDF synchronization (-synctex=1)
• Proper output directory handling (-outdir=%OUTDIR%)

These tools work in conjunction with the recipes we defined earlier, allowing for both simple one-step compilation with latexmk and more traditional multi-step compilation with pdflatex and bibtex.

Compilation Cleanup Configuration

To keep your working directory clean, I’ve configured the extension to remove common auxiliary files:

"latex-workshop.latex.clean.fileTypes": [
  "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind",
  "*.lof", "*.lot", "*.out", "*.toc", "*.acn",
  "*.acr", "*.alg", "*.glg", "*.glo", "*.gls",
  "*.ist", "*.fls", "*.log", "*.fdb_latexmk"
],
  "latex-workshop.latex.autoClean.run": "onBuilt",
  "latex-workshop.latex.clean.method": "glob"

Customization

If you need to customize the LaTeX environment, the Dockerfile is publicly available below in the post. You can modify it to add additional packages or tools as needed. The Dockerfile uses build arguments for easy customization of the user settings:

ARG USER_NAME=latex
ARG USER_HOME=/home/latex
ARG USER_ID=1000
ARG USER_GECOS=LaTeX

Benefits of This Setup

1. Isolated Environment: The Docker container keeps your LaTeX installation separate from your system.
2. Reproducible: Anyone can use the same setup by pulling the Docker image.
3. Lightweight: Only includes essential packages to keep the image size minimal.
4. ARM64 Optimized: Specifically built for modern ARM64 architecture.

Conclusion

This setup provides a clean, containerized LaTeX environment that’s easy to set up and maintain. The combination of Docker and VSCode’s LaTeX Workshop extension creates a powerful yet lightweight document writing environment that works especially well on ARM64 systems.

Feel free to customize the Docker image or VSCode settings to better suit your needs. The Dockerfile is available for those who want to add additional packages or make other modifications to the base image.

FROM debian:bullseye-slim

# Use build args for customization
ARG USER_NAME=latex
ARG USER_HOME=/home/latex
ARG USER_ID=1000
ARG USER_GECOS=LaTeX

# Create user
RUN adduser \
--home "$USER_HOME" \
--uid $USER_ID \
--gecos "$USER_GECOS" \
--disabled-password \
"$USER_NAME"

# Install only essential packages
RUN apt-get update && apt-get install -y --no-install-recommends \
texlive \
texlive-latex-extra \
texlive-pictures \
texlive-science \
latexmk \
make \
git \
wget \
python3-pygments && \
rm -rf /var/lib/apt/lists/* && \
apt-get clean

# Set working directory
WORKDIR $USER_HOME
USER $USER_NAME

# Add a healthcheck
HEALTHCHECK CMD pdflatex --version || exit 1

# Add labels for better maintainability
LABEL maintainer="noahwo" \
description="Lightweight LaTeX environment for ARM64" \
version="1.0"