Working with Docker Compose Services

The Overleaf Toolkit runs Overleaf inside a docker container, plus the supporting databases (MongoDB and Redis), in their own containers. All of this is orchestrated with docker compose.

Note: for legacy reasons, the main Overleaf container is called sharelatex, and is based on the sharelatex/sharelatex docker image. This is because the technology is based on the ShareLaTeX code base, which was merged into Overleaf. See this blog post for more details. At some point in the future, this will be renamed to match the Overleaf naming scheme.

The bin/docker-compose Wrapper

The bin/docker-compose script is a wrapper around docker compose. It loads configuration from the config/ directory, before invoking docker compose with whatever arguments were passed to the script.

You can treat bin/docker-compose as a transparent wrapper for the docker compose program installed on your machine.

For example, we can check which containers are running with the following:

bin/docker-compose ps

Convenience Helpers

In addition to bin/docker-compose, the toolkit also provides a collection of convenient scripts to automate common tasks:

• bin/up: shortcut for bin/docker-compose up
• bin/start: shortcut for bin/docker-compose start
• bin/stop: shortcut for bin/docker-compose stop
• bin/shell: starts a shell inside the main container

Architecture

Inside the overleaf container, the Overleaf software runs as a set of micro-services, managed by runit. Some of the more interesting files inside the container are:

• /etc/service/: initialisation files for the microservices
• /etc/overleaf/settings.js: unified settings file for the microservices
• /var/log/overleaf/: logs for each microservice
• /var/www/overleaf/: code for the various microservices
• /var/lib/overleaf/: the mount-point for persistent data (corresponds to the directory indicated by OVERLEAF_DATA_PATH on the host)

Before Server Pro/Community Edition version 5.0, the paths used the ShareLaTeX brand.

The MongoDB and Redis Containers

Overleaf dedends on two external databases: MongoDB and Redis. By default, the toolkit will provision a container for each of these databases, in addition to the Overleaf container, for a total of three docker containers.

If you would prefer to connect to an existing MongoDB or Redis instance, you can do so by setting the appropriate settings in the overleaf.rc configuration file.

Viewing Individual Micro-Service Logs

The bin/logs script allows you to select individual log streams from inside the overleaf container. For example, if you want to see just the logs for the web and clsi (compiler) micro-services, run:

bin/logs -f web clsi

See the output of bin/logs --help for more options.

docker-compose.yml to Toolkit migration

If you're currently using Docker Compose via a docker-compose.yml file, migrating to the Toolkit can make running an on-premises version of Overleaf easier to deploy, upgrade and maintain.

To migrate, you'll need to convert your existing Docker Compose setup into the format used by the Toolkit. This process involves copying existing configuration into the Toolkit.

This guide will walk you through each step of this process, ensuring a smooth migration from Docker Compose to the Toolkit.

Note: These instructions are for v4.x and earlier. Therefore all variables use the SHARELATEX_ prefix instead of OVERLEAF_

Clone the Toolkit repository

First, let's clone this Toolkit repository to the host machine:

git clone https://github.com/overleaf/toolkit.git ./overleaf-toolkit

Next run the bin/init command to initialise the Toolkit with its default configuration.

Setting the image and version

In the docker-compose.yml file the image and version are defined in the component description:

version: '2.2'
services:
    sharelatex:
        restart: always
        # Server Pro users:
        # image: quay.io/sharelatex/sharelatex-pro
        image: sharelatex/sharelatex:3.5.13

When using the Toolkit, the image name is automatically resolved; the only requirement is to set SERVER_PRO=true in config/overleaf.rc to pick the Server Pro image or SERVER_PRO=false to use Community Edition.

The desired Server Pro/Community Edition version number is set in the config/version file. The Toolkit requires a specific version number like "4.2.3". In case you are using latest, you can use bin/images to find the image id of your local latest version, then use the release notes for 2.x, 3.x, 4.x or 5.x to map the image id to the version.

If you are sourcing the image from your own internal registry you can override the image the Toolkit uses by setting OVERLEAF_IMAGE_NAME. You do not need to specify the tag as the Toolkit will automatically add it based on your config/version file.

Configuring external access

By default, Overleaf will listen on 127.0.0.1:80, only allowing traffic from the Docker host machine.

To allow external access, you’ll need to set the OVERLEAF_LISTEN_IP and OVERLEAF_PORT in the config/overleaf.rc file.

Environment variable migration

You’ll likely have a set of environment variables defined in the sharelatex service:

environment:
    SHARELATEX_APP_NAME: Overleaf Community Edition
    SHARELATEX_PROXY_LEARN: 'true'
    …

Each of these variables should be copied, with several exceptions we’ll list later, into the Toolkit’s config/variables.env file, ensuring the following form (note the use of = instead of :):

SHARELATEX_APP_NAME=Overleaf Community Edition
SHARELATEX_PROXY_LEARN=true

As mentioned above, there are several exceptions, as certain features are configured differently when using the Toolkit:

• Variables starting with SANDBOXED_COMPILES_ and DOCKER_RUNNER are no longer needed. To enable Sandboxed Compiles, set SIBLING_CONTAINERS_ENABLED=true in your config/overleaf.rc file.
• Variables starting with SHARELATEX_MONGO_, SHARELATEX_REDIS_ and the REDIS_HOST variable are no longer needed. MongoDB and Redis are now configured in the config/overleaf.rc file using MONGO_URL, REDIS_HOST and REDIS_PORT.

For advanced configuration options, refer to the overleaf.rc documentation.

NGINX Proxy

For instructions on how to migrate nginx, please see TLS Proxy for Overleaf Toolkit environment

Volumes

ShareLaTeX

The location of the data volume for the sharelatex container will need to be set using OVERLEAF_DATA_PATH in the config/overleaf.rc file.

In case you are bind-mounting the application logs, you can use OVERLEAF_LOG_PATH to configure the host path.

MongoDB

The location of the data volume for the mongo container will need to be set using MONGO_DATA_PATH in the config/overleaf.rc file.

Redis

The location of the data volume for the redis container will need to be set using REDIS_DATA_PATH in the config/overleaf.rc file.