What is the Overleaf Toolkit?
The Overleaf Toolkit is the recommended deployment method for on-premises installations of the Community Edition and Server Pro and has been designed to work with the most common environment: a single physical server or virtual machine. The Toolkit uses docker compose to manage your server's Docker containers and provides a set of scripts which wrap docker commands to assist with the more technical side of managing an on-premises version of Overleaf.
The bin/docker-compose wrapper
bin/docker-compose wrapperThe 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:
Convenience helpers
In addition to bin/docker-compose, the Toolkit also provides a collection of convenient scripts to assist with common tasks:
bin/up: shortcut forbin/docker-compose upbin/start: shortcut forbin/docker-compose startbin/stop: shortcut forbin/docker-compose stopbin/shell: starts a shell inside the sharelatex containerbin/doctor: script used to gather installation and deployment information. See Checking your server section belowbin/mongo: starts a shell inside the mongo container and switch to the correct database (sharelatex)bin/backup-config: used to create a copy, zip or tar of your current configuration and then store in a destination directory of your choicebin/logs: script used for easily viewing/tailing service logsbin/error-logs: script used for easily viewing/tailing service error logsbin/rename-env-vars-5-0: migration script used to update environment variables in config/variables.env as part of the re-branding from ShareLaTeX to Overleafbin/rename-rc-vars: migration script used to update environment variables in config/overleaf.rc as part of the re-branding from ShareLaTeX to Overleafbin/run-script: helper script used to simplify running scripts that are stored within the sharelatex containerbin/upgrade: script used to assist with instance upgrades. The script with check for updates to the Toolkit code (via git) and offer to pull any new changes. It will then check for the latest available version of the Docker image currently in use and offer to update it. The script provides step-by-step confirmation, the option to take a backup of current configuration and handles the stopping/starting of Docker services. See Upgrading your deployment for more information.
If you prefer to run your instance without attaching to the Docker logs you can run bin/up -d to run in detached mode.
Checking your server
The Overleaf Toolkit includes a handy script called bin/doctor that produces a report pointing to any unfulfilled dependency.
Before we continue any further, let's run the bin/doctor script and check that everything is working correctly.
We should see some output similar to this:
First, we see some information about the host system (the machine that the Toolkit is being run on), then some information about dependencies. If any dependencies are missing, we will see a warning here. Next, the doctor checks our local configuration. At the end, the doctor will print out some warnings, if any problems were encountered. For example, if you're running end-of-life versions of Docker or Docker Compose.
If you run into problems with running the Toolkit, you should first run the bin/doctor script and check it's output for any warnings.
Users of the free Community Edition should open an issue on GitHub.
Users of Server Pro should contact support+serverpro@overleaf.com for assistance.
In both cases, it is a good idea to include the output of the bin/doctor script in your message.
Last updated
Was this helpful?