> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/maintenance/docker-compose.yml-to-toolkit-migration.md).

# 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 %}

{% stepper %}
{% step %}

### Clone the Toolkit repository

First, clone the 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.
{% endstep %}

{% step %}

### Setting the image and version

In a typical `docker-compose.yml` the image and version are defined in the component description, for example:

```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`. If 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, 3.x.x, 4.x.x or 5.x.x 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.
{% endstep %}

{% step %}

### 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, set the `OVERLEAF_LISTEN_IP` and `OVERLEAF_PORT` in the [**config/overleaf.rc**](/on-premises/configuration/overleaf-toolkit/environment-variables.md) file.
{% endstep %}

{% step %}

### Environment variable migration

You’ll likely have a set of environment variables defined in the `sharelatex` service in your `docker-compose.yml`, for example:

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

Copy these variables into the Toolkit’s [**config/variables.env**](broken://pages/f85467fdca000c0dbac697fb58e52f29cb74dc46) file, ensuring the following form (use `=` instead of `:`):

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

Exceptions / differences 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/environment-variables.md) documentation.
{% endstep %}

{% step %}

### NGINX Proxy

For instructions on how to migrate `nginx`, see the [TLS Proxy documentation](/on-premises/configuration/overleaf-toolkit/tls-proxy.md):
{% endstep %}

{% step %}

### Volumes

Set the locations of data volumes in **config/overleaf.rc**:

#### ShareLaTeX

Set the `OVERLEAF_DATA_PATH` to the location of the data volume used by the `sharelatex` container.

#### MongoDB

Set the `MONGO_DATA_PATH` to the location of the data volume used by the `mongo` container.

#### Redis

Set the `REDIS_DATA_PATH` to the location of the data volume used by the `redis` container.
{% endstep %}
{% endstepper %}

For more details and advanced configuration, consult the relevant Toolkit configuration docs linked above.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/on-premises/maintenance/docker-compose.yml-to-toolkit-migration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.