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 Ayakaleaf Pro está disponível no GitHub ayaka-notes/ayakaleaf-pro.
Como servidores com 8 ou mais núcleos de CPU costumam ser caros, recomendamos fortemente usar seu computador local para o desenvolvimento.
- 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, usamos o Ayakaleaf Pro para mostrar como configurar um ambiente de desenvolvimento do Overleaf. Todos os comandos abaixo são executados no diretóriodevelop, salvo indicação em contrário.
1
Obter o código-fonte
Primeiro, vamos clonar o repositório:
bash
2
Sincronizar o yarn.lock
O repositório usa Yarn 4 (
packageManager no package.json raiz), e o seu yarn.lock pode ficar fora de sincronia com os arquivos package.json. Sincronize-o após o primeiro clone e após qualquer alteração em um package.json:bash
bin/sync executa yarn install --mode=update-lockfile em um contêiner node:24.18.1, então você não precisa de Node.js no host. Não faça commit do yarn.lock alterado.3
Construir a imagem de desenvolvimento
Construa os serviços:
bash
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
Aplicar as traduções
Os módulos do Ayakaleaf Pro guardam suas traduções em Ele precisa de
services/web/locales/locales_patches/, que os arquivos de locales commitados não contêm. Aplique-as uma vez antes da primeira inicialização, ou as páginas desses módulos mostrarão chaves como about_to_permanently_delete_accounts em vez de texto:bash
jq no host. Execute-o novamente depois de adicionar uma tradução ou trocar de branch, veja Atualizar traduções i18n.5
Iniciar todos os microsserviços
Em seguida, inicie os serviços:Quando os serviços estiverem em execução, abra http://localhost/launchpad para criar a primeira conta de administrador. Adicione a porta se você alterou
bash
OVERLEAF_PORT (veja abaixo).O LDAP vem ativado por padrão (
LDAP_ENABLED=true em dev.rc). O launchpad então mostra o formulário de administrador LDAP: ele pede apenas um e-mail, e esse administrador faz login depois pelo LDAP, por exemplo como professor / professor (professor@planetexpress.com). Os usuários de teste estão listados em develop/authentication/README.md. Defina LDAP_ENABLED=false e SAML_ENABLED=false para criar um administrador local com senha.develop/dev.env já define ADMIN_PRIVILEGE_AVAILABLE=true, então os administradores podem abrir o painel de administração sem configuração extra.Configuração (dev.rc)
develop/dev.rc, ao lado de dev.env, contém as chaves do ambiente de desenvolvimento, como o overleaf.rc no Overleaf Toolkit. Altere um valor e execute bin/dev novamente para aplicá-lo; um recurso desativado também para seus contêineres.
Cada recurso mantém seu
docker-compose.yml e outros arquivos em uma pasta própria: authentication/ldap, authentication/saml, mail, s3, hoppscotch e grafana. Um recurso que precisa de uma configuração do web sem variável de ambiente monta um arquivo em /etc/overleaf/settings.d/, e develop/settings.dev-env.cjs mescla todos eles. Todos os scripts bin/* passam por bin/docker-compose, que adiciona os arquivos dos recursos ativados. Use bin/docker-compose em vez de docker compose quando precisar de um comando compose.
Portas
O site, o console do RustFS e o Hoppscotch escutam em127.0.0.1 do host; em uma máquina remota, encaminhe primeiro as portas, por exemplo ssh -L 9001:localhost:9001 <host>. O site usa OVERLEAF_PORT do dev.rc, então adicione a porta aos endereços abaixo se você a alterou.
Mailpit, Grafana, Mongo Express e RedisInsight são servidos pelo site em seus próprios caminhos, por meio do webpack-dev-server, então não precisam de porta própria. Depois do login, o menu Dev tools na barra de navegação do site aponta para eles; uma página cujo recurso está desativado no
dev.rc fica de fora. Configurar ferramentas de desenvolvimento mostra o que cada um faz.
A API do S3 (porta 9000) e o SMTP (porta 1025) só são acessíveis dentro da rede do Docker. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) e git-bridge (8000) são publicados apenas em 127.0.0.1 do host.
TeX Live
As compilações em sandbox vêm ativadas por padrão:develop/dev.env define SANDBOXED_COMPILES=true e as imagens ghcr.io/ayaka-notes/texlive-full:2026.1 e ghcr.io/ayaka-notes/texlive-full:2025.1. O clsi não baixa imagens sozinho, então baixe-as uma vez:
dev.env também ativa as conversões do Pandoc com PANDOC_IMAGE=overleaf-pandoc:local. Construa essa imagem uma vez, a partir da raiz do repositório:
.env no diretório develop com DOCKER_SOCKET_PATH=/var/run/docker.sock.raw
Desenvolvimento
Para evitar executarbin/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:
node --watch, que monitora automaticamente o código e reinicia os serviços conforme necessário. Execute-o novamente depois de alterar o dev.rc.
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:
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.bin/i18n, veja Atualizar traduções i18n.
Depuração
No 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 Dev Tools do Chrome ou um integrado a uma IDE. A tabela a seguir mostra a porta exposta em127.0.0.1 da máquina host para cada serviço:
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
O scriptbin/logs acompanha os logs e os formata com bunyan. Ele também precisa de ggrep, que é o nome do GNU grep quando instalado com Homebrew no macOS; o Ubuntu não tem o comando ggrep.
bin/docker-compose em vez de docker compose, para que os serviços dos recursos do dev.rc (mailpit, rustfs, ldap, saml, hoppscotch e grafana com Prometheus, Loki e os exporters) também sejam encontrados.
Com GRAFANA_ENABLED=true, os logs de todos os contêineres também ficam no Grafana, onde podem ser filtrados por serviço, nível e texto, veja Configurar ferramentas de desenvolvimento.

