raabf/texstudio-versions repository overview

🐋📓 DockerTeX ➕ 🐋📽 DockerTeXstudio

🏬 Dockerhub:

📓raabf/latex-versions	📱raabf/latex-versions-arm🆕	📽raabf/texstudio-versions

Both images are automatically rebuilt on Dockerhub when the Debian or Ubuntu base images change (they do on average each once per month).

📵 ARM variants: Docker does not provide free builds on dockerhub any more, so I need an new infrastructure and hence the ARM variants are currently not building.

📑️ Table of Contents

• 🏆 Features
• 🏷 Supported tags
• 🖱 Usage
  • 📓 dockertex
  • 📽 dockertexstudio
• 🪠 TexStudio Display Troubleshooting
• 🛠 Installation
  • 👔 zsh plugin manager
    • zplug
  • ⛓ Automated script
  • 🔨 Manual
• 🎈 Continuous Integration (CI)
  • GitLab CI
• 💡 Contributing

🏆 Features

• 💯 The only latex docker which provides different texlive versions — all from 2012 onwards!
• 🐧 Uses Linux Debian and Ubuntu as backend.
• 🏙 Complete latex package (texlive-full), which includes every latex module you normally need.
• 📽 TeXstudio⁠ GUI can be started in all containers.
• 🏭 Common tools used with latex are pre-installed: biber, make, gnuplot, inkscape, pandoc, python-pygments.
• ⬛ Easy and short shell commands to build your document in the docker container (see “Usage” section).
• 🎎 Preserves your ownership (user and group ID) of all your files which get pushed or created by the docker container.
• 👷 Easy installation via script or shell plugin-manager.
• 🗃 Menu entries for TeXstudio of all installed texlive versions.
• 🖥 The TexStudio GUI runs directly on your local X-server via shared sockets (no ssh X-forwarding or something like that). Please see Troubleshooting on problems.
• 📍 The TexStudio’s “Go to PDF” and ‘’Go to Source Code” are working as well as the LanguageTool⁠ integration.
• 🦫 Supports also Podman⁠ instead of docker CLI.

🏷 Supported tags

To specify your texlive version you can either use the texlive tag (texlive2012, texlive2013, …) or use the distribution codenames (wheezy, trusty, …)

📓texlive	🏷docker-tag	📀distro	🏷docker-tag	🐳Dockerfile and info for 📓Latex, 📱Latex-ARM,and 📽TeXstudio	📋Notes
v2012	texlive2012	Debian	wheezy		EOL²; last TeXstudio¹: 2.12.10-2
v2013	texlive2013	Ubuntu	trusty		EOL²; last TeXstudio¹: 2.12.14-1
v2014	texlive2014 armhf-texlive2014	Debian	jessie armhf-jessie		EOL²; last TeXstudio¹: 2.12.14-1
v2015	texlive2015 armhf-texlive2015 arm64-texlive2015	Ubuntu	xenial armhf-xenial arm64-xenial		EOL²; last TeXstudio¹: 2.12.22-1
v2016	texlive2016 armhf-texlive2016 arm64-texlive2016	Debian	stretch armhf-stretch arm64-stretch		last TeXstudio¹: 3.1.2
v2017	texlive2017 armhf-texlive2017 arm64-texlive2017	Ubuntu	bionic armhf-bionic arm64-bionic
v2018	texlive2018 armhf-texlive2018 arm64-texlive2018	Debian	buster armhf-buster arm64-buster
v2019	texlive2019 armhf-texlive2019 arm64-texlive2019	Ubuntu	focal armhf-focal arm64-focal
v2020	texlive2020	Debian	bullseye
v2021	texlive2021	Ubuntu	jammy
v2022	texlive2022	Debian	bookworm		in development

¹ TeXstudio does not provide builds for this Linux distribution version any more. The container is build with the last available TeXstudio version.

² The distribution release reached End Of Life, so there aren’t any updates any more. However, the docker image should still work.

🖱 Usage

Either docker CLI⁠ or Podman⁠ are required to run the container. You can either use the dockertexstudio images or – if you never need TeXstudio – just the dockertex images. The dockertexstudio images include all features of the dockertex images. dockertex will automatically use the dockertexstudio images when installed on the local system, so that not twice as much disk space is occupied on your computer. dockertex and dockertexstudio will promt you to pull the docker images when necessary.

Fonts The images contain debian’s non-free repository and ubuntu’s multiverse. Beside the default latex fonts, Liberation and MSCoreFonts are installed. Liberation are a free replacement for the MSCoreFonts. If you still use the MSCoreFonts you accept their EULA⁠.

📓 dockertex

Let's assume you are in a direcory with your latex file called document.tex, then for example just run:

dockertex --tag texlive2016 pdftex document.tex

The general syntax is:

dockertex [-t|--tag tagname] command

dockertex run the docker container with the tag tagname and mounts the current working directory pwd as a volume and just executes command in this mount point. Furthermore, the script makes sure that all files (changed and newly generated files) preserve their ownership (user and group ID) of the user executing dockertex.

command can be arbitrary and is not limit to tex commands, for example if you use a Makefile:

dockertex --tag jessie make all

Default Tag To set a default Tag so that --tag is optional, set the environment variable:

export DOCKERTEX_DEFAULT_TAG="texlive2016"

Engine To run the container, select an executable within your PATH. It defaults to podman when it is installed, else docker. Specify it with:

export DOCKERTEX_ENGINE="podman"
export DOCKERTEX_ENGINE="docker"

📽 dockertexstudio

dockertexstudio is a tool to start TexStudio⁠ GUI inside a specified docker container. The usage of the tag is the same as dockertex:

 dockertexstudio [-t|--tag tagname] [-v|--volume mapping]* [texstudio options]

dockertexstudio always mounts your home directory ~ as volume in the container. If you need additional mount points, use --volume, which has the same syntax as in docker run. For example:

dockertexstudio --tag texlive2016  --volume /media/git/:/home/git/

The configuration of TexStudio in the containers and among the containers is preserved between runs of the docker containers. Execute dockertexstudio --help to display the local path of the configuration folder.

Menu Entries The menu entries generated during the Installation process will also make use of dockertexstudio. In your file manager, you can even open .tex files directly with TexStudio inside the container. Just assign .tex files to the appropriate menu entry. But be careful, direct opening only works if the full file path inside and outside the container, is the same — this is the case for the per default mounted home directory.

Go to Because TeXstudio is running inside the docker container, the “Go to PDF” and ‘’Go to Source Code” functions via synctex are working.

LanguageToolLanguageTool⁠ is an advanced tool for grammar checking. It can be accessed via its HTTP API. dockertexstudio shares its network interface with the host system, so you can lunch LanguageTool on your host’s localhost interface (which is the default configuration for LanguageTool, so just start it normally) and dockertexstudio will be able to access it.

x11docker The image basically also works with x11docker⁠, just call for example

x11docker --network=host --share $HOME raabf/texstudio-versions:texlive2019

You might want that because of its security features, or because it works better for you.

🪠 TexStudio Display Troubleshooting

Authorization required

When using docker and you get

Authorization required, but no authorization protocol specified

you need to run

xhost local:root

on your host. The problem is that docker runs all container as root, who is by default not allowed to access XServer of your local running user. However, the xhost command can allow that.

Further Authentication

If he still wants more authentication, you might need to pass a token generated by xauth list from the host to the guest, so that the guest can connect to the XServer on the host. I did not tested that yet, see here⁠.

DISPLAY variable

If he complains that the Display is not found, you might have to replace in the dockertexstudio.sh script --env='DISPLAY' with -e DISPLAY=unix$DISPLAY. This might be environment specific and I do not know the conditions for that.

Remove Network

A user reported⁠ that it helps to remove the shared network by removing the line --network=host in dockertexstudio.sh. However, TexStudio then cannot access network resources like Laguagetool.

x11docker

You might try x11docker⁠ instead of dockertexstudio.sh, which can setup GUI apps in containers. For example, you can call

x11docker --network=host --share $HOME raabf/texstudio-versions:texlive2019

More resources

In this issue⁠ you find some more hints and links, which might have solutions.

🛠 Installation

👔 zsh plugin manager

The most comfortable method to install it, is with a zsh plugin-manager. This approach has the big advantage that dockertex CLI will be updated together with your other plugins.

The script /posthook.sh can install a menu entry into your desktop environment. The mandatory option --menu-tag allows to specify a docker tag for the menu entry. For mounting additional volumes, use the --menu-volume option—the syntax is the same as in docker run, except that you have to replace : with = because zplug does not allow a : in a string. Use ./posthook.sh …; ./posthook.sh … multiple times for installing multiple menu entries for different tags.

Please consult the built-in help if you want to find out what the default installation paths are or to change those.

curl https://gitlab.com/raabf/dockertex/raw/master/posthook.sh | bash -s -- --help

To install dockertex CLI, just add the repository to your plugin configuration in your ~/.zshrc. If you want to create a menu entries for TeXstudio, add ./posthook.sh to the hook-build. For example your configuration could look like:

zplug

zplug raabf/dockertex, \                                                                                                                                                    
    from:gitlab, \                                                                                                                                                          
    hook-build:"./posthook.sh --menu-tag latest --menu-volume /media/ext/=/home/ext/"

It should work also with any other plugin manager. If you have tested it with other plugin managers and if you want to extend this list please tell me at the issues board⁠.

⛓ Automated script

If you do not have zsh, you can install the dockertex CLI and the TeXstudio menu entries through an install script.

The mandatory option --menu-tag allows to install a menu entry into your desktop environment. For mounting additional volumes, use the --menu-volume option—the syntax is the same as in docker run. Just execute the script multiple times if want to have multiple menu entries with different tags.

Just run install.sh with:

curl https://gitlab.com/raabf/dockertex/raw/master/install.sh | bash -s -- --menu-tag latest --menu-volume "/media/ext/:/home/ext/"

or to install it system wide

curl https://gitlab.com/raabf/dockertex/raw/master/install.sh | bash -s -- --system --menu-tag latest --menu-volume /media/ext/:/home/ext/"

Just leave out the --menu-tag and --menu-volume options if you do not want to create any menu entry.

If you neither want to install the texstudio script nor the menu entries, use the --no-texstudio option.

curl https://gitlab.com/raabf/dockertex/raw/master/install.sh | bash -s -- --no-texstudio

Please consult the built-in help if you want to find out what the default installation paths are or to change those.

curl https://gitlab.com/raabf/dockertex/raw/master/install.sh | bash -s -- --help

🔨 Manual

Copy the scripts from bin/ to a folder in your PATH such as /usr/local/bin/:

sudo cp bin/dockertex.sh /usr/local/bin/dockertex; sudo cp bin/dockertexstudio.sh /usr/local/bin/dockertexstudio

Make sure that the files have the executable bit set

chmod a+x /usr/local/bin/dockertex*

Copy TeXstudio icon to an arbitrary place:

cp misc/icons/hicolor/scalable/apps/texstudio.svg /usr/local/share/icons/hicolor/scalable/apps/texstudio.svg

Use the template misc/dockertexstudio.desktop to create one or multiple menu entry:

cp misc/dockertexstudio.desktop /usr/local/share/applications/dockertexstudio-stretch.desktop 

Then append the missing fields:

echo "Name=Docker TexStudio (stretch)                                                                                                                  
Exec=/usr/local/bin/dockertexstudio --tag latest %F                      
Icon=/usr/local/share/icons/hicolor/scalable/apps/texstudio.svg" >> /usr/local/share/applications/dockertexstudio-stretch.desktop

🎈 Continuous Integration (CI)

The latex images are working well for automatically build your output PDF in a Continuous Integration (CI) system.

GitLab CI

First you have to register a runner⁠ at one of your servers with installed docker. The only important thing is that you choose docker as executor. The given image is just a default docker image which can be overwritten later in the project config.

sudo gitlab-runner register --url https://gitlab.com/ --executor "docker" --tag-list "docker, latex, dockertex" --docker-image "raabf/latex-versions:latest"

Then add the CI configuration file .gitlab-ci.yml to your git root. Use the following one as a template:

---
stages:
  - latex

before_script:
  - lsb_release --all
  - latex --version

make_texlive2016:
  image: raabf/latex-versions:texlive2016
  stage: latex
  tags:
    - docker
  script:
    - make all
  artifacts:
    paths:
      - ./thesis.pdf
    expire_in: 1 week


# test your latex file on multiple versions

make_texlive2017:
  image: raabf/latex-versions:texlive2017
  stage: latex
  tags:
    - docker
  script:
    - make all
  artifacts:
    paths:
      - ./thesis.pdf
    expire_in: 1 week

make_texlive2015:
  image: raabf/latex-versions:texlive2015
  stage: latex
  tags:
    - docker
  script:
    - make all
  artifacts:
    paths:
      - ./thesis.pdf
    expire_in: 1 week

In this example thesis.pdf is your output. The artifact section will upload the specified file at the CI’s Web-Interface and make it even available for viewing and downloading!

Did you test it with other CI systems and want to extend this list of examples? Please tell me at the issues board⁠.

💡 Contributing

This project aims to be a generalized latex environment for the majority of latex projects. If something is missing or not working, then I’m happy for any contribution. You can find the repository⁠ and issues board⁠ at GitLab.