About

These are some notes on running Overleaf (a self-hosted latex on-line collaborative tool) using docker containers.

The Minefield

Here is a list of problems that have to be tackled in order to get everything working:

docker depends on mongodb and the last version of mongodb that supports CPUs without AVX extensions is 4.4.6,
similarly, due to the inter-dependency with mongodb, the Overleaf version that works with the mongodb at 4.4.6 is the Overleaf version 3.5.13,
when the Overleaf docker container starts, the container sets up some paths, that can be volume-mounted, by changing the permissions and ownership of the folders in the paths; unfortunately, unless there is full permission to the paths, the Overleaf initialization script will set a non-zero error status and then the whole container will terminate,
the community edition of Overleaf does not contain a full TeXLive distribution, such that TeXLive will have to be downloaded manually by entering a shell inside the container; then the modified image has to be saved to a different image in order to persist the TeXLive download,
Overleaf does not support having a base URL, so any reverse-proxying will have to use a whole (sub-)domain,
Overleaf crashes on initial start after creating an account if history is not turned off

The Images

This section stores the docker compose files to create the images necessary for running Overleaf on docker.

Mongo

ersion: '3.9'

services:
    mongo:
      image: mongo:4.4.6
      healthcheck:
        test: echo 'db.stats().ok' | mongo localhost:27017/test --quiet
        interval: 10s
        timeout: 10s
        retries: 5
      user: 1000:1000
      volumes:
        - /mnt/docker/data/mongo/db:/data/db
        - /mnt/docker/data/mongo/configdb:/data/configdb
        - /mnt/docker/data/mongo/init:/docker-entrypoint-initdb.d/:ro
      ports:
        - 27017:27017
      environment:
        - PUID=1000
        - PGID=1000
        - TZ=Etc/UTC
        - MONGO_INITDB_ROOT_USERNAME=root
        - MONGO_INITDB_ROOT_PASSWORD=password

The host /mnt/docker/data/mongo/init folder that is mapped inside the docker container as read-only at /docker-entrypoint-initdb.d/ contains a file name init.js with the following contents:

db = db.getSiblingDB('admin');
// move to the admin db - always created in Mongo
db.auth("root", "password");
// log as root admin if you decided to authenticate in your docker-compose file...
db = db.getSiblingDB('overleaf');
// create and move to your new database
db.createUser({
'user': "overleaf",
'pwd': "overleaf",
'roles': [{
    'role': 'dbOwner',
    'db': 'overleaf'}]});
// user created
//db.createCollection('collection_test');
// add new collection

that is placed there in order to pre-create the overleaf database referenced in the monogdb connector within the overleaf docker compose file.

Redis

version: '3.9'

services:
    redis:
      image: library/redis:latest
      deploy:
        resources:
          limits:
            memory: 256M
            cpus: '0.75'
          reservations:
            memory: 50M
      healthcheck:
        test: ["CMD-SHELL", "redis-cli ping || exit 1"]
      user: 1000:1000
      ports:
        - 6379:6379
      volumes:
        - /mnt/docker/data/redis/data:/data
        - /mnt/docker/data/redis/config:/usr/local/etc/redis
      environment:
        - PUID=1000
        - PGID=1000
        - TZ=Etc/UTC

Overleaf

After mongo and redis have been installed, setting Overleaf up is little more complicated given that the container itself has a complex setup. The first step is to run the container as per the following docker compose definition whilst changing the necessary environment variables to match.

# after starting, run inside the container: 
#   # in order to set the email to an admin
#   cd /var/www/sharelatex; grunt user:create-admin --email=yourownemail
#   # in order to install the full TeXLive distribution
#   tlmgr option repository https://ftp.math.utah.edu/pub/tex/historic/systems/texlive/2022/tlnet-final
#   tlmgr install scheme-full
version: '3.9'

services:
    overleaf:
      image: sharelatex/sharelatex:3.5.13
      healthcheck:
        test: curl -f http://localhost:80/ || exit 1
      ports:
        - 7643:80
      stop_grace_period: 60s
      volumes:
        - /mnt/docker/data/overleaf:/var/lib/sharelatex
      environment:
        - SHARELATEX_FPH_DISPLAY_NEW_PROJECTS=false
        - SHARELATEX_FPH_INITIALIZE_NEW_PROJECTS=false
        - SHARELATEX_SECURE_COOKIE=false
        - SHARELATEX_BEHIND_PROXY=true
        - SHARELATEX_APP_NAME="Overleaf Community Edition"
        - SHARELATEX_MONGO_URL=mongodb://overleaf:overleaf@docker/overleaf
        - SHARELATEX_REDIS_HOST=docker
        - REDIS_HOST=docker
        - ENABLE_CONVERSIONS=true
        - EMAIL_CONFIRMATION_DISABLED=false
        - SHARELATEX_ADMIN_EMAIL=your@email.com
        - TEXMFVAR=/var/lib/sharelatex/tmp/texmf-var
        - SHARELATEX_SITE_URL=https://latex...
        - SHARELATEX_NAV_TITLE=OverleafCE
        - SHARELATEX_EMAIL_SMTP_HOST=smtp.gmail.com
        - SHARELATEX_EMAIL_SMTP_PORT=587
        - SHARELATEX_EMAIL_SMTP_USER=your@email.com
        - SHARELATEX_EMAIL_SMTP_PASS=dfelecwkuldjffxfehd
        - SHARELATEX_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
        - SHARELATEX_EMAIL_SMTP_IGNORE_TLS=false
        - SHARELATEX_EMAIL_FROM_ADDRESS=your@email.com
        - SHARELATEX_EMAIL_SMTP_LOGGER=true
        - TZ=Etc/UTC

