> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash title="Run this" theme={null}
ls -l
```

> [!NOTE]
>
> 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:

```text theme={null}
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
```

> [!NOTE]
>
> 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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/files-and-locations.md#persistent-data) section below. |

> [!WARNING]
>
> 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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/toolkit-settings.md) page.

> [!NOTE]
>
> 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](https://ayakaleaf-pro.mintlify.site/on-premises/maintenance/upgrading-your-deployment.md). |
| `bin/rename-env-vars-5-0`, `bin/rename-rc-vars` | One-off migrations of old `SHARELATEX_*` variable names to `OVERLEAF_*`. |

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/environment-variables.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.