Server Pro: Sandboxed Compiles
Overleaf Server Pro 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.
For toolkit based setups, please refer to the dedicated documentation page on Sandboxed Compiles in the toolkit.
In this 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_SIBLING_CONTAINERS
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
IMPORTANT: starting with Overleaf CE/Server Pro 5.0.1
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:latest
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
SYNCTEX_BIN_HOST_PATH: "/data/overleaf_data/bin" #### IMPORTANT
Server Pro uses three environment variables to determine which texlive 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 the Server Pro instance starts up, it will 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 environment
section of the docker-compose file.
Here's an example where we default to texlive 2018 for new projects, and keep both 2018 and 2017 in use for older projects:
TEX_LIVE_DOCKER_IMAGE: "quay.io/sharelatex/texlive-full:2018.1"
ALL_TEX_LIVE_DOCKER_IMAGES: "quay.io/sharelatex/texlive-full:2018.1,quay.io/sharelatex/texlive-full:2017.1"
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: "TeX Live 2018.1,TeX Live 2017.1"
Before updating to a newer version of TexLive we strongly recommend backing up your data and update to the latest version of Server Pro available.
These are all the TexLive images that can be added to TEX_LIVE_DOCKER_IMAGE
and ALL_TEX_LIVE_DOCKER_IMAGES
:
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)
It's possible to extend an existing TexLive image using a new Dockerfile and configure the application to use the new image.
Here we offer some guidelines to install new packages or fonts, but the configuration of a custom image is not covered by our support terms.
The TeXLive images receive infrequent updates. We suggest rebuilding custom images when upgrading Server Pro.
You can use tlmgr
commands such as tlmgr install
and tlmgr update
to manage TexLive packages as in the following example:
FROM quay.io/sharelatex/texlive-full:2023.1
RUN tlmgr update --force ebproof
By default tlmgr
downloads resources from the latest TeXLive release. When patching an older TeXLive image, the downloads need to be switched to the respective archive. See the list in https://www.tug.org/historic/ for mirrors of archives.
FROM quay.io/sharelatex/texlive-full:2022.1
RUN tlmgr option repository <MIRROR>/systems/texlive/<YEAR>/tlnet-final
# e.g. RUN tlmgr option repository ftp://tug.org/historic/systems/texlive/2022/tlnet-final
RUN tlmgr update --force ebproof
There are different procedures to install new fonts in a TexLive distribution, and installing a custom font might require several steps. Checking the instructions to install TeX fonts in the official TexLive documentation is probably a good starting point.
The following Dockerfile
shows an example of installing a TrueType font over an existing TexLive 2022 image:
FROM quay.io/sharelatex/texlive-full:2022.1
COPY ./myfonts/*.ttf /usr/share/fonts/truetype/myfont/
# rebuild font information cache
RUN fc-cache
Use the name quay.io/sharelatex/texlive-full
and a custom tag to build the new image, as in:
docker build -t quay.io/sharelatex/texlive-full:2023.1-custom
We can now configure Server Pro to use the new 2023.1-custom
image updating the TEX_LIVE_DOCKER_IMAGE
and ALL_TEX_LIVE_DOCKER_IMAGES
environment variables:
TEX_LIVE_DOCKER_IMAGE: "quay.io/sharelatex/texlive-full:2023.1-custom"
ALL_TEX_LIVE_DOCKER_IMAGES: "quay.io/sharelatex/texlive-full:2023.1,quay.io/sharelatex/texlive-full:2023.1-custom"
In the example above new projects are set by default to use the new 2023.1-custom
image, while 2023.1
is still available for when it's needed.
⚠️ Warning: previous versions of Server Pro supported a docker-in-Docker setup for Sandboxed Compiles. This is no longer supported starting at v2.0. Original instructions to setup docker-in-docker are available here
Running Docker inside Docker can be hard to set up, and in many cases simply can't be made to work well. For those situations, we use instead Sandboxed Compiles with "Sibling Containers" instead of the a docker-in-docker setup. (From version 0.5.11 onwards)
With Sibling Containers, the Overleaf container doesn't start the compiler containers inside of itself, instead it communicates with the Host docker instance to spawn the compilers on the Host, alongside of itself.
To make this work we need to do a few things:
- Update the required environment variables
- Mount the host docker socket into the Overleaf container
- Mapping the host compile directory
- Mapping the location of synctex in the host
Notably, the privileged
flag is not required when using sibling containers.
Set the environment variables DOCKER_RUNNER
, SANDBOXED_COMPILES
and SANDBOXED_COMPILES_SIBLING_CONTAINERS
to true
.
Example:
--env DOCKER_RUNNER='true'
--env SANDBOXED_COMPILES='true'
--env SANDBOXED_COMPILES_SIBLING_CONTAINERS='true'
This point is only relevant to Server Pro v1.x. Starting with Server Pro 2.0.0 fiddling with group and user permissions is not needed.
We need to mount the host docker socket (usually /var/run/docker.sock
) into the Overleaf container.
In this example, note the addition of an extra -v
option with /var/run/docker.sock:/var/run/docker.sock
.
docker run -d \
-v ~/sharelatex_data:/var/lib/sharelatex \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 5000:80 \
--name=sharelatex \
quay.io/sharelatex/sharelatex-pro
It is important that the docker socket is owned by a group with the group id of 999
to match the group id used inside of the Overleaf container.
Check the group, in this case docker
> ls -l /var/run/docker.sock
srw-rw---- 1 root docker 0 May 31 08:57 /var/run/docker.sock
See the groupid of the docker group is 999
> getent group docker
docker:x:999:
If you are using the example docker-compose file, there is a commented-out example of this mount under the volumes
section.
The Overleaf container writes its data to a directory which is mounted from the host. For this example, let's say that this mount is /data/overleaf_data:/var/lib/overleaf
(mounted to /var/lib/sharelatex
for versions 4.x
and earlier).
Within that directory, there will be a data/compiles
directory. Because the compiler containers will be spawned on the Host (not inside the Overleaf container), we need to specify the full path to that directory on the host:
--env SANDBOXED_COMPILES_HOST_DIR='/data/overleaf_data/data/compiles'
⚠️ Warning: If you're running Server Pro2.0.1
or2.0.2
please follow these instructions instead: Fixing-SyncTeX errors in Server Pro 2.0.0 and 2.0.1
Overleaf automatically places synctex
executable in the correct location in the host, so it can be then mounted inside the compiler container. This location must be provided by SYNCTEX_BIN_HOST_PATH
environment variable, and should point to the bin/synctex
file inside the directory mounted from the host.
Let's say that the volume mount definition is /data/overleaf_data:/var/lib/overleaf
, then the value of the property should be:
--env SYNCTEX_BIN_HOST_PATH='/data/overleaf_data/bin/synctex'
- Quickstart Guide (Overleaf Toolkit)
- Hardware Requirements
- Database & Dependencies
- Creating and managing users
- General configuration
- Configuring Email
- SSL & Nginx reverse proxy
- Data and Backups
- Configuring Headers, Footers & Logo
- Password Restrictions
- i18n Languages
- Logging
- Common Config Options
- F.A.Q
- Troubleshooting
- Full Project History Migration