Skip to main content

Taking a look around

Now that you have a local copy of the Toolkit, let’s take a look at the structure of the repository using the ls command.
Run this
The ls -l command displays a detailed long listing view of the contents of a directory, providing additional file information such as permissions, ownership and size.
If everything was cloned successfully you should see something like this:
All user-owned configuration files are found in the config/ directory. This directory is excluded from the git revision control system, so it will not be changed by updating the Toolkit.

Repository layout

We recommend not changing files outside of the /config folder directly. Instead, if you need to make changes, they can be done via environment variables set in either config/variables.env or config/overleaf.rc.
For example, to set the mongo service image, rather than editing lib/docker-compose.mongo.yml directly, set the image using the environment variable MONGO_IMAGE in config/overleaf.rc. For more information see the Toolkit settings page.
The Toolkit will not change any data in the config/ directory without your permission.

Commands

Run these scripts from the Toolkit directory. Each one prints its options with --help.

What survives a rebuild

A rebuild replaces a container with a new one. Only the data directories (data/ by default) and config/ are outside the container, so everything else goes with it: packages installed or files edited through bin/shell, and the logs in /var/log/overleaf unless you set OVERLEAF_LOG_PATH.
  • Commands that keep the container do not apply changes in config/. Use bin/up for that.
  • To rebuild all the containers, run bin/docker-compose down, then bin/up -d. Your projects, users and history stay.
  • Make lasting changes through config/variables.env, config/overleaf.rc or config/docker-compose.override.yml, not inside a container.
  • Without OVERLEAF_SESSION_SECRET, a new container signs sessions with a new secret, so everyone has to log in again.
  • Your data is deleted only if you delete the data directories yourself. Before an upgrade, make a backup.
If every bin/up logs all users out, set OVERLEAF_SESSION_SECRET. Without it the session cookies are signed with a secret that is generated again whenever the container is recreated, see the Q&A in Environment Variables.
Last modified on November 11, 2026