Saltar al contenido principal

Requisitos previos

Overleaf es un proyecto de código abierto típico con arquitectura de microservicios, en el que todos los servicios se ejecutan en Docker. Para configurar un entorno de desarrollo de Overleaf necesitarás un servidor potente; se recomienda una configuración de al menos 8 núcleos y 16 GB de RAM, ya que tendrás que ejecutar más de 20 contenedores simultáneamente.
Como los servidores con 8 o más núcleos de CPU suelen ser caros, se recomienda encarecidamente usar tu ordenador local para el desarrollo.
Por otro lado, como desarrollador, entendemos que ya deberías estar familiarizado con la instalación de Docker. Te recomendamos encarecidamente usar una versión reciente y estable de Ubuntu LTS (por ejemplo, Ubuntu 24.04 en 2025–2026) y la última versión de Docker para el desarrollo, ya que así se reduce la posibilidad de encontrar errores inesperados. En resumen, necesitarás:
  • Un servidor o equipo de escritorio potente para desarrollar
  • Una versión reciente y estable de Ubuntu LTS (por ejemplo, Ubuntu 24.04)
  • Un entorno con Docker y Git

Tutorial de configuración

Aquí usamos Ayakaleaf Pro para mostrar cómo configurar un entorno de desarrollo de Overleaf. Todos los comandos siguientes se ejecutan en el directorio develop, salvo que se indique lo contrario.
1

Descargar el código fuente

En primer lugar, clonemos el repositorio:
bash
2

Sincronizar yarn.lock

El repositorio usa Yarn 4 (packageManager en el package.json raíz), y su yarn.lock puede quedar desincronizado de los archivos package.json. Sincronízalo tras el primer clon y tras cualquier cambio en un package.json:
bash
bin/sync ejecuta yarn install --mode=update-lockfile en un contenedor node:24.18.1, así que no necesitas Node.js en el host. No confirmes el yarn.lock modificado.
3

Construir la imagen de desarrollo

Construye los servicios:
bash
Si Docker se queda sin RAM al construir los servicios en paralelo, crea un archivo .env en este directorio que contenga COMPOSE_PARALLEL_LIMIT=1.
4

Aplicar las traducciones

Los módulos de Ayakaleaf Pro guardan sus traducciones en services/web/locales/locales_patches/, que los archivos de locales confirmados no contienen. Aplícalas una vez antes del primer arranque, o las páginas de estos módulos mostrarán claves como about_to_permanently_delete_accounts en lugar de texto:
bash
Necesita jq en el host. Vuelve a ejecutarlo después de añadir una traducción o cambiar de rama, consulta Actualizar las traducciones i18n.
5

Iniciar todos los microservicios

A continuación, inicia los servicios:
bash
Una vez que los servicios estén en ejecución, abre http://localhost/launchpad para crear la primera cuenta de administrador. Añade el puerto si cambiaste OVERLEAF_PORT (ver más abajo).
LDAP está activado por defecto (LDAP_ENABLED=true en dev.rc). El launchpad muestra entonces el formulario de administrador LDAP: solo pide un correo, y ese administrador inicia sesión después mediante LDAP, por ejemplo como professor / professor (professor@planetexpress.com). Los usuarios de prueba están listados en develop/authentication/README.md. Establece LDAP_ENABLED=false y SAML_ENABLED=false para crear en su lugar un administrador local con contraseña.
develop/dev.env ya establece ADMIN_PRIVILEGE_AVAILABLE=true, así que los administradores pueden abrir el panel de administración sin configuración adicional.

Configuración (dev.rc)

develop/dev.rc, junto a dev.env, contiene los interruptores del entorno de desarrollo, como overleaf.rc en el Overleaf Toolkit. Cambia un valor y vuelve a ejecutar bin/dev para aplicarlo; una función desactivada también detiene sus contenedores. Cada función guarda su docker-compose.yml y otros archivos en su propia carpeta: authentication/ldap, authentication/saml, mail, s3, hoppscotch y grafana. Una función que necesita un ajuste de web sin variable de entorno monta un archivo en /etc/overleaf/settings.d/, y develop/settings.dev-env.cjs los combina todos. Todos los scripts bin/* pasan por bin/docker-compose, que añade los archivos de las funciones activadas. Usa bin/docker-compose en lugar de docker compose cuando necesites un comando compose.
Los volúmenes locales y RustFS son almacenes separados: un proyecto creado con S3_ENABLED=true no tiene historial ni archivos binarios tras cambiar a false, y viceversa. Para copiar a RustFS los archivos de un entorno que funcionaba antes de que existiera S3_ENABLED, sigue «Moving existing data into RustFS» en develop/README.md.

Puertos

El sitio, la consola de RustFS y Hoppscotch escuchan en 127.0.0.1 del host; en una máquina remota, reenvía primero sus puertos, por ejemplo ssh -L 9001:localhost:9001 <host>. El sitio usa OVERLEAF_PORT de dev.rc, así que añade el puerto a las direcciones de abajo si lo cambiaste. El sitio sirve Mailpit, Grafana, Mongo Express y RedisInsight en sus propias rutas, a través de webpack-dev-server, así que no necesitan un puerto propio. Una vez que inicias sesión, el menú Dev tools de la barra de navegación del sitio enlaza a ellos; se omite la página cuya función está desactivada en dev.rc. Configurar herramientas de desarrollo muestra qué hace cada uno. La API de S3 (puerto 9000) y SMTP (puerto 1025) solo son accesibles dentro de la red de Docker. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) y git-bridge (8000) se publican solo en 127.0.0.1 del host.

TeX Live

Las compilaciones en sandbox están activadas por defecto: develop/dev.env establece SANDBOXED_COMPILES=true y las imágenes ghcr.io/ayaka-notes/texlive-full:2026.1 y ghcr.io/ayaka-notes/texlive-full:2025.1. clsi no descarga imágenes por sí mismo, así que descárgalas una vez:
Consulta Configurar compilaciones en sandbox para más detalles.
Un proyecto creado mientras SANDBOXED_COMPILES estaba desactivado no tiene imagen de TeX Live. Sigue compilando con la imagen por defecto, pero saltar entre el código y el PDF falla con «That didn’t work. Recompile and try again.» Asigna una vez a esos proyectos la imagen de TEX_LIVE_DOCKER_IMAGE; sin --commit, el script solo muestra lo que cambiaría:
dev.env también activa las conversiones de Pandoc con PANDOC_IMAGE=overleaf-pandoc:local. Construye esa imagen una vez, desde la raíz del repositorio:
Para compilar en un host macOS, puede que tengas que sobrescribir la ruta del socket de Docker creando un archivo .env en el directorio develop con DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Desarrollo

Para evitar ejecutar bin/build && bin/up después de cada cambio en el código, puedes ejecutar Overleaf Community Edition en modo de desarrollo, en el que los servicios se actualizan automáticamente cuando cambia el código. Para ello, usa el script incluido bin/dev:
Esto iniciará todos los servicios con node --watch, que supervisará automáticamente el código y reiniciará los servicios cuando sea necesario. Vuelve a ejecutarlo después de cambiar dev.rc. Para mejorar el rendimiento, puedes iniciar solo un subconjunto de los servicios en modo de desarrollo pasando una lista separada por espacios al script bin/dev:
Iniciar el servicio web en modo de desarrollo solo actualizará el servicio web cuando cambie el código del backend. Para que también se actualice automáticamente el código del frontend, asegúrate de iniciar también el servicio webpack en modo de desarrollo.
Si no se indica ningún servicio, todos los servicios se iniciarán en modo de desarrollo. Después de añadir una traducción o cambiar de rama, ejecuta bin/i18n, consulta Actualizar las traducciones i18n.

Depuración

En modo de desarrollo, la mayoría de los servicios exponen un puerto de depuración al que puedes conectar un depurador, como el inspector de las Dev Tools de Chrome o uno integrado en un IDE. La siguiente tabla muestra el puerto expuesto en 127.0.0.1 de la máquina host para cada servicio: Para conectarte a un servicio mediante la depuración remota de Chrome, ve a chrome://inspect/ y asegúrate de que Discover network targets esté marcado. Después haz clic en Configure… y añade una entrada localhost:[service port] para cada uno de los servicios a los que quieras conectar un depurador. Tras añadir una entrada, el servicio aparecerá como Remote Target, que podrás inspeccionar y depurar.

Registros

El script bin/logs sigue los logs y les da formato con bunyan. También necesita ggrep, que es el nombre de GNU grep cuando se instala con Homebrew en macOS; Ubuntu no tiene el comando ggrep.
O bien puedes ejecutar directamente:
Usa bin/docker-compose en lugar de docker compose, para que también se encuentren los servicios de las funciones de dev.rc (mailpit, rustfs, ldap, saml, hoppscotch y grafana con Prometheus, Loki y los exportadores). Con GRAFANA_ENABLED=true, los logs de cada contenedor también están en Grafana, donde se pueden filtrar por servicio, nivel y texto, consulta Configurar herramientas de desarrollo.

Otras herramientas

Una vez que hayas terminado todo, puedes consultar la siguiente sección para añadir algunas herramientas de depuración a tu entorno de desarrollo de Overleaf.
Última modificación el 20 de noviembre de 2026