Skip to main content

Prerequisites

Overleaf is a typical open-source project for microservice architecture, with all services running in Docker. To set up an Overleaf development environment, you’ll need a powerful server; a configuration of at least 8 cores and 16GB of RAM is recommended, as you’ll need to run more than 20 containers simultaneously.
Since servers with 8 or more CPU cores are typically expensive, It’s highly recommend using your local computer for development.
Meanwhile, as a developer, we believe you should already be familiar with Docker installation. We strongly suggest using a recent and stable Ubuntu LTS (e.g. Ubuntu 24.04 in 2025–2026) and the latest Docker for development, as this reduces the possibility of encountering unexpected errors. In summary, you will need:
  • A powerful server/desktop to develop
  • A recent and stable Ubuntu LTS (e.g. Ubuntu 24.04)
  • Docker and Git environment

Configuration Tutorial

Here, we use Ayakaleaf Pro to show how to set up an Overleaf development environment. All commands below run in the develop directory unless said otherwise.
1

Pull the Source Code

First of all let’s clone the repo:
bash
2

Synchronize yarn.lock

The repository uses Yarn 4 (packageManager in the root package.json), and its yarn.lock can be out of sync with the package.json files. Sync it after the first clone and after any package.json change:
bash
bin/sync runs yarn install --mode=update-lockfile in a node:24.18.1 container, so you do not need Node.js on the host. Do not commit the changed yarn.lock.
3

Build Develop Image

Build the services:
bash
If Docker is running out of RAM while building the services in parallel, create a .env file in this directory containing COMPOSE_PARALLEL_LIMIT=1.
4

Apply the Translations

The modules of Ayakaleaf Pro keep their translations in services/web/locales/locales_patches/, which the committed locale files do not contain. Apply them once before the first start, or the pages of these modules show keys such as about_to_permanently_delete_accounts instead of text:
bash
It needs jq on the host. Run it again after adding a translation or changing branch, see Update i18n Translations.
5

Start All Micro Services

Then start the services:
bash
Once the services are running, open http://localhost/launchpad to create the first admin account. Add the port if you changed OVERLEAF_PORT (see below).
LDAP is on by default (LDAP_ENABLED=true in dev.rc). The launchpad then shows the LDAP admin form: it only asks for an email, and that admin logs in through LDAP afterwards, for example as professor / professor (professor@planetexpress.com). The test users are listed in develop/authentication/README.md. Set LDAP_ENABLED=false and SAML_ENABLED=false to create a local admin with a password instead.
develop/dev.env already sets ADMIN_PRIVILEGE_AVAILABLE=true, so admins can open the Admin panel without extra setup.

Configuration (dev.rc)

develop/dev.rc, next to dev.env, holds the switches of the dev environment, like overleaf.rc in the Overleaf Toolkit. Change a value and run bin/dev again to apply it; a feature that is turned off also stops its containers. Each feature keeps its docker-compose.yml and other files in its own folder: authentication/ldap, authentication/saml, mail, s3, hoppscotch and grafana. A feature that needs a web setting without an environment variable mounts a file into /etc/overleaf/settings.d/, and develop/settings.dev-env.cjs merges all of them. All bin/* scripts go through bin/docker-compose, which adds the files of the features that are on. Call bin/docker-compose instead of docker compose when you need a compose command yourself.
The local volumes and RustFS are separate stores: a project created with S3_ENABLED=true has no history or binary files after switching to false, and the other way round. To copy the files of an environment that ran before S3_ENABLED existed into RustFS, follow “Moving existing data into RustFS” in develop/README.md.

Ports

The site, the RustFS console and Hoppscotch listen on 127.0.0.1 of the host; on a remote machine, forward their ports first, for example ssh -L 9001:localhost:9001 <host>. The site uses OVERLEAF_PORT from dev.rc, so add the port to the addresses below if you changed it. Mailpit, Grafana, Mongo Express and RedisInsight are served by the site on their own paths, through webpack-dev-server, so they need no port of their own. Once you are logged in, the Dev tools menu in the navbar of the site links to them; a page whose feature is turned off in dev.rc is left out. Setup Develop Tools shows what each of them does. The S3 API (port 9000) and SMTP (port 1025) are only reachable inside the Docker network. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) and git-bridge (8000) are published on 127.0.0.1 of the host only.

TeX Live

Sandboxed compiles are on by default: develop/dev.env sets SANDBOXED_COMPILES=true and the images ghcr.io/ayaka-notes/texlive-full:2026.1 and ghcr.io/ayaka-notes/texlive-full:2025.1. clsi does not pull images itself, so pull them once:
See Setup Sandbox Compiles for the details.
A project created while SANDBOXED_COMPILES was off has no TeX Live image. It still compiles with the default image, but jumping between the code and the PDF fails with “That didn’t work. Recompile and try again.” Give such projects the image of TEX_LIVE_DOCKER_IMAGE once; without --commit, the script only shows what it would change:
dev.env also turns on Pandoc conversions with PANDOC_IMAGE=overleaf-pandoc:local. Build that image once, from the root of the repository:
To compile on a macOS host, you may need to override the path to the Docker socket by creating a .env file in the develop directory, containing DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Development

To avoid running bin/build && bin/up after every code change, you can run Overleaf Community Edition in development mode, where services will automatically update on code changes. To do this, use the included bin/dev script:
This will start all services using node --watch, which will automatically monitor the code and restart the services as necessary. Run it again after changing dev.rc. To improve performance, you can start only a subset of the services in development mode by providing a space-separated list to the bin/dev script:
Starting the web service in development mode will only update the web service when backend code changes. In order to automatically update frontend code as well, make sure to start the webpack service in development mode as well.
If no services are named, all services will start in development mode. After adding a translation or changing branch, run bin/i18n, see Update i18n Translations.

Debugging

When run in development mode most services expose a debugging port to which you can attach a debugger such as the inspector in Chrome’s Dev Tools or one integrated into an IDE. The following table shows the port exposed on 127.0.0.1 of the host machine for each service: To attach to a service using Chrome’s remote debugging, go to chrome://inspect/ and make sure Discover network targets is checked. Next click Configure… and add an entry localhost:[service port] for each of the services you want to attach a debugger to. After adding an entry, the service will show up as a Remote Target that you can inspect and debug.

Logging

The script bin/logs follows the logs and formats them with bunyan. It also needs ggrep, which is the name of GNU grep when installed with Homebrew on macOS; Ubuntu does not have a ggrep command.
Or, you can run directly with:
Use bin/docker-compose rather than docker compose, so that the services of the features in dev.rc (mailpit, rustfs, ldap, saml, hoppscotch, and grafana with Prometheus, Loki and the exporters) are found too. With GRAFANA_ENABLED=true, the logs of every container are also in Grafana, where they can be filtered by service, level and text, see Setup Develop Tools.

Other Tools

Once you’ve done all, you can refer to the next section to add some debug tools to your overleaf development.
Last modified on November 15, 2026