Community Edition Feature Request: only sanbox-compile, no local texlive (with Source Code)

[davrot]

My friends CoPilot, Raptor Mini and myself wrote worked on the clsi service.

(Licence: GNU AFFERO GENERAL PUBLIC LICENSE Version 3)
I don't have the time to submit it through the regular PR process. If someone could adopt it: Thanks!

The goal was to remove the local & incomplete TexLive installation and switch to docker based compile. This is necessary since latex packages like minted need latex shell escape. And you shouldn't allow this without isolating the latex compile process from the rest of the server.

In addition, I tried to simplified the docker settings side of things. The goal was to have default settings that allow to use sandbox compile out of the box. Well, we succeeded mainly. Only the docker env parameter OVERLEAF_HOST_DATA_DIR needs to be set.
Small rant: I was not able to fill the default of OVERLEAF_HOST_DATA_DIR with the /var/lib/overleaf mouting point. The information is there from inside the container:

CONTAINER_ID=$(hostname)
curl --unix-socket /var/run/docker.sock \
  ["http://localhost/containers/overleafserver/json"](http://localhost/containers/overleafserver/json) | python3 -m json.tool | grep -A 20 '"Mounts"'

Nevertheless, raptor mini did fought against it like hell.

Another point is that the overleaf server container will get the texLive images before it gets ready (i.e. healthy). Pre-pull the images or wait...

synctex works:

shell escape works (is allowed by default now):

MULTI-IMAGES:

    volumes:
    - /data_1/docker/compose_cep/overleafserver/data:/var/lib/overleaf
    - /var/run/docker.sock:/var/run/docker.sock

    environment:
      OVERLEAF_HOST_DATA_DIR: /data_1/docker/compose_cep/overleafserver/data
      ALL_TEX_LIVE_DOCKER_IMAGES: texlive/texlive:latest-full, texlive/texlive:TL2024-historic, texlive/texlive:TL2023-historic
      ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: TeXLive 2025, TeXLive 2024, TeXLive 2023

DEFAULT SETTING:

    volumes:
    - /data_1/docker/compose_cep/overleafserver/data:/var/lib/overleaf
    - /var/run/docker.sock:/var/run/docker.sock

    environment:
      OVERLEAF_HOST_DATA_DIR: /data_1/docker/compose_cep/overleafserver/data

Code
https://github.com/davrot/overleaf_with_admin_extension/tree/sandbox-compile

[davrot]

Sandbox Compile — Quick User Guide

This short guide explains the key Docker environment variables and configuration needed to enable and operate the Sandbox Compile feature (sibling-container Docker runner) in this repository. Sandboxed compiles run per-project builds inside separate Docker images for better isolation and reproducible TeXLive environments.

⚠️ Note: Sandboxed compiles require mounting the Docker socket into the sharelatex container, plus one or more host directories used for compile inputs and outputs. This introduces security implications — only enable in trusted environments.

---

Minimum Requirements

• Docker installed and available on the host.
• The Overleaf container must be run with the Docker socket mounted (recommended path: /var/run/docker.sock).
• Host directories must be created and bind-mounted (or provided via OVERLEAF_HOST_DATA_DIR):
  • SANDBOXED_COMPILES_HOST_DIR_COMPILES (required)
  • SANDBOXED_COMPILES_HOST_DIR_OUTPUT (recommended, used for synctex/output)

If SANDBOXED_COMPILES_HOST_DIR_COMPILES is missing, the clsi service will throw and fail to start.

---

Key Environment Variables (what they do)

• DOCKER_SOCKET_PATH (optional)

  • Default: /var/run/docker.sock
  • Path to the Docker socket inside the container; the container must have this socket mounted to run sibling containers.

• SANDBOXED_COMPILES_HOST_DIR_COMPILES (required)

  • The host directory path used to store project files for compilation (bind-mounted into the service container).
  • Example: /home/user/sharelatex_data/data/compiles
  • Must be readable and writable by the user inside the compile image (default www-data).

• SANDBOXED_COMPILES_HOST_DIR_OUTPUT (recommended)

  • Host path for compiled outputs (synctex / pdf outputs). Optional; helpful if you need to access outputs outside the container.
  • Example: /home/user/sharelatex_data/data/output

• ALL_TEX_LIVE_DOCKER_IMAGES (optional)

  • Comma-separated list of allowed TeX Live Docker images, e.g.:
    texlive/texlive:latest-full,texlive/texlive:2023.
  • When provided, the Service uses this list as the single source-of-truth for allowed compile images.

• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (optional)

  • Comma-separated list of human-readable names for the above images, intended for the UI (e.g., TeXLive Latest,TeXLive 2023).
  • If omitted, a default friendly name is used.

• TEX_LIVE_DOCKER_IMAGE (optional / default)

  • The default TeX Live Docker image used if a project doesn't pick a specific image.
  • Default: texlive/texlive:latest-full in dev.

• TEX_LIVE_IMAGE_USER (optional)

  • The user account inside the TeX Live image used to run latexmk, default www-data.
  • Ensure the host bind-mount directories are accessible/writable by this user, or adjust accordingly.

• TEX_LIVE_IMAGE_NAME_OVERRIDE (optional, CLIs)

  • If you use a private registry, set this to the registry path prefix (e.g., us-east1-docker.pkg.dev/overleaf-ops/ol-docker). The runner will prepend this value to the image name when pulling.

• TEX_COMPILER_EXTRA_FLAGS (optional, powerful)

  • Server-level flags merged into every compile request by default (e.g., -shell-escape); used to allow features like minted / pygmentize.
  • Default in dev/sandbox: -shell-escape.
  • Security: setting this globally enables shell-escape for every compile; using it in production is a security risk. Prefer per-request flags where possible.

• TEXLIVE_OPENOUT_ANY TEXLIVE_MAX_PRINT_LINE (optional, CLIs)

  • Additional CLIs-related TeXLive options. If needed, set them in the CLSI environment.

• COMPILE_GROUP_DOCKER_CONFIGS (optional, advanced)

  • JSON string with Docker host config overrides per compile group. Use to customize container CPU shares, memory limits or AutoRemove for helper containers.

• DOCKER_RUNTIME and DOCKER_SOCKET_PATH (optional)

  • DOCKER_RUNTIME lets you define a runtime environment, DOCKER_SOCKET_PATH sets the path to the Docker socket for sibling container invocations.

• AUTO_FALLBACK_TEXLIVE_IMAGE (optional, safe fallback)

• Default: true in production (and enabled in development by default). When true, the server startup check will automatically migrate any projects using images not present in ALL_TEX_LIVE_DOCKER_IMAGES to the current TEX_LIVE_DOCKER_IMAGE value.

• When set to true, the server startup check will automatically migrate any projects using images not present in ALL_TEX_LIVE_DOCKER_IMAGES to the current TEX_LIVE_DOCKER_IMAGE value.

• Use when you want the system to automatically recover from accidental removal of images from ALL_TEX_LIVE_DOCKER_IMAGES. The operation performs DB updates; ensure you have a backup and check resulting project behavior.

---

Quick Examples

Environment-based invocation (inline example):

ALL_TEX_LIVE_DOCKER_IMAGES="texlive/texlive:latest-full,texlive/texlive:2023" \
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES="TeXLive Latest,TeXLive 2023" \
TEX_LIVE_DOCKER_IMAGE="texlive/texlive:2023" \
SANDBOXED_COMPILES_HOST_DIR_COMPILES="/home/user/sharelatex_data/data/compiles" \
SANDBOXED_COMPILES_HOST_DIR_OUTPUT="/home/user/sharelatex_data/data/output" \
TEX_COMPILER_EXTRA_FLAGS="-shell-escape" \
DOCKER_SOCKET_PATH="/var/run/docker.sock" \
docker compose up -d

Docker Compose snippet (short example to paste into docker-compose.yml / service environment):

services:
  sharelatex:
    environment:
      DOCKER_SOCKET_PATH: '/var/run/docker.sock'
      ALL_TEX_LIVE_DOCKER_IMAGES: 'texlive/texlive:latest-full,texlive/texlive:2023'
      ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: 'TeXLive Latest,TeXLive 2023'
      TEX_LIVE_DOCKER_IMAGE: 'texlive/texlive:2023'
      TEX_LIVE_IMAGE_USER: 'www-data'
      TEX_COMPILER_EXTRA_FLAGS: '-shell-escape'
      SANDBOXED_COMPILES_HOST_DIR_COMPILES: '/home/user/sharelatex_data/data/compiles'
      SANDBOXED_COMPILES_HOST_DIR_OUTPUT: '/home/user/sharelatex_data/data/output'

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /home/user/sharelatex_data:/var/lib/overleaf

Pre-pull configured TexLive images (optional but recommended for production):

# Pull TexLive images defined in ALL_TEX_LIVE_DOCKER_IMAGES
./bin/pre-pull-texlive-images.sh

---

Tips & Troubleshooting

• Permission errors on compile host dir:
  • Ensure SANDBOXED_COMPILES_HOST_DIR_COMPILES and SANDBOXED_COMPILES_HOST_DIR_OUTPUT exist and are writable by TEX_LIVE_IMAGE_USER (default www-data), or chown them to that user:

sudo mkdir -p /home/user/sharelatex_data/data/{compiles,output}
sudo chown -R 33:33 /home/user/sharelatex_data/data/   # 33 typically maps to www-data

• Latexmk not being found (or minted failing due to pygmentize):

  • If you see "latexmk not found" or a need to pass -shell-escape, check TEX_LIVE_DOCKER_IMAGE and TEX_COMPILER_EXTRA_FLAGS variables. The system also supports using absolute latexmk paths for some images.

• Validate expected images are allowed: confirm ALL_TEX_LIVE_DOCKER_IMAGES lists every image you want to permit. The UI will display friendly names from ALL_TEX_LIVE_DOCKER_IMAGE_NAMES in the same order.

• Use a private registry: set TEX_LIVE_IMAGE_NAME_OVERRIDE to your registry host prefix to force image pulls from your registry.

• If CLIs cannot mount the host directory: set SANDBOXED_COMPILES_VALIDATE_HOST_DIR_VIA_DOCKER=true to run a container-based validation when the host path might not be visible by the service container.

---

Security Considerations

• Mounting the Docker socket inside a container is a privilege escalation vector (it grants the container the ability to spawn containers and access the Docker host). Only enable it in fully trusted environments or internal deployments.

• Global TEX_COMPILER_EXTRA_FLAGS='-shell-escape' enables shell escaping for LaTeX builds; this can be dangerous in multi-tenant or public environments. Where possible, prefer per-project flags, limit sandboxed compile features to trusted groups, and apply compile pool restrictions via ALLOWED_COMPILE_GROUPS and compile group configs.

---

Where to Look in the Repository

• server-ce/config/settings.js — server defaults & environment hooks for TEX_LIVE_DOCKER_IMAGE, TEX_COMPILER_EXTRA_FLAGS, ALL_TEX_LIVE_DOCKER_IMAGES.
• services/clsi/config/settings.defaults.js — CLIs-specific settings and texCompilerExtraFlags default.
• services/clsi/README.md — local CLSI setup and examples.
• bin/pre-pull-texlive-images.sh — helper script to pull the configured images on a host.
• docker-compose.yml — example toggles and environment variables used for sandboxed compiles.
• doc/sandboxed_compiles_ce.md — additional documentation and admin notes.

---

Quick Restart Steps

After editing environment variables or docker-compose.yml:

1. Pull the configured TexLive images (optional):

ALL_TEX_LIVE_DOCKER_IMAGES="texlive/texlive:2023,texlive/texlive:2024" ./bin/pre-pull-texlive-images.sh

2. Start/restart the containers to apply new environment variables:

# Recommended: restart the sharelatex container
docker compose down
docker compose up -d --remove-orphans

3. Verify the clsi and sharelatex logs for errors and that clsi acknowledges the allowed images list.

[davrot]

Docker container for testing this feature:
https://hub.docker.com/repository/docker/davrot/sharelatex/tags/sandbox-compile/sha256:8d4cb548e3a903eabdb89764be255dcf9a8543f9799222b32f834b4b02ceb4b9

[ayaka-lab]

For users who are running sandbox compile in overleaf CE, we highly recommend https://github.com/ayaka-notes/texlive-full

This docker image is specially designed and optimized for sandbox compile and has been verified to works well in our large school deployment. We provide all texlive full image from 2019-2025.

And also with full font contained. You can even compile R code like overleaf official website.

The only thing you need to mind is your server storage. Because each image will need more than 10GB storage.