Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kjarosh/latex-docker
A set of lightweight Docker images for building LaTeX documents
https://github.com/kjarosh/latex-docker
docker docker-container dockerfile latex texlive
Last synced: 8 days ago
JSON representation
A set of lightweight Docker images for building LaTeX documents
- Host: GitHub
- URL: https://github.com/kjarosh/latex-docker
- Owner: kjarosh
- License: mit
- Created: 2021-03-10T22:20:37.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-09T17:16:29.000Z (about 2 months ago)
- Last Synced: 2024-09-09T21:52:11.685Z (about 2 months ago)
- Topics: docker, docker-container, dockerfile, latex, texlive
- Language: Makefile
- Homepage:
- Size: 43 KB
- Stars: 28
- Watchers: 2
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# LaTeX in Docker
[](https://github.com/kjarosh/latex-docker/blob/main/LICENSE)
[](https://github.com/kjarosh/latex-docker/actions)
[](https://github.com/kjarosh/latex-docker/releases)
[](https://hub.docker.com/r/kjarosh/latex)
[](https://github.com/users/kjarosh/packages/container/package/latex)
[](https://hub.docker.com/r/kjarosh/latex)
[](https://hub.docker.com/r/kjarosh/latex)
[](https://hub.docker.com/r/kjarosh/latex)
[](https://hub.docker.com/r/kjarosh/latex)
[](https://hub.docker.com/r/kjarosh/latex)
This repository defines a set of images which may be used
to run LaTeX in a container, for example in CI/CD.
They come in several flavors, which correspond to TeX Live schemes
(see the table below).
The default scheme is `full` which contains all packages.
If some package is missing you can always use `tlmgr` to install it.
The image is based on [`alpine`](https://alpinelinux.org/), so system packages
may be installed using `apk`.
| Scheme | Image | Size |
|---------|--------------------------------|---------|
| minimal | `kjarosh/latex:2024.4-minimal` | ~40 MB |
| basic | `kjarosh/latex:2024.4-basic` | ~90 MB |
| small | `kjarosh/latex:2024.4-small` | ~180 MB |
| medium | `kjarosh/latex:2024.4-medium` | ~500 MB |
| full | `kjarosh/latex:2024.4` | ~2 GB |
The images are made in such a way that they reuse layers.
For example `full` will add a layer to `medium` with packages that are
not present there.
This makes it easier to manage and saves space.
## Usage
If you're writing a CI/CD configuration, check out [CI/CD Examples](#cicd-examples)!
Assuming you want to quickly compile a file named `main.tex` in the current
directory to a PDF and place the output in `./out`:
```shell
docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" kjarosh/latex:2024.4 latexmk -pdf -outdir=out -auxdir=out/aux main.tex
```
If you want to work on your LaTeX project and see your changes live,
add `-pvc` at the end.
This will recompile the project automatically each time a source file changes.
If you want to use a different engine, use e.g. `-xelatex` for XeLaTeX
or `-lualatex` for LuaLaTeX.
Other useful options you may want to check out include e.g. `-c`, `-g`, or `-silent`.
See [latexmk documentation](https://ctan.gust.org.pl/tex-archive/support/latexmk/latexmk.pdf)
for detailed usage and options.
If you don't want to use `latexmk` you are free to issue any command you want
(`latex`, `pdflatex`, `xelatex`, etc.) and it should just work.
For more complex building processes, using a building tool such as `make` is advised.
In that case you'll need to install it by issuing `apk add make` inside the container.
## Versions
There are several types of versions described below.
*If you're unsure which version to use, use the latest stable version.*
### Stable Versions
Stable versions are in the format of `.` (e.g. `2022.1`).
The major version relates to TeX Live version (which is the year),
the minor version is the version of the image within the given year.
Stable versions offer image updates & fixes and include the
set of packages for the given TeX Live version at the time of release.
| TeX Live version | Latest stable version |
| ---------------- | --------------------- |
| 2024 | `2024.4` |
| 2023 | `2023.4` |
| 2022 | `2022.3` |
| 2021 | `2021.4` |
| 2020 | `2020.2` |
| 2019 | `2019.2` |
| 2018 | `2018.2` |
All stable versions are available on the [releases page](https://github.com/kjarosh/latex-docker/releases).
### Development Versions
If you want to use the newest TeX Live or visit an old release
from the past, you can use development versions.
Development versions are released automatically
every day and come in several formats:
1. `devel` — The lastest development build which uses the main TL mirror.
Using this version is **highly discouraged**, especially in CI/CD,
as in case a newer TeX Live release appears, `tlmgr` will not work.
2. `devel--` — A development version containing TeX Live
in version ``, based on a historic mirror from `` (so that `tlmgr` will work).
Usually these images are created once and not updated in the future.
3. `devel-` — The newest development build for the given TeX Live release.
When `` is the current TeX Live version, this image will
usually be newer than the latest stable release of ``.
However, when `` is not the current TeX Live version, the latest
stable release usually will contain maintenance fixes and base image updates.
4. `devel-any-` — A development version containing TeX Live from ``.
This is the same as `devel--`, but without `` in case
someone wants to use the TeX Live from `` without knowing ``.
## CI/CD Examples
### GitHub Actions
Example using `latexmk`:
```yaml
name: Compile LaTeX
on: [ push ]
jobs:
container:
runs-on: ubuntu-latest
container: kjarosh/latex:2024.4
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build using latexmk
run: latexmk -pdf -output-directory=out main.tex
- name: Upload document
uses: actions/upload-artifact@v4
with:
name: main-document
path: out/index.pdf
```
### GitLab CI/CD
Example using `latexmk`:
```yaml
build:
stage: build
image: kjarosh/latex:2024.4
script:
- latexmk -pdf -output-directory=out main.tex
artifacts:
paths:
- out/index.pdf
```