Configurar o ambiente de desenvolvimento (local)

Configure seu ambiente de desenvolvimento em seu servidor local ou desktop.

​

Pré-requisitos

O Overleaf é um projeto de código aberto típico com arquitetura de microsserviços, com todos os serviços executados no Docker.

• O código-fonte oficial da Community Edition está em GitHub Overleaf Official.
• O código-fonte do Overleaf-CEP está disponível em GitHub Yu-i-i/Overleaf.
• O Overleaf Pro Edition está disponível em GitHub Ayaka-notes/overleaf-pro.

Para configurar um ambiente de desenvolvimento do Overleaf, você precisará de um servidor potente; recomenda-se uma configuração de pelo menos 8 núcleos e 16 GB de RAM, pois será necessário executar mais de 20 contêineres simultaneamente.

Como servidores com 8 ou mais núcleos de CPU costumam ser caros, recomendamos fortemente usar seu computador local para o desenvolvimento.

Além disso, como desenvolvedor, acreditamos que você já esteja familiarizado com a instalação do Docker. Sugerimos fortemente usar uma versão LTS recente e estável do Ubuntu (por exemplo, Ubuntu 24.04 em 2025–2026) e a versão mais recente do Docker para desenvolvimento, pois isso reduz a possibilidade de encontrar erros inesperados.

Em resumo, você precisará de:

• Um servidor/desktop potente para desenvolver
• Uma versão LTS recente e estável do Ubuntu (por exemplo, Ubuntu 24.04)
• Ambiente com Docker e Git

​

Tutorial de configuração

Aqui, usaremos o overleaf-cep como exemplo para demonstrar como configurar um ambiente de desenvolvimento do Overleaf.

1. Obter o código-fonte

   Primeiro, vamos clonar o repositório:

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. Sincronizar o package-lock.json

   Como o Overleaf é desenvolvido em um repositório interno, é muito provável que o arquivo package-lock.json fique dessincronizado devido a questões de desenvolvimento. Precisamos executar o comando a seguir para sincronizá-lo (caso você tenha um ambiente nodejs local).

   bash

   npm install --package-lock-only --ignore-scripts
   

   Se você não tiver o nodejs instalado, não se preocupe: você pode usar diretamente o docker para executar o mesmo comando. Execute a partir da raiz do repositório do Overleaf:

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. Construir a imagem de desenvolvimento

   O Overleaf fornece um diretório dedicado /develop para armazenar os scripts de desenvolvimento. Basta construir os serviços:

   bash

   cd ./develop
   bin/build
   

   Se o Docker ficar sem RAM ao construir os serviços em paralelo, crie um arquivo .env neste diretório contendo COMPOSE_PARALLEL_LIMIT=1.

4. Iniciar todos os microsserviços

   Em seguida, inicie os serviços:

   bash

   bin/up
   

   Quando os serviços estiverem em execução, abra http://localhost/launchpad para criar a primeira conta de administrador.

   Você deve executar bin/up antes de executar o comando bin/dev. Caso contrário, poderá encontrar uma série de problemas de permissão.

Por padrão, o privilégio de administrador não está disponível. Você precisa adicionar isto ao develop/dev.env. Depois disso, você terá acesso ao painel de administração.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

Compilar um PDF requer a construção de uma imagem do TeX Live para realizar a compilação dentro do Docker:

docker build texlive -t texlive-full

Para compilar em um host macOS, talvez seja necessário substituir o caminho do socket do Docker criando um arquivo .env neste diretório contendo DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Você também pode usar o ayaka-notes/texlive-full, mas pode usar a tag base, que é a versão mínima do texlive.

​

Desenvolvimento

Para evitar executar bin/build && bin/up após cada alteração no código, você pode executar o Overleaf Community Edition em modo de desenvolvimento, no qual os serviços são atualizados automaticamente quando o código muda.

Para isso, use o script incluído bin/dev:

bin/dev

Isso iniciará todos os serviços usando node --watch, que monitora automaticamente o código e reinicia os serviços conforme necessário.

Para melhorar o desempenho, você pode iniciar apenas um subconjunto dos serviços em modo de desenvolvimento, fornecendo uma lista separada por espaços ao script bin/dev:

bin/dev [service1] [service2] ... [serviceN]

Iniciar o serviço web em modo de desenvolvimento só atualizará o serviço web quando o código de backend mudar. Para atualizar automaticamente também o código de frontend, certifique-se de iniciar também o serviço webpack em modo de desenvolvimento.

Se nenhum serviço for informado, todos os serviços serão iniciados em modo de desenvolvimento.

​

Depuração

Quando executados em modo de desenvolvimento, a maioria dos serviços expõe uma porta de depuração à qual você pode conectar um depurador, como o inspetor do Chrome Dev Tools ou um integrado a uma IDE. A tabela a seguir mostra a porta exposta na máquina host para cada serviço:

Serviço	Porta
web	9229
clsi	9230
chat	9231
contacts	9232
docstore	9233
document-updater	9234
filestore	9235
notifications	9236
real-time	9237
references	9238
history-v1	9239
project-history	9240
linked-url-proxy	9241

Para se conectar a um serviço usando a depuração remota do Chrome, acesse chrome://inspect/ e certifique-se de que Discover network targets esteja marcado. Em seguida, clique em Configure… e adicione uma entrada localhost:[service port] para cada serviço ao qual deseja conectar um depurador.

Depois de adicionar uma entrada, o serviço aparecerá como um Remote Target que você pode inspecionar e depurar.

​

Logs

No ambiente de desenvolvimento, o Overleaf fornece o script bin/logs; no entanto, é necessário instalar uma dependência:

sudo npm install -g bunyan
# Or sudo apt install node-bunyan 

Ou você pode executar diretamente:

docker compose logs -f [service name]

​

Outras ferramentas

Depois de concluir tudo, você pode consultar a próxima seção para adicionar algumas ferramentas de depuração ao seu desenvolvimento do Overleaf.