Skip to content

Server Pro: Sandboxed Compiles

Jump to bottom
Jakob Ackermann edited this page May 28, 2024 · 38 revisions

Overleaf Server Pro comes with the option to run compiles in a secured sandbox environment for enterprise security. It does this by running every project in its own secured docker environment.

Toolkit

For toolkit based setups, please refer to the dedicated documentation page on Sandboxed Compiles in the toolkit.

docker-compose

In this example, note the following:

  • the docker socket volume mounted into the Overleaf container
  • DOCKER_RUNNER set to "true"
  • SANDBOXED_COMPILES set to "true"
  • SANDBOXED_COMPILES_SIBLING_CONTAINERS set to "true"
  • SANDBOXED_COMPILES_HOST_DIR set to "/data/overleaf_data/data/compiles", the place on the host where the compile data will be written

IMPORTANT: starting with Overleaf CE/Server Pro 5.0.1 environment variables have been rebranded from SHARELATEX_* to OVERLEAF_*.

If you're using a 4.x version (or earlier) please make sure the variables are prefix accordingly (e.g. SHARELATEX_MONGO_URL instead of OVERLEAF_MONGO_URL)

version: '2'
services:
    sharelatex:
        restart: always
        image: quay.io/sharelatex/sharelatex-pro:latest
        container_name: sharelatex
        depends_on:
            - mongo
            - redis
        ports:
            - 80:80
        links:
            - mongo
            - redis
        volumes:
            - /data/overleaf_data:/var/lib/overleaf # (/var/lib/sharelatex for versions 4.x and earlier)
            - /var/run/docker.sock:/var/run/docker.sock    #### IMPORTANT
        environment:
            OVERLEAF_MONGO_URL: mongodb://mongo/sharelatex
            OVERLEAF_REDIS_HOST: redis
            OVERLEAF_APP_NAME: 'My Overleaf'
            OVERLEAF_SITE_URL: "http://overleaf.mydomain.com"
            OVERLEAF_NAV_TITLE: "Our Overleaf Instance"
            OVERLEAF_ADMIN_EMAIL: "support@example.com"
            ...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_SIBLING_CONTAINERS: "true"    #### IMPORTANT
            # Note: (/var/lib/sharelatex for versions 4.x and earlier)
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"  #### IMPORTANT

Changing the TexLive Image

Server Pro uses three environment variables to determine which texlive images to use for sandboxed compiles:

  • TEX_LIVE_DOCKER_IMAGE: name of the default image for new projects
  • ALL_TEX_LIVE_DOCKER_IMAGES: comma-separated list of all images in use
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: Optional: comma-separated list of user-facing friendly names for the images. If omitted, the version number will be used, for example, texlive-full:2018.1

When the Server Pro instance starts up, it will pull all of the images listed in ALL_TEX_LIVE_DOCKER_IMAGES.

The current default is quay.io/sharelatex/texlive-full:2017.1, but you can override these values in the environment section of the docker-compose file.

Here's an example where we default to texlive 2018 for new projects, and keep both 2018 and 2017 in use for older projects:

    TEX_LIVE_DOCKER_IMAGE: "quay.io/sharelatex/texlive-full:2018.1"
    ALL_TEX_LIVE_DOCKER_IMAGES: "quay.io/sharelatex/texlive-full:2018.1,quay.io/sharelatex/texlive-full:2017.1"
    ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: "TeX Live 2018.1,TeX Live 2017.1"

Before updating to a newer version of TexLive we strongly recommend backing up your data and update to the latest version of Server Pro available.

Available TexLive Images

These are all the TexLive images that can be added to TEX_LIVE_DOCKER_IMAGE and ALL_TEX_LIVE_DOCKER_IMAGES:

  • quay.io/sharelatex/texlive-full:2023.1
  • quay.io/sharelatex/texlive-full:2022.1
  • quay.io/sharelatex/texlive-full:2021.1
  • quay.io/sharelatex/texlive-full:2020.1 (legacy)
  • quay.io/sharelatex/texlive-full:2019.1 (legacy)
  • quay.io/sharelatex/texlive-full:2018.1 (legacy)
  • quay.io/sharelatex/texlive-full:2017.1 (legacy)
  • quay.io/sharelatex/texlive-full:2016.1 (legacy)
  • quay.io/sharelatex/texlive-full:2015.1 (legacy)
  • quay.io/sharelatex/texlive-full:2014.2 (legacy)

Extending TexLive

It's possible to extend an existing TexLive image using a new Dockerfile and configure the application to use the new image.

Here we offer some guidelines to install new packages or fonts, but the configuration of a custom image is not covered by our support terms.

The TeXLive images receive infrequent updates. We suggest rebuilding custom images when upgrading Server Pro.

Installing and updating new packages

You can use tlmgr commands such as tlmgr install and tlmgr update to manage TexLive packages as in the following example:

FROM quay.io/sharelatex/texlive-full:2023.1

RUN tlmgr update --force ebproof

Using tlmgr in an older TeXLive image

By default tlmgr downloads resources from the latest TeXLive release. When patching an older TeXLive image, the downloads need to be switched to the respective archive. See the list in https://www.tug.org/historic/ for mirrors of archives.

FROM quay.io/sharelatex/texlive-full:2022.1

RUN tlmgr option repository <MIRROR>/systems/texlive/<YEAR>/tlnet-final
# e.g. RUN tlmgr option repository ftp://tug.org/historic/systems/texlive/2022/tlnet-final

RUN tlmgr update --force ebproof

Installing new fonts

There are different procedures to install new fonts in a TexLive distribution, and installing a custom font might require several steps. Checking the instructions to install TeX fonts in the official TexLive documentation is probably a good starting point.

The following Dockerfile shows an example of installing a TrueType font over an existing TexLive 2022 image:

FROM quay.io/sharelatex/texlive-full:2022.1

COPY ./myfonts/*.ttf /usr/share/fonts/truetype/myfont/

# rebuild font information cache
RUN fc-cache

Configuring Server Pro to use the new images

Use the name quay.io/sharelatex/texlive-full and a custom tag to build the new image, as in:

docker build -t quay.io/sharelatex/texlive-full:2023.1-custom

We can now configure Server Pro to use the new 2023.1-custom image updating the TEX_LIVE_DOCKER_IMAGE and ALL_TEX_LIVE_DOCKER_IMAGES environment variables:

TEX_LIVE_DOCKER_IMAGE: "quay.io/sharelatex/texlive-full:2023.1-custom"
ALL_TEX_LIVE_DOCKER_IMAGES: "quay.io/sharelatex/texlive-full:2023.1,quay.io/sharelatex/texlive-full:2023.1-custom"

In the example above new projects are set by default to use the new 2023.1-custom image, while 2023.1 is still available for when it's needed.

Setup & Managing Overleaf

Server Pro

Legacy

Clone this wiki locally