Saltar para o conteúdo principal

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. 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, usamos o Ayakaleaf Pro para mostrar como configurar um ambiente de desenvolvimento do Overleaf. Todos os comandos abaixo são executados no diretório develop, 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 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
Ele precisa de 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:
bash
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 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.
Os volumes locais e o RustFS são armazenamentos separados: um projeto criado com S3_ENABLED=true não tem histórico nem arquivos binários depois de mudar para false, e vice-versa. Para copiar para o RustFS os arquivos de um ambiente que rodava antes de S3_ENABLED existir, siga “Moving existing data into RustFS” em develop/README.md.

Portas

O site, o console do RustFS e o Hoppscotch escutam em 127.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:
Veja Configurar Sandbox Compiles para os detalhes.
Um projeto criado enquanto SANDBOXED_COMPILES estava desativado não tem imagem do TeX Live. Ele ainda compila com a imagem padrão, mas pular entre o código e o PDF falha com “That didn’t work. Recompile and try again.” Atribua uma vez a esses projetos a imagem de TEX_LIVE_DOCKER_IMAGE; sem --commit, o script só mostra o que mudaria:
O 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:
Para compilar em um host macOS, talvez seja necessário substituir o caminho do socket do Docker criando um arquivo .env no diretório develop com DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

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:
Isso iniciará todos os serviços usando 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.
Se nenhum serviço for informado, todos os serviços serão iniciados em modo de desenvolvimento. Depois de adicionar uma tradução ou trocar de branch, execute 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 em 127.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 script bin/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.
Ou você pode executar diretamente:
Use 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.

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.
Última modificação em 20 de novembro de 2026