Persistent Data
The Overleaf Toolkit needs to store persistent data, such as the files required to compile LaTeX projects, and the contents of the MongoDB database. This is achieved by mounting a few directories from the host machine into the Docker containers, and writing the data to those directories.Data Directories
Thesharelatex container requires a directory in which to store data relating to LaTeX compiles. This directory is set with the OVERLEAF_DATA_PATH variable in config/overleaf.rc.
The mongo container, if it is enabled, requires a directory in which to store its database files, and the same is true of the redis container. These directories can also be configured in config/overleaf.rc.
File Permissions
Because Docker runs asroot, the data directories will end up being owned by the root user, even if the Toolkit is being used by a non-root user. This is not a problem, but is worth being aware of if you intend to alter the persistent data from outside of the containers.
Configuration file location
All user-owned configuration files are found in theconfig/ directory.
This directory is excluded from the git revision control system, so it will not be changed by updating the Toolkit code. The Toolkit will not change any data in the config/ directory without your permission.
Changes to the configuration files will not be automatically applied to existing containers, even if the container is stopped and restarted (with
bin/stop and bin/start). To apply the changes, run bin/up, and behind the scenes, docker compose will automatically apply the configuration changes to a new container. (Or, run bin/up -d, if you prefer not to attach to the Docker logs.)The config/overleaf.rc file
The config/overleaf.rc file contains the most important top-level configuration settings used by the Toolkit. It contains statements that set variables, in the format: VARIABLE_NAME=value
To see a breakdown of all available configuration options see our settings section.
The variables.env file
The config/variables.env file contains environment variables that are loaded into the sharelatex container, and used to configure the Overleaf microservices. These include the name of the application, as displayed in the header of the web interface, settings for sending emails, and other settings such as SSO.
To see a breakdown of all available environment variables see the Environment variables section.
The config/version file
The config/version file contains the version number of the Docker image that will be used to create the running instance of your Overleaf server.
Changes to these configuration files will not be automatically applied to existing containers, even if the container is stopped and restarted (with
bin/stop and bin/start). To apply your changes, run bin/up, and the Toolkit will automatically create a new container for you with configuration changes applied.The docker-compose.override.yml file
If present, the config/docker-compose.override.yml file will be included in the invocation to docker compose. This is useful for overriding configuration specific to Docker Compose.
config/variables.env is not loaded into the mongo and redis containers. To set an environment variable there, add it here and run bin/up -d, for example:
Q&A
Which filesystem should the data directories use? Can I use btrfs, copy-on-write or zstd compression?
Which filesystem should the data directories use? Can I use btrfs, copy-on-write or zstd compression?
Answer: The Toolkit does not check the filesystem. The one with requirements is MongoDB, so the choice matters most for
data/mongo (MONGO_DATA_PATH). MongoDB’s production notes say to use XFS or ext4 on Linux, and strongly recommend XFS with WiredTiger, the storage engine it uses. They do not cover btrfs or other copy-on-write filesystems. If your root filesystem is btrfs, you can mount an XFS volume and point MONGO_DATA_PATH to it. The filesystem must also support fsync() on directories, which HGFS and VirtualBox shared folders do not.Filesystem compression saves little for data/mongo: WiredTiger already compresses collections with snappy and indexes with prefix compression. For NFS, see Troubleshooting.
