avatarShinichi Okada

Summary

The web content provides a comprehensive guide on setting up a Dockerized LaTeX environment using three different methods, integrating it with Visual Studio Code (VSCode) and its Remote-Containers extension for a seamless development experience.

Abstract

The article outlines three approaches to create a Dockerized LaTeX environment, emphasizing the use of Docker containers for consistent development setups across different operating systems. The first method involves using the tianon/latex Docker image and configuring VSCode settings to enable LaTeX compilation within a container. The second method leverages the VSCode Remote-Containers extension to develop within a Docker container using the qmcgaw/latexdevcontainer image, which is pre-configured with essential LaTeX tools and packages. The third method guides readers through creating a custom Docker container based on qmcgaw/latexdevcontainer, allowing for the installation of additional LaTeX packages and personalized configurations. The article also covers how to switch between different remote containers and view compiled PDFs within VSCode. It concludes by discussing the advantages and trade-offs of the described methods, such as the image size and the need for package installations.

Opinions

  • The author suggests that using Docker for LaTeX provides full control over the environment, allowing for the installation of necessary tools without affecting the host system.
  • The preference for qmcgaw/latexdevcontainer over tianon/latex is implied due to its smaller image size and the ability to customize it further.
  • The author expresses the convenience of auto-updating PDFs upon saving the LaTeX source file, highlighting the efficiency of the setup.
  • The use of VSCode's LaTeX Workshop extension is recommended for its features like ChkTeX for LaTeX linting and latexmk for compilation.
  • The article promotes the idea of using Docker containers for development as a way to ensure reproducibility and ease of setup across different environments.

Three Ways to Create Dockernized LaTeX Environment

Getting Started with LeTeX + Docker + VSCode Remote Container

Image by Stefan Keller from Pixabay
Table of Contents
Introduction
1. Setup
2. Method 1: tianon/latex
3. Method 2: Remote-Containers
4. Method 3: Creating your container
5. How to switch Remote containers
6. Opening a PDF
Conclusion

Introduction

We can run a Docker application in any environment, Linux, Windows, or Mac. Docker provides a set of official base images for the most used operating systems and apps. Docker allows you to take full control of your environment, installing what you need, removing, and installing from Dockerfile.

In this article, I will show you three ways how to use LaTeX on Docker and VSCode Remote Containers extension. In the first part, we use tianon/latex image and qmcgaw/latexdevcontainer Docker image in the second part. In the end, we create our image based on the qmcgaw/latexdevcontainer Docker image.

Setup

If you wish, you can delete LaTeX from your computer.

For me I needed to run:

$ brew uninstall mactex

Please install Docker Desktop and VSCode’s Remote-Containers and LaTeX-Workshop VSCode extension.

VSCode extension Microsoft Remote — Containers. Image by Author
VSCode extension LaTeX Workshop. Image by Author

Method 1: tianon/latex

Pull tianon/latex image:

$ docker pull tianon/latex

Open settings.json by SHIFT+CMD+P:

VSCode SHIFT+CMD+P. Image by Author.

And add the following:

{
    // ... YOUR OTHER SETTINGS ...
    // latex
    "latex-workshop.docker.enabled": true,
    "latex-workshop.latex.outDir": "./out",
    "latex-workshop.synctex.afterBuild.enabled": true,
    "latex-workshop.view.pdf.viewer": "tab",
    "latex-workshop.docker.image.latex": "tianon/latex",
    // End
  }

Create a tex file and enter the following:

\documentclass{article}
\begin{document}
An Example for a very \tiny{tiny} \normalsize \LaTeX \ document.
\end{document}

You can build a LaTeX file either by clicking the build icon or using OPTION+CMD+B on Mac.

Clicking the build icon. Image by Author.

After that whenever you save a file, it will automatically update the PDF.

On saving the file will be updated. Image by Author.

Now you are running LaTeX on Docker.

Method 2: Remote-Containers

The Visual Studio Code Remote — Containers extension lets you use a Docker container as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code’s full feature set. A devcontainer.json file in your project tells VS Code how to access (or create) a development container with a well-defined tool and runtime stack. — from Developing inside a Container

In your directory, create .devcontainer/devcontainer.json and add the following:

{
    "name": "project-dev",
    "dockerComposeFile": ["docker-compose.yml"],
    "service": "vscode",
    "runServices": ["vscode"],
    "shutdownAction": "stopCompose",
    "workspaceFolder": "/workspace",
    "postCreateCommand": "",
    "extensions": [
        "james-yu.latex-workshop",
        // Git
        "eamodio.gitlens",
        // Other helpers
        "shardulm94.trailing-spaces",
        "stkb.rewrap", // rewrap comments after n characters on one line
        // Other
        "vscode-icons-team.vscode-icons",
    ],
    "settings": {
        // General settings
        "files.eol": "\n",
        // Latex settings
        "latex-workshop.chktex.enabled": true,
        "latex-workshop.latex.clean.subfolder.enabled": true,
        "latex-workshop.latex.autoClean.run": "onBuilt",
        "editor.formatOnSave": true,
        "files.associations": {
            "*.tex": "latex"
        },
        "latex-workshop.latexindent.args": [
            "-c",
            "%DIR%/",
            "%TMPFILE%",
            "-y=\"defaultIndent: '%INDENT%',onlyOneBackUp: 1\"",
        ]
    }
}

In the setting, we enable listing LaTeX with ChkTeX, deleting LaTeX auxiliary files recursively in sub-folders, and we delete LaTeX auxiliary files on built.

If you wish, you can see more setting in VSCode > Preferences > Settings > Extensions > LaTeX.

VSCode Settings for LaTeX. Image by Author

Create .devcontainer/docker-compose.yml and add the following:

version: "3.7"
services:
  vscode:
    image: qmcgaw/latexdevcontainer
    volumes:
      - ../:/workspace
      - ~/.ssh:/home/vscode/.ssh:ro
      - ~/.ssh:/root/.ssh:ro
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp:unconfined
    entrypoint: zsh -c "while sleep 1000; do :; done"

We use qmcgaw/latexdevcontainer as the image. It uses texlive 2020 basic scheme and latexmk for LaTeX compilation to PDF. It formats on save using latexindent and uses chktex for LaTeX linting.

You have the following structure:

Directory structure. Image by Author

Click the green icon at the left-bottom, or open the command palette in Visual Studio Code (CMD/CTRL+SHIFT+P), and select Remote-Containers: Open Folder in Container... and choose your project.

The green Remote Container icon. Image by Author
Selecting Remote-Containers: Open Folder in Container … Image by Author

It will pull the Docker image, in this case qmcgaw/latexdevcontainer, and run a container behind the scene.

Results from docker images, docker ps -a. Image by Author

Once it is done, you will see “Dev Container” at the bottom left in VSCode.

Dev Container display at the bottom left. Image by Author

If you need to install LaTeX packages you can use tlmgr in the VSCode terminal:

$/workspace tlmgr update --self
$/workspace sudo apk add xz
$/workspace tlmgr install lastpage
$/workspace texhash
Terminal commands in the container. Image by Author

Create a simple tex file:

\documentclass{article} 
\usepackage{lastpage}
\begin{document}
An Example document.
\[
 \frac{4}{12}
\]
\end{document}

And when you save it, it will create a PDF file.

Saving a tex file create a PDF file. Image by Author

Method 3: Creating your container

qmcgaw/latexdevcontainer is a great starting point to create your Dockerfile and install all packages in your image. Here is an example.

Create a new directory and a Dockerfile in it:

FROM qmcgaw/latexdevcontainer
ARG USERNAME=vscode
USER root
RUN tlmgr update --self && \
    tlmgr install latexindent latexmk && \
    tlmgr install mathexam setspace adjustbox xkeyval collectbox enumitem lastpage && \
    texhash
USER ${USERNAME}

This will update tlmgr and install all packages I need. We can add any LaTeX packages using tlmgr install ....

We build an image from this Dockerfile.

$ docker build -t shinokada/latexexam .

I am running this command from the same directory I have the Docker file.

Let’s check the image we just created.

$ docker images
REPOSITORY                 TAG                 IMAGE ID            CREATED             SIZE
shinokada/latexexam        latest              7035f718823c        32 seconds ago      401MB
qmcgaw/latexdevcontainer   latest              85b911aaea3e        3 weeks ago         382MB

It has 19 MB more than qmcgaw/latexdevcontainer.

You can push to Docker Hub so that you can use it in the future and share it with others.

$ docker login
...
$ docker push shinokada/latexexam
...

We will update .devcontainer/docker-compose.yml file so that VSCode uses our new Docker image.

version: "3.7"
services:
  vscode:
    image: shinokada/latexexam
    volumes:
      - ../:/workspace
      - ~/.ssh:/home/vscode/.ssh:ro
      - ~/.ssh:/root/.ssh:ro
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp:unconfined
    entrypoint: zsh -c "while sleep 1000; do :; done"

The only difference is image: shinokada/latexexam.

Let’s update .devcontainer/devcontainer.json. We are going to output PDF to the /out directory. We use the same file as before and add a line:

...
"settings": {
        // General settings
        "files.eol": "\n",
        // Latex settings
        "latex-workshop.chktex.enabled": true,
        "latex-workshop.latex.outDir": "./out",
        ...

Let’s create a sample tex file called percent.tex.

Your directory structure is like this:

Directory structure. Image by Author

Then select “Open Folder in Container” as we did before. It will start Dev Container.

Save the percent.tex file and see a PDF is created in the out directory.

out directory. Image by Author
A created PDF. Image by Author

How to switch Remote containers

When you change files in .devcontainer directory, you need to rebuild a container. Select “Remote-Containers: Rebuild Container”.

Use Remote-Containers: Rebuild Container when you switch to another container. Image by Author

If the above method doesn’t work, you may need to select “Remote-Containers: Reopen Locally” first then select “Remote-Containers: Open Folder in Container”.

Opening a PDF

You can view a tex file in the VSCode tab or web browser. Please note you need to do it from a tex file. If you try to open it from another type of file, it won’t work.

LaTeX Workshop View LaTeX PDF menu. Image by Author

Conclusion

The size of qmcgaw/latexdevcontainer is 382MB and it is much smaller than tianon/latex. You can customize your image by creating your Dockerfile and using the FROM instruction to specify the parent image from which you are building.

Even though the file size of tianon/latex is big, the advantage of using it is that you don’t need to install packages. It already has most of the standard packages.

Comparing image size. Image by Author

Get full access to every story on Medium by becoming a member.

https://blog.codewithshin.com/subscribe

References

Docker
Latex
Programming
Math
Vscode
Recommended from ReadMedium