Extended CE: Sandboxed Compiles - yu-i-i/overleaf-cep GitHub Wiki

Overleaf Extended CE 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

To enable sandboxed compiles (also known as "Sibling containers"), set the following configuration options in overleaf-toolkit/config/overleaf.rc:

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

For additional details refer to Toolkit: Sandboxed Compiles.

docker-compose

In the following 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_HOST_DIR set to /data/overleaf_data/data/compiles, the place on the host where the compile data will be written
services:
  sharelatex:
    ...
    volumes:
      - /data/overleaf_data:/var/lib/overleaf
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      ...
      DOCKER_RUNNER: "true"
      SANDBOXED_COMPILES: "true"
      SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
      ...
    ...

Changing the TeX Live Image

The following environment variables are used to specify which TeX Live images to use for sandboxed compiles:

  • ALL_TEX_LIVE_DOCKER_IMAGES (required)
    • A comma-separated list of TeX Live images to use. If the Overleaf Toolkit is used for deployment, these images will be downloaded or updated.
    • To skip downloading, set SIBLING_CONTAINERS_PULL=false in config/overleaf.rc.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES
    • A comma-separated list of friendly names for the images. If omitted, the version name will be used (for example, latest-full).
  • TEX_LIVE_DOCKER_IMAGE
    • The default TeX Live image used for compiling new projects.
    • This image must be included in ALL_TEX_LIVE_DOCKER_IMAGES.
    • If not set, the first image in ALL_TEX_LIVE_DOCKER_IMAGES will be used as the default image.

Users can select the image for a project in the project menu.

Below is an example configuration where the default TeX Live image is latest-full from Docker Hub, but the TL2024-historic image can be used for older projects:

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full, texlive/texlive:TL2024-historic
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLive 2025, TeXLive 2024
TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full

Defining the docker image repository

Starting with v6.1.0-ext-v3.5, an additional environment variable is supported:

  • TEX_LIVE_DOCKER_IMAGE_ROOT
    • Defines the docker image repository (namespace) from which TeX Live images are resolved.

When this variable is set, values specified in ALL_TEX_LIVE_DOCKER_IMAGES and TEX_LIVE_DOCKER_IMAGE are expected not to include a repository prefix. The full Docker image reference is constructed internally as <TEX_LIVE_DOCKER_IMAGE_ROOT>/<image>.

Equivalent configuration to the above, using TEX_LIVE_DOCKER_IMAGE_ROOT:

TEX_LIVE_DOCKER_IMAGE_ROOT=texlive
ALL_TEX_LIVE_DOCKER_IMAGES=texlive:latest-full, texlive:TL2024-historic
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLive 2025, TeXLive 2024
TEX_LIVE_DOCKER_IMAGE=texlive:latest-full

The TeX Live image used for project compilation and for templates is stored in MongoDB. When TEX_LIVE_DOCKER_IMAGE_ROOT is defined, MongoDB records are expected to store only the image name and tag, without the repository prefix, that is texlive:latest-full instead of texlive/texlive:latest-full.

This allows administrators to change the Docker image repository (for example, to use alternative TeX Live images) without modifying existing projects or templates. If an existing installation already stores full image names in MongoDB and TEX_LIVE_DOCKER_IMAGE_ROOT is enabled, the database must be migrated accordingly.

Migration can be performed with:

./overleaf-toolkit/bin/run-script modules/server-ce-scripts/scripts/strip-image-repo-prefix.mjs

The script runs in dry-run mode by default and prints the changes that would be applied. Add the --no-dry-run option to perform the actual changes.

If an administrator later decides to return to the variant with full image paths and removes TEX_LIVE_DOCKER_IMAGE_ROOT, the imageName fields in MongoDB records must again include the repository prefix. This can be done with:

./overleaf-toolkit/bin/run-script modules/server-ce-scripts/scripts/add-image-repo-prefix.mjs --prefix=texlive

The --prefix option specifies the repository prefix to add (for example, texlive). The script runs in dry-run mode by default; add --no-dry-run to apply the changes.

If overleaf-toolkit is used to pull and update TeX Live images (SIBLING_CONTAINERS_PULL=true), an additional change is required when TEX_LIVE_DOCKER_IMAGE_ROOT is set. The file overleaf-toolkit/bin/up must be updated as follows:

--- a/bin/up
+++ b/bin/up
@@ -62,7 +62,9 @@ function pull_sandboxed_compiles() {
     exit 1
   fi
   echo "Pulling TeX Live images..."
+  local image_root=$(read_variable "TEX_LIVE_DOCKER_IMAGE_ROOT")
   for image in ${images//,/ }; do
+    [[ -n "$image_root" ]] && image="$image_root/$image"
     echo "  - $image download started (may take some time)"
     docker pull $image
     echo "  - $image download finished"

Enabling external commands during compilation

When the compilation takes place in a dedicated container, it is relatively safe to permit running external commands from inside the TeX file during compilation. This is required for packages like minted. For this purpose, the following environment variable can be used:

  • TEX_COMPILER_EXTRA_FLAGS
    • A list of extra flags for TeX compiler. Example: -shell-escape -file-line-error

Note on migration from Overleaf CE

In projects created with Overleaf CE, the image name is not stored in MongoDB project records. When a user opens such a project in Overleaf CE+ for the first time, the imageName field is initialized with the default image.

If an administrator later decides to return to Overleaf CE, these records can optionally be removed. Open mongosh with:

./overleaf-toolkit/bin/mongo

Then remove the imageName field from all projects:

db.projects.updateMany({}, { $unset: { imageName: "" } })

For additional details refer to Server Pro: Sandboxed Compiles.

Sample variables.env file for Overleaf Toolkit

 
OVERLEAF_APP_NAME="Our Overleaf Instance"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# Enables Thumbnail generation using ImageMagick
ENABLE_CONVERSIONS=true

# Disables email confirmation requirement
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## Set for TLS via nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Our Overleaf Instance
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
[email protected]

OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:[email protected]"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "url":"https://github.com/yu-i-i/overleaf-cep"}]

[email protected]
OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
OVERLEAF_EMAIL_SMTP_PORT=587
OVERLEAF_EMAIL_SMTP_SECURE=false
# OVERLEAF_EMAIL_SMTP_USER=
# OVERLEAF_EMAIL_SMTP_PASS=
# OVERLEAF_EMAIL_SMTP_NAME=
OVERLEAF_EMAIL_SMTP_LOGGER=false
OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
OVERLEAF_CUSTOM_EMAIL_FOOTER=This system is run by department x

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

########################
## Sandboxed Compiles ##
########################

TEX_LIVE_DOCKER_IMAGE_ROOT=texlive
ALL_TEX_LIVE_DOCKER_IMAGES=texlive:latest-full, texlive:TL2024-historic
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLive 2025, TeXLive 2024
TEX_LIVE_DOCKER_IMAGE=texlive:TL2024-historic
TEX_COMPILER_EXTRA_FLAGS=-shell-escape
⚠️ **GitHub.com Fallback** ⚠️