Skip to main content
Sandboxed compiles work a little differently in the dev environment than in the production image. The dev environment already has them set up; this page explains the settings and three things to keep in mind:
  • File Permission Problem
  • Volume Share Between history-v1 and filestore
  • Subdirectories Problem

Enable Sandbox Compiles

Sandboxed compiles are on by default. develop/docker-compose.yml sets SANDBOXED_COMPILES=true for clsi, and develop/dev.env holds the rest:
develop/dev.env
clsi does not pull images itself, so pull the images once with docker pull ghcr.io/ayaka-notes/texlive-full:2026.1 (and :2025.1). LaTeX runs in the sibling containers as TEXLIVE_IMAGE_USER. In the dev environment this is tex, which is also clsi’s default (services/clsi/config/settings.defaults.cjs:154). The production image uses www-data instead when SANDBOXED_COMPILES_SIBLING_CONTAINERS=true (server-ce/config/env.sh:15-21), because there the files are created by the www-data user of the Overleaf container.
Please don’t use your self-built image, you may encounter a series of errors.

Fix File Permissions

The clsi container starts as root, gives the compiles, output and cache folders to the node user (uid 1000) and then runs clsi as node (services/clsi/entrypoint.sh). So develop/compiles on the host belongs to uid 1000, the same uid as tex in the dev setup (see the comment in develop/pandoc/Dockerfile). With the settings above, the dev environment compiles without any permission change. If you set TEXLIVE_IMAGE_USER=root instead, root (uid 0) has no permission to write to the subfolders of compiles. In that case, give the root group ownership and write permission to compiles, with setgid set so that new subfolders inherit this ownership:
bash
For detailed document, you can see services/clsi/README.md.

Volume Share Between history-v1 and filestore

The settings in this section and the next one are already in develop/docker-compose.yml and develop/dev.env. They only matter with S3_ENABLED=false in develop/dev.rc. With the default S3_ENABLED=true, filestore and history-v1 keep these files in RustFS buckets instead (develop/s3/docker-compose.yml).
By default, filestore act as a bridge between s3 and other services in overleaf. However, in overleaf ce or server pro, all files are stored locally by default. So, overleaf introduced a very tricky method.
server-ce/config/settings.js
And in the meantime, data/history is also used by history service. In this way, they can share the same data between different micro service. That is why the filestore service in develop mounts the history-v1-buckets volume of history-v1. Without it, clsi will not be able to pull blob files from filestore service.
develop/docker-compose.yml
filestore finds the buckets through these settings in dev.env:
develop/dev.env

Use Subdirectories

filestore always reads history blobs with subdirectories (services/filestore/app/js/KeyBuilder.js:58, :70). The production image turns useSubdirectories on for history-v1 (server-ce/config/production.json), but the default config of history-v1 does not, so in development history-v1 would flatten all the data. dev.env therefore sets NODE_CONFIG for history-v1:
develop/dev.env
Without it, history-v1 stores the project_blobs files like this:
With useSubdirectories set to true, the _ in these names becomes /, so each blob is stored in subfolders.
Last modified on November 13, 2026