# 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. {% hint style="danger" %} 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 and environment variables) when running LaTeX compiles. {% endhint %} ## 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. {% hint style="info" %} 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. {% endhint %} 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](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/templates#transferring-templates-from-overleaf.com) guide. {% hint style="info" %} 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. {% endhint %} ## 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 {% hint style="danger" %} Starting with Overleaf CE/Server Pro `5.0.3` environment variables have been rebranded from `SHARELATEX_*` to `OVERLEAF_*`. {% endhint %} 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`) {% code overflow="wrap" %} ```yaml 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: "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 ``` {% endcode %} ## 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: {% code overflow="wrap" %} ``` 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" ``` {% endcode %} ## 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:2025.1` * `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` (legacy) * `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](https://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` {% hint style="danger" %} 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. {% endhint %} * Set `SIBLING_CONTAINERS_PULL=false` in `config/overleaf.rc` * Recreate the `sharelatex` container using `bin/up -d` {% hint style="warning" %} 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). {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/server-pro-only-configuration/sandboxed-compiles.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.