Skip to content
/ LatexWorks Public

Docker Images that provide LaTeX TeX Live based on Fedora.

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE_APACHE-2.0
MIT
LICENSE_MIT
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

robinwalterfit/LatexWorks

BranchesTags

Repository files navigation

LatexWorks

Docker Images that provide LaTeX TeXLive based on Fedora.

Getting Started | GitHub

Conventional Commits License MIT or Apache-2.0 Contributor Covenant Docker lefthook Taskfile MegaLinter

Table of Contents

Getting Started

This project builds Docker Images that provide $\LaTeX$ TeX Live with different predefined packages. All images differentiate in the scheme that was installed from the fedora rpm repository.

Fedora is used as the base image, because it provides a recent TeX Live distribution without extra configuration necessary and the management and installation of $\LaTeX$ packages can be done via dnf, just like any other package installation.

If you want to install additional $\LaTeX$ packages with dnf, you can do this with the following command. This for example will install the beamer class and hyperref package.

sudo dnf install --assumeyes 'tex(beamer.cls)'
sudo dnf install --assumeyes 'tex(hyperref.sty)'

Prerequisites

To make use of these images you (of course) need Docker installed on your machine. You can find instructions on how to install Docker for your platform according the instructions from this link.

Docker is also necessary if you want to extend these images. Otherwise you will not be able to build the new images.

Installation

Currently, these images are not deployed anywhere (see Deployment for more information). This means you have to build an image yourself. Some guidance on how to achieve this will follow:

Download and Copy

The most obvious way would be to just download the Dockerfile and run the command from Build the Project. Keep in mind you have to download the docker-entrypoint.sh file as well. Otherwise you have to modify the Dockerfile.

Either use the download buttons from the GitHub web application or use e.g. curl.

curl --fail --location --remote-name 'https://raw.githubusercontent.com/robinwalterfit/LatexWorks/main/Dockerfile'
curl --fail --location --remote-name 'https://raw.githubusercontent.com/robinwalterfit/LatexWorks/main/docker-entrypoint.sh'

Git Submodule

An alternative way would be to add this repository as a git submodule. This way it will be easier to upgrade when a new release of this repository was published and you will keep in mind where to look for more information.

git submodule add --branch main https://github.com/robinwalterfit/LatexWorks.git

This will install the repository under a new subdirectory LatexWorks. You can then cd into this directory and run the command from Build the Project.

Usage

The image provides a custom entrypoint. In order to use the image, all you have to do is running docker run. Most likely you will want to use latexmk to compile your document. However, you must provide some arguments to the run command otherwise the compilation will not work. The only necessary arguments are the volume mount to mount your document sources into the container and the workspace directory. You should also provide information about your local user, otherwise the compiled document will belong to root.

Run the following command from the root of your project directory:

docker run --env PUID="$(id -u)" --env PGID="$(id -g)" --interactive --rm --tty --volume "${PWD}:/workspace" --workdir '/workspace' robinwalterfit/latexworks:<scheme>-<fedora-version>-<project-version> latexmk [options] [file ...]
# Or: use docker `--user` argument
docker run --interactive --rm --tty --user "$(id -u)" --volume "${PWD}:/workspace" --workdir '/workspace' robinwalterfit/latexworks:<scheme>-<fedora-version>-<project-version> latexmk [options] [file ...]

This will mount your project directory to /workspace and tell docker to use this directory as the workspace folder. The --rm flag tells docker to remove the container as soon as it has finished execution. The environment variables PUID and PGID will make sure to drop privileges as well as the --user option and that all commands in the container use the same user id as your local user. The flags --interactive and --tty are for interactive mode and to allocate a pseudo-TTY respectively. This is done, because latexmk works interactively by default. If you do not want to run interactively, you should use -interaction=nonstopmode option of latexmk.

If you make use of latexmkrc files, then you should make sure they can be found by latexmk. Either add a .latexmkrc file to the root of your project or provide them as an option to the command. But remember: all files not part of the project must be mounted into the container!

⬆️ Back to Top

Development

In order to extend the functionallity of the images you must follow the prerequisites to install Docker.

It is recommended to use Visual Studio Code as editor. The repository recommends different VSCode extensions, however, none of them are required. It is up to you what extensions you use.

There is only one Dockerfile that is used for all images.

Build the Project

All build commands follow this scheme:

docker buildx build \
    --build-arg CREATED=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
    --build-arg FEDORA_VERSION=40 \  # Optional
    --build-arg REVISION=$(git log -n 1 --format=%H) \
    --build-arg TEXLIVE=texlive-scheme-<scheme> \
    --build-arg VERSION=<project-version> \
    --target latexworks \  # Comes before the `devcontainer` stage, so make sure to add this target!
    --tag <user/org>/latexworks:<scheme>-<fedora-version>-<project-version> \
    [--tag ... ] \  # Additional tags may be provided
    .  # Context: CWD

There are some placeholders used in this command. Let us break this down:

  • <scheme>: The TeX Live distribution provides different installation schemes. The following schemes are available:
    • basic: This is the basic TeX Live scheme: it is a small set of files sufficient to typeset plain TeX or LaTeX documents in PostScript or PDF, using the Computer Modern fonts. This scheme corresponds to collection-basic and collection-latex.
    • context: This is the TeX Live scheme for installing ConTeXt.
    • full: This is the full TeX Live scheme: it installs everything available.
    • gust: This is the GUST TeX Live scheme: it is a set of files sufficient to typeset Polish plain TeX, LaTeX and ConTeXt documents in PostScript or PDF.
    • medium: This is the medium TeX Live collection: it contains plain TeX, LaTeX, many recommended packages, and support for most European languages.
    • minimal: This is the minimal TeX Live scheme, with support for only plain TeX. (No LaTeX macros.) LuaTeX is included because Lua scripts are used in TeX Live infrastructure. This scheme corresponds exactly to collection-basic.
    • small: This is a small TeX Live scheme, corresponding to MacTeX's BasicTeX variant. It adds XeTeX, MetaPost, various hyphenations, and some recommended packages to scheme-basic.
    • tetex: TeX Live scheme nearly equivalent to the teTeX distribution that was maintained by Thomas Esser.
  • <user/org>: The user or organization identifier.
  • <fedora-version>: The Fedora version of the base image. E.g. at the time of writing the most recent stable version available was 40.
  • <project-version>: This project itself uses SemVer as versioning scheme. This version should be added to the tag since there could be new releases while the Fedora and TeX Live versions stay the same.

NOTE: The images should be used as-is. No additional packages should be installed directly. Checkout customization for more information on how to install additional packages in smaller images.

However, task can be used to build the images, too. There are many different tasks that can be found in Taskfile.yml. To build a LatexWorks image just invoke one of the available tasks.

Deployment

Currently none of these images will be deployed to any public registry. Main reason for this is the size of the images. Even the minimal scheme image has a size of ~2GB. This will definitely exceed GitHub's Packages Quota.

However, this does not mean you cannot use this project. It simply implies a simple docker pull ... will not be enough. See the installation instructions for more information on how to use $\LaTeX$Works.

Customization

If a specific package is needed, that is not available in e.g. small, but using a bigger image with a different scheme is not desirable, then the installation should be done in the container. This however, is not persistent. To make it persistent, a new image should be created that uses the small image as its base image.

⬆️ Back to Top

Dev Container

The standard image is not optimized for the usage as a Dev Container. This is why an additional stage called devcontainer was introduced. The devcontainer stage uses the latexworks stage as its base layer. This way a dev container will inherit all functionality from the $\LaTeX$Works image, but also include everything necessary to create a dev container. One very important thing is the user mapping. Make note of the additional build arguments. Also make sure to put your code into /workspace inside the container.

docker buildx build \
    --build-arg CREATED=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
    --build-arg FEDORA_VERSION=40 \  # Optional
    --build-arg HADOLINT_VERSION=2.12.0 \  # Optional
    --build-arg LTEX_LS_VERSION=15.2.0 \  # Optional
    --build-arg PYENV_VERSION=2.3.24 \  # Optional
    --build-arg PYTHON_VERSION=3.10.6 \  # Optional
    --build-arg REVISION=$(git log -n 1 --format=%H) \
    --build-arg TEXLIVE=texlive-scheme-<scheme> \
    --build-arg USER_GID="$(id -g)" \
    --build-arg USER_UID="$(id -u)" \
    --build-arg USERNAME="$(id -un)" \
    --build-arg VERSION=<project-version> \
    --target devcontainer \  # Could be omitted
    --tag <user/org>/latexworks-devcontainer:<scheme>-<fedora-version>-<project-version> \
    [--tag ... ] \  # Additional tags may be provided
    .  # Context: CWD

There are tasks available to build a dev container image, too.

⬆️ Back to Top

Contributing

You want to contribute to $\LaTeX$Works? Great! Please make sure to read CONTRIBUTING.md first.

⬆️ Back to Top

Links

⬆️ Back to Top

Licenses

Code: © 2024 - Present - Robin Walter <hello@robinwalter.me>.

MIT or Apache-2.0 where applicable.

⬆️ Back to Top

About

Docker Images that provide LaTeX TeX Live based on Fedora.

Topics

docker productivity latex mit apache2

Resources

Readme

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE_APACHE-2.0
MIT
LICENSE_MIT

Code of conduct

Code of conduct
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 7

1.1.0 (2024-10-27) Latest
Oct 27, 2024
+ 6 releases

Languages