# docker-compose.yml to Toolkit migration

If you're currently using Docker Compose via a `docker-compose.yml` file, migrating to the Toolkit can make running an on-premises version of Overleaf easier to deploy, upgrade and maintain.

To migrate, you'll need to convert your existing Docker Compose setup into the format used by the Toolkit. This process involves copying existing configuration into the Toolkit.

This guide will walk you through each step of this process, ensuring a smooth migration from Docker Compose to the Toolkit.

{% hint style="info" %}
These instructions are for v4.x and earlier. Therefore all variables use the `SHARELATEX_` prefix instead of `OVERLEAF_`
{% endhint %}

## Clone the Toolkit repository

First, let's clone this Toolkit repository to the host machine:

```bash
git clone https://github.com/overleaf/toolkit.git ./overleaf-toolkit
```

Next run the `bin/init` command to initialise the Toolkit with its default configuration.

## Setting the image and version

In the `docker-compose.yml` file the image and version are defined in the component description:

```yaml
version: '2.2'
services:
    sharelatex:
        restart: always
        # Server Pro users:
        # image: quay.io/sharelatex/sharelatex-pro
        image: sharelatex/sharelatex:3.5.13
```

When using the Toolkit, the image name is automatically resolved; the only requirement is to set `SERVER_PRO=true` in **config/overleaf.rc** to pick the Server Pro image or `SERVER_PRO=false` to use Community Edition.

The desired Server Pro/Community Edition version number is set in the **config/version** file. The Toolkit requires a specific version number like "**4.2.3**". In case you are using `latest`, you can use `bin/images` to find the image id of your local `latest` version, then use the release notes for [2.x.x](/on-premises/release-notes/release-notes-2.x.x.md), [3.x.x](/on-premises/release-notes/release-notes-3.x.x.md), [4.x.x](/on-premises/release-notes/release-notes-4.x.x.md) or [5.x.x](/on-premises/release-notes/release-notes-5.x.x.md) to map the image id to the version.

If you are sourcing the image from your own internal registry you can override the image the Toolkit uses by setting `OVERLEAF_IMAGE_NAME`. You do not need to specify the tag as the Toolkit will automatically add it based on your **config/version** file.

## Configuring external access

By default, Overleaf will listen on **127.0.0.1:80**, only allowing traffic from the Docker host machine.

To allow external access, you’ll need to set the `OVERLEAF_LISTEN_IP` and `OVERLEAF_PORT` in the [**config/overleaf.rc**](/on-premises/configuration/overleaf-toolkit/toolkit-settings.md) file.

## Environment variable migration

You’ll likely have a set of environment variables defined in the **sharelatex** service:

```yaml
environment:
    OVERLEAF_APP_NAME: Overleaf Community Edition
    OVERLEAF_PROXY_LEARN: 'true'
    …
```

Each of these variables should be copied, with several exceptions we’ll list later, into the Toolkit’s [**config/variables.env**](/on-premises/configuration/overleaf-toolkit/environment-variables.md) file, ensuring the following form (note the use of `=` instead of `:`):

```
OVERLEAF_APP_NAME=Overleaf Community Edition
OVERLEAF_PROXY_LEARN=true
```

As mentioned above, there are several exceptions, as certain features are configured differently when using the Toolkit:

* Variables starting with `SANDBOXED_COMPILES_` and `DOCKER_RUNNER` are no longer needed. To enable Sandboxed Compiles, set `SIBLING_CONTAINERS_ENABLED=true` in your **config/overleaf.rc** file.
* Variables starting with `OVERLEAF_MONGO_`, `OVERLEAF_REDIS_` and the `REDIS_HOST` variable are no longer needed. MongoDB and Redis are now configured in the **config/overleaf.rc** file using `MONGO_URL`, `REDIS_HOST` and `REDIS_PORT`.

For advanced configuration options, refer to the [config/overleaf.rc](/on-premises/configuration/overleaf-toolkit/toolkit-settings.md) documentation.

## NGINX Proxy

For instructions on how to migrate `nginx`, please see [TLS Proxy](/on-premises/configuration/overleaf-toolkit/tls-proxy.md).

## Volumes

### ShareLaTeX

The location of the data volume for the `sharelatex` container will need to be set using `OVERLEAF_DATA_PATH` in the **config/overleaf.rc** file.

### MongoDB

The location of the data volume for the `mongo` container will need to be set using `MONGO_DATA_PATH` in the **config/overleaf.rc** file.

### Redis

The location of the data volume for the `redis` container will need to be set using `REDIS_DATA_PATH` in the **config/overleaf.rc** file.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overleaf.com/on-premises/maintenance/docker-compose.yml-to-toolkit-migration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.