2. Familiarize yourself with the Toolkit

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

ls -l

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:

drwxr-xr-x 3 fry fry  4096 Aug 30 14:16 bin
-rw-r--r-- 1 fry fry  6465 Aug 30 14:16 CHANGELOG.md
drwxr-xr-x 2 fry fry  4096 Sep  6 12:43 config
drwxr-xr-x 5 fry fry  4096 Aug 30 14:22 data
drwxr-xr-x 3 fry fry  4096 Aug 30 14:16 doc
drwxr-xr-x 3 fry fry  4096 Aug 30 14:16 lib
-rw-r--r-- 1 fry fry 34520 Aug 30 14:16 LICENSE
-rw-r--r-- 1 fry fry  1178 Aug 30 14:16 README.md

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

Name	Description
bin	This folder contains a collection of scripts that help you manage your Overleaf server instance. You can read more about these scripts in our Commands section below.
config	This folder contains your own local configuration files.
lib	This folder contains base configuration files used by the Toolkit.
data	By default this folder contains the storage location for MongoDb, Redis and Overleaf. For more information see Persistent data section below.

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.

Command	What it does
bin/init	Creates the configuration files in config/ the first time. bin/init --tls adds the NGINX TLS proxy configuration.
bin/up	Creates and starts the containers (bin/docker-compose up). Add -d to run in the background instead of following the logs. Run it after every change in config/: it recreates the containers whose configuration changed.
bin/start	Starts the existing containers again (bin/docker-compose start). It does not apply configuration changes.
bin/stop	Stops the containers and keeps them (bin/docker-compose stop).
bin/docker-compose	Runs docker compose with the Toolkit’s files, for example bin/docker-compose ps or bin/docker-compose restart sharelatex.
bin/logs	Shows or follows the logs of one or more services, for example bin/logs -f web.
bin/error-logs	Like bin/logs, but shows only the errors.
bin/shell	Opens a shell inside the sharelatex container.
bin/mongo	Opens a MongoDB shell on the sharelatex database.
bin/run-script	Runs a script that ships inside the sharelatex container.
bin/doctor	Checks the host and the configuration, and prints a report to share when you ask for help.
bin/images	Lists the Overleaf Docker images on the host.
bin/backup-config	Copies the config/ directory to a backup location (copy, zip or tar).
bin/upgrade	Updates the Toolkit and the Overleaf image step by step, see Upgrading your deployment.
bin/rename-env-vars-5-0, bin/rename-rc-vars	One-off migrations of old SHARELATEX_* variable names to OVERLEAF_*.

When bin/up recreates a container, everything changed inside it is lost, for example packages installed or files edited through bin/shell. Only the data directories (data/ by default) and config/ are kept. Make lasting changes through config/variables.env, config/overleaf.rc or config/docker-compose.override.yml instead.

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.