Note that Overleaf has to be able to set ownership and permissions for the local folder /mnt/docker/data/overleaf that is mounted within the container at /var/lib/sharelatex which might be a problem depending on the setup. For example, if /mnt/docker/data/overleaf is to be found on an NFS share, then the NFS share should be defined using no_root_squash in order to make sure that the chown command will work. Here is how one would export /mnt/docker/data/overleaf using NFS:

/mnt/docker/data/overleaf     docker1(rw,sync,insecure,no_subtree_check,no_root_squash)

The typical Overleaf showstopper consists in permission errors. Fortunately, the Overleaf docker container can be monitored by issuing:

docker logs OVERLEAF_CONTAINER --follow

where:

OVERLEAF_CONTAINER is the name of ID of the Overleaf container

Similarly, one very useful source of information is to start a shell within the docker container:

docker exec -it OVERLEAF_CONTAINER bash

where:

OVERLEAF_CONTAINER is the container ID of the Overleaf container

and then look under /var/log/sharelatex, specifically, inside the files:

/var/log/sharelatex/web.log, responsible for web-based interactions, and,
/var/log/sharelatex/clsi.log, responsible for compiling latex files

In case Overleaf manages to start and you are able to connect to the web-interface, then the E-Mail that has been used to create an account has to be set as an administrator. This can be done by issuing the command:

cd /var/www/sharelatex; grunt user:create-admin --email=yourownemail

where:

yourownemail is the E-Mail address referenced in the docker compose file environment variables

Now, the next part involves installing the full LaTeX TeXLive distribution, similarly, by entering the container shell and issuing the commands:

tlmgr option repository https://ftp.math.utah.edu/pub/tex/historic/systems/texlive/2022/tlnet-final
tlmgr install scheme-full

where:

the first command is necessary to switch to the UTAH TeXLive distribution mirror because it container TeXLive 2022 which is the version required to run Overleaf at version 3.5.13,
the second command will pull all the packages from the TeXLive mirror

Finally, the image is now complete and can be used such that it is best to create a separate image with the changes committed.

First, list all containers:

docker container ls

then commit the container to a separate image:

docker commit CONTAINER_ID IMAGE_NAME

where:

CONTAINER_ID is the container id of the Overleaf container,
IMAGE_NAME is the new image name to save the modified image as (ex: overleaf:latexfull)

From now on, the Overleaf compose file can be changed, and instead of:

      image: sharelatex/sharelatex:3.5.13

the new image can be used:

      image: overleaf:latexfull

Although it is out of the scope of this tutorial, in case that Overleaf will be running in a swarm, it is best to deploy a private registry to save the modified image such that it can be retrieved by the swarm.

Generating Google Application Passwords

For the environment section within the Overleaf docker compose file, namely, the definitions that define and outbound E-Mail:

        - SHARELATEX_EMAIL_SMTP_HOST=smtp.gmail.com
        - SHARELATEX_EMAIL_SMTP_PORT=587
        - SHARELATEX_EMAIL_SMTP_USER=your@email.com
        - SHARELATEX_EMAIL_SMTP_PASS=dfelecwkuldjffxfehd
        - SHARELATEX_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
        - SHARELATEX_EMAIL_SMTP_IGNORE_TLS=false
        - SHARELATEX_EMAIL_FROM_ADDRESS=your@email.com
        - SHARELATEX_EMAIL_SMTP_LOGGER=true

use Google via SMTP. For this to work, the "Security" section of the Google account has to be visited, two-factor authentication (2FA) must be enabled and then by clinking on the "Two-factor Authentication" and scrolling down, a section should be provided to create an application password.

The application password created should be set as the value of the SHARELATEX_EMAIL_SMTP_PASS environment variable:

        - SHARELATEX_EMAIL_SMTP_PASS=dfelecwkuldjffxfehd

Table of Contents

About

The Minefield

The Images

Mongo

Redis

Overleaf

Generating Google Application Passwords