Running LuaTeX in Docker, Remotely — Heavy Typesetting Without Polluting the Local Machine

Setting up LuaTeX for academic typesetting hits a practical wall: a full TeX Live installation is several gigabytes, the font ecosystem adds hundreds of megabytes more, and dependent packages behave differently across operating systems. The desire is modest ── write a paper or a report ── yet the local machine is steadily consumed by typesetting infrastructure.

The wish to keep typesetting capability without sacrificing local environment cleanliness has a clean answer: isolate the compilation environment in a remote Docker container. This article walks through the design of one implementation, luatex-docker-remote², component by component, with the design decisions surfaced where they matter.

Design Stance ── Local Minimal, Typesetting Maximal

The starting point is simple:

• Local environment: text editor + .tex / .sty / figure files only
• Typesetting capability: full TeX Live + comprehensive font ecosystem + LuaLaTeX-ja for CJK
• The bridge: rsync + SSH + Docker

Concretely, when the user types luatex-pdf document.tex on their local machine, the following sequence runs underneath:

1. Local .tex / .sty / image files are rsynced to the remote Docker host
2. A Docker container on the remote host launches LuaTeX and produces a PDF
3. The generated PDF is fetched back to the local machine; the temporary remote files are cleaned up

What remains on the local machine is the PDF only. TeX Live, fonts, caches ── all sealed inside the remote container. The local environment is minimal; the typesetting capability is maximal, and neither side compromises the other.

In the vocabulary of the foundational essay Relative, Not Deterministic, this is a design for keeping the mediator under control¹. The LuaTeX environment is a mediator ── it prescribes what can be typeset and how ── but unfolded onto the local machine, the TeX Live version, the font state, the dependency behaviour all become entangled with everything else you do, and the environment drifts toward “can’t throw it away”. Isolated in a container, the boundary of the mediation is made physically explicit; it can be swapped wholesale or discarded. The stance is: don’t let the mediator grow on its own, out of your hands.

Network Auto-Detection ── One Command Across Locations

The most awkward practical issue in remote-host workflows is that SSH endpoints differ between home and outside. At home an internal hostname (zeus, say) reaches the host via the LAN; outside, only a global IP or domain name (zeus-external) reaches it through a different port. Most users want a single command to work in both cases without a flag for the location.

luatex-docker-remote’s network auto-detection implements this as a two-step decision:

1. Fetch the current global IP
2. Compare to the registered “home global IP”

If the two match, connect via the internal hostname; if they differ, connect via the external hostname. The configuration lives in two files ── ~/.home_global_ip and ~/.config/luatex/network-config ── with first-time setup wrapped in make setup-network.

The implementation is unsophisticated; the user-experience effect is not. A single command, luatex-pdf document.tex, has the same meaning at home and at a café.

.sty Auto-Sync ── A Two-Layer Convention

Style files (.sty) in LaTeX traditionally split into two patterns:

• Project-local: a .sty specific to a single project, placed alongside the .tex
• System-shared: a .sty placed in TEXMFHOME (~/.local/share/texmf/tex/latex/) and used across all projects

luatex-docker-remote honours both²:

• .sty files in the same directory as the .tex are rsynced together
• .sty files under ~/.config/luatex/styles/ are mounted into the container at startup and available to every project

The two-layer split mirrors the design discipline familiar from per-project versus user-global configuration files (.gitignore per repository vs. global ~/.gitignore, project .editorconfig vs. user defaults, etc.). Settings that belong to a project, and settings that span projects, are physically separated to prevent collisions ── a standard move in computational environment design.

A CJK-Friendly Font Ecosystem

Japanese typesetting in LuaLaTeX has historically been a sticking point. Until Adobe Source Han, individual fonts (IPA / IPAex / Takao) had to be installed and licence-checked one by one, with substantial up-front investment.

The luatex-docker-remote Docker image ships with the Japanese fonts pre-installed²:

• Harano Aji ── a TeX-optimised derivative of Adobe Source Han
• Noto CJK ── Google / Adobe’s open-source CJK family
• IPA / IPAex ── traditional academic fonts maintained by the Information-Technology Promotion Agency (Japan)
• Takao / M+ / Sawarabi / VL Gothic and others

For mathematical documents using Libertinus Math as the body / math font, the recommended Japanese pairing is Harano Aji, on the grounds that the Source Han glyph weight aligns visually with Libertinus Serif and the grayscale balance of mixed CJK / Latin text comes out clean³.

For mathematical typesetting in physics / engineering documents, Libertinus Math is one of the few open-source mathematical fonts that work cleanly with the unicode-math package⁴. This combination ── Libertinus + Harano Aji ── is what the writer uses as the personal default. International readers writing CJK alongside Latin scripts benefit from the same out-of-the-box configuration regardless of the body language they primarily target.

Operational Flow ── Transparency and Idempotence

With the design in place, day-to-day usage simplifies to a small set of commands:

# Standard compile (LuaLaTeX + Japanese)
luatex-pdf document.tex

# Watch mode ── re-compile on file changes
luatex-pdf -w document.tex

# Engine swap (upLaTeX, pLaTeX, XeLaTeX, pdfLaTeX)
luatex-pdf -e uplatex document.tex

Behind the single luatex-pdf command runs the full sequence: rsync (local → remote), SSH-driven Docker launch, compilation, PDF retrieval (remote → local), and remote cleanup. All of this is transparent to the user in a single invocation.

make uninstall removes the local-side configuration files and symbolic links cleanly ── a deliberate property, since being easy to throw away is just as important as being easy to install. A tool one cannot uninstall is a tool one hesitates to install.

---

Re-read in 2026, this kind of environment design carries an implication beyond convenient tooling: it is itself an act of arranging the extension of thought.

Umesao Tadao, in The Technique of Intellectual Production (1969)⁵, proposed that the technique of separating and reintegrating thought from procedural work sat at the centre of intellectual production. Andy Clark and David Chalmers, in their 1998 extended mind paper, gave the philosophical formulation: external tools and media can constitute components of cognitive systems⁶. Read against an environment design like luatex-docker-remote, these claims map directly:

• Local environment cleanliness = thinking flow undisturbed (Umesao’s card-writing analogue)
• Container isolation on the remote = processing apparatus placed outside the cognitive locus (Clark & Chalmers’ external cognitive devices)
• Network auto-detection = tool operation lowered into the automatic-processing layer (Shiffrin & Schneider’s automatic processing⁷)

Typesetting environment design, in other words, is a computational problem and equally a cognitive-environment ── a mediation ── problem. What Clark and Chalmers framed as the extended mind, and what this site calls mediation, are the same situation through different entrances¹, appearing here as “where, and how isolated, do you keep the apparatus that mediates typesetting”. That a single command behaves correctly across contexts, that the local machine is not polluted, that the tool is easy to uninstall ── these are all conditions for keeping the mediator under control while leaving the writer’s flow of thought uninterrupted.

This article belongs to the systems-track lineage on the dlab site. The companion essay Writing as Thinking — Where Tools and Thought Meet (currently in Japanese), and the foundational essay Relative, Not Deterministic, make the argument explicit: the environment one builds is the cognitive substrate one writes from ── and this is the typesetting-environment instance of the stance of not treating a tool as the correct procedure, but making the range it mediates explicit and keeping it swappable as the situation changes.

References