|
|
|
|
@@ -1,10 +1,10 @@
|
|
|
|
|
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.
|
|
|
|
|
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`:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
```bash
|
|
|
|
|
SERVER_PRO=true
|
|
|
|
|
SIBLING_CONTAINERS_ENABLED=true
|
|
|
|
|
```
|
|
|
|
|
@@ -23,54 +23,181 @@ In the following example, note the following:
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
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"
|
|
|
|
|
...
|
|
|
|
|
...
|
|
|
|
|
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 TexLive Image
|
|
|
|
|
## 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`.
|
|
|
|
|
- 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 (e.g., `latest-full`).
|
|
|
|
|
- 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.
|
|
|
|
|
- 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 their project in the project menu.
|
|
|
|
|
Users can select the image for a project in the project menu.
|
|
|
|
|
|
|
|
|
|
Here is an example where the default TeX Live image is `latest-full` from Docker Hub, but the `TL2024-historic` image can be used for older projects:
|
|
|
|
|
```
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For additional details refer to
|
|
|
|
|
[Server Pro: Sandboxed Compiles](https://github.com/overleaf/overleaf/wiki/Server-Pro:-sandboxed-compiles).
|
|
|
|
|
## 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`:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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:
|
|
|
|
|
```bash
|
|
|
|
|
# Dry run (default): no real changes are applied
|
|
|
|
|
docker exec -i mongo mongosh --quiet < migrate-texlive-image-names.js
|
|
|
|
|
|
|
|
|
|
# Apply real changes
|
|
|
|
|
docker exec -i -e DRY_RUN=false mongo mongosh --quiet < migrate-texlive-image-names.js
|
|
|
|
|
```
|
|
|
|
|
By default, the script runs in dry-run mode.
|
|
|
|
|
Actual changes are applied only when `DRY_RUN=false` is explicitly set.
|
|
|
|
|
|
|
|
|
|
The `migrate-texlive-image-names.js` script can be as follows:
|
|
|
|
|
```javascript
|
|
|
|
|
(() => {
|
|
|
|
|
var dryRun = true
|
|
|
|
|
|
|
|
|
|
try {
|
|
|
|
|
if (typeof process !== 'undefined' && process.env.DRY_RUN !== undefined) {
|
|
|
|
|
dryRun = process.env.DRY_RUN === 'false' ? false : true
|
|
|
|
|
}
|
|
|
|
|
} catch (e) {
|
|
|
|
|
dryRun = true
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
const dbx = db.getSiblingDB('sharelatex')
|
|
|
|
|
|
|
|
|
|
function stripPath(name) {
|
|
|
|
|
if (!name || typeof name !== 'string') return ''
|
|
|
|
|
const parts = name.split('/')
|
|
|
|
|
return parts[parts.length - 1]
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
const collections = ['projects', 'templates']
|
|
|
|
|
|
|
|
|
|
for (const collName of collections) {
|
|
|
|
|
const coll = dbx.getCollection(collName)
|
|
|
|
|
const cursor = coll.find({ imageName: { $regex: '/' } })
|
|
|
|
|
|
|
|
|
|
print('\nProcessing collection: ' + collName)
|
|
|
|
|
|
|
|
|
|
let count = 0
|
|
|
|
|
cursor.forEach(doc => {
|
|
|
|
|
const oldName = doc.imageName || ''
|
|
|
|
|
const newName = stripPath(oldName)
|
|
|
|
|
|
|
|
|
|
if (oldName && newName && oldName !== newName) {
|
|
|
|
|
count++
|
|
|
|
|
if (dryRun) {
|
|
|
|
|
print('_id: ' + doc._id + ', old: ' + oldName + ', new: ' + newName)
|
|
|
|
|
} else {
|
|
|
|
|
coll.updateOne(
|
|
|
|
|
{ _id: doc._id },
|
|
|
|
|
{ $set: { imageName: newName } }
|
|
|
|
|
)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
print(
|
|
|
|
|
'Total entries ' +
|
|
|
|
|
(dryRun ? 'to be changed' : 'changed') +
|
|
|
|
|
' in ' +
|
|
|
|
|
collName +
|
|
|
|
|
': ' +
|
|
|
|
|
count
|
|
|
|
|
)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
print(
|
|
|
|
|
dryRun
|
|
|
|
|
? '\nDry-run complete. No changes made. Set DRY_RUN=false to apply updates.'
|
|
|
|
|
: '\nUpdate complete.'
|
|
|
|
|
)
|
|
|
|
|
})()
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```diff
|
|
|
|
|
--- 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`
|
|
|
|
|
- A list of extra flags for TeX compiler.
|
|
|
|
|
Example: `-shell-escape -file-line-error`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For additional details refer to
|
|
|
|
|
[Server Pro: Sandboxed Compiles](https://github.com/overleaf/overleaf/wiki/Server-Pro:-sandboxed-compiles).
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary><h4>Sample variables.env file for Overleaf Toolkit</h4></summary>
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
```bash
|
|
|
|
|
OVERLEAF_APP_NAME="Our Overleaf Instance"
|
|
|
|
|
|
|
|
|
|
ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url
|
|
|
|
|
@@ -116,9 +243,10 @@ NAV_HIDE_POWERED_BY=true
|
|
|
|
|
## Sandboxed Compiles ##
|
|
|
|
|
########################
|
|
|
|
|
|
|
|
|
|
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full, texlive/texlive:TL2024-historic
|
|
|
|
|
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/texlive:TL2024-historic
|
|
|
|
|
TEX_LIVE_DOCKER_IMAGE=texlive:TL2024-historic
|
|
|
|
|
TEX_COMPILER_EXTRA_FLAGS=-shell-escape
|
|
|
|
|
```
|
|
|
|
|
</details>
|
|
|
|
|
|
yu-i-i