Sandboxed Compiles

Server Pro comes with the option to run compiles in a secured sandbox environment for enterprise security achieving sandbox isolation between projects. It does this by running every project in its own secured Docker environment. With Sandboxed Compiles you also benefit from easier package management via access to our customized TeX Live images.

Improved security

Sandboxed Compiles are the recommended approach for Server Pro due to many LaTeX documents requiring/having the ability to execute arbitrary shell commands as part of the PDF compile process. If you use Sandboxed Compiles, each compile runs in a separate Docker container with limited capabilities that are not shared with any other user or project and has no access to outside resources such as the host network.

If you attempt to run Server Pro without Sandboxed Compiles, the compile runs alongside other concurrent compiles inside the main Docker container and users have full read and write access to the sharelatex container resources (filesystem, network, environment variables) when running LaTeX compiles.

Sandboxed Compiles are not available in Community Edition, which is intended for use in environments where all users are trusted. Community Edition is not appropriate for scenarios where isolation of users is required.

Easier package management

To avoid manually installing packages, we recommend enabling Sandboxed Compiles. This is a configurable setting within Server Pro that will provide your users with access to the same Tex Live environment as that on overleaf.com but within your own on-premise installation. TeX Live images used by Sandboxed Compiles contain the most popular packages and fonts tested against our gallery templates, ensuring maximum compatibility with on-premise projects.

Enabling Sandboxed Compiles allows you to configure which TeX Live versions users are able to choose from within their project along with setting a default TeX Live image version for new projects.

If you attempt to run Server Pro without Sandboxed Compiles, your instance will default to using a basic scheme version of TeX Live for compiles. This basic version is lightweight and only contains a very limited subset of LaTeX packages, which will most likely result in missing package errors for your users, especially if they try to use pre-built templates.

As Server Pro has been architected to work offline, there isn't an automated way to integrate overleaf.com gallery templates into your on-premise installation, it is, however, possible to do this manually on a per-template basis. For more information on how this works, please check out our transferring templates from overleaf.com guide.

Sandboxed Compiles requires that the sharelatex container has access to the Docker socket on the host machine (via a bind mount) so it can manage these sibling compile containers.

How it works

When Sandboxed Compiles are enabled, the Docker socket will be mounted from the host machine into the sharelatex container, so that the compiler service in the container can create new Docker containers on the host. Then for each run of the compiler in each project, the LaTeX compiler service (CLSI) will do the following:

• Write out the project files to a location inside the OVERLEAF_DATA_PATH,

• Use the mounted Docker socket to create a new texlive container for the compile run

• Have the texlive container read the project data from the location under OVERLEAF_DATA_PATH

• Compile the project inside the texlive container

Enabling Sandboxed Compiles

In config/overleaf.rc, set SIBLING_CONTAINERS_ENABLED=true, and ensure that the DOCKER_SOCKET_PATH setting is set to the location of the Docker socket on the host machine.

The next time you start the Docker services (with bin/up), the Toolkit will verify that it can communicate with Docker on the host machine, and will pull all configured TeX Live images set by the ALL_TEX_LIVE_DOCKER_IMAGES environment variable in the config/variables.env file.

Docker Compose Example

Starting with Overleaf CE/Server Pro 5.0.3 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:5.0.3
        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: "[e-mail]"
            ...
            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 TeX Live Image

Server Pro uses three environment variables to determine which TeX Live 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 starting your Server Pro instance using the bin/up command, the Toolkit will automatically 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 config/variables.env if you are using the Toolkit or the environment section of the docker-compose.yml file if you are using Docker Compose.

Here's an example where we default to TeX Live 2024 for new projects, and keep both 2023 and 2022 in use for existing projects:

    TEX_LIVE_DOCKER_IMAGE: "quay.io/sharelatex/texlive-full:2024.1"
    ALL_TEX_LIVE_DOCKER_IMAGES: "quay.io/sharelatex/texlive-full:2024.1,quay.io/sharelatex/texlive-full:2023.1,quay.io/sharelatex/texlive-full:2022.1"
    ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: "TeX Live 2024.1,TeX Live 2023.1,TeX Live 2022.1"

Available TeX Live images

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

• quay.io/sharelatex/texlive-full:2024.1

• 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)

Using your own image registry

As Server Pro has been architected to work offline, it may not always be possible to reach the quay.io registry to pull TeX Live images. If you need to use your own image registry you can use the following steps:

• Set the TEX_LIVE_IMAGE_NAME_OVERRIDE environment variable in config/variables.env to the name of the mirror. For example: your-image-repository/sharelatex (be careful not to include a trailing /)

• Ensure that all TeX Live images that are set in ALL_TEX_LIVE_DOCKER_IMAGES, are pulled, correctly tagged (see note below) are then pushed to your mirror. For example:

  • docker pull quay.io/sharelatex/texlive-full:2024.1

  • docker tag quay.io/sharelatex/texlive-full:2024.1 your-image-repository/sharelatex/texlive-full:2024.1

  • docker push your-image-repository/sharelatex/texlive-full:2024.1

Both the TEX_LIVE_DOCKER_IMAGE and ALL_TEX_LIVE_DOCKER_IMAGES environment variables must still be set to use quay.io/sharelatex images — the value set in the TEX_LIVE_IMAGE_NAME_OVERRIDE environment variable will replace the quay.io/sharelatex component of the image name at compile time.

• Set SIBLING_CONTAINERS_PULL=false in config/overleaf.rc

• Recreate the sharelatex container using bin/up -d

There is a strict schema concerning how images must be tagged (the following regex applies ^[0-9]+.[0-9]+, for which the first number determines the TeX Live year and the second the patch version).