Ön Koşullar
Overleaf, tüm hizmetleri Docker’da çalışan, mikro hizmet mimarisine sahip tipik bir açık kaynak projesidir.- Resmi Community Edition kaynak kodu GitHub Overleaf Official adresindedir.
- Overleaf-CEP kaynak kodu GitHub Yu-i-i/Overleaf adresinde mevcuttur.
- Ayakaleaf Pro, GitHub ayaka-notes/ayakaleaf-pro adresinde mevcuttur.
8 veya daha fazla CPU çekirdeğine sahip sunucular genellikle pahalı olduğundan, geliştirme için yerel bilgisayarınızı kullanmanız şiddetle önerilir.
- Geliştirme için güçlü bir sunucu/masaüstü bilgisayar
- Güncel ve kararlı bir Ubuntu LTS (ör. Ubuntu 24.04)
- Docker ve Git ortamı
Yapılandırma Eğitimi
Burada bir Overleaf geliştirme ortamının nasıl kurulacağını Ayakaleaf Pro ile gösteriyoruz. Aksi belirtilmedikçe aşağıdaki tüm komutlardevelop dizininde çalışır.
1
Kaynak Kodunu Çekin
Öncelikle depoyu klonlayalım:
bash
2
yarn.lock dosyasını eşitleme
Depo Yarn 4 kullanır (kökteki
package.json içinde packageManager) ve yarn.lock dosyası package.json dosyalarıyla uyumsuz olabilir. İlk klonlamadan sonra ve herhangi bir package.json değişikliğinden sonra eşitleyin:bash
bin/sync, yarn install --mode=update-lockfile komutunu bir node:24.18.1 konteynerinde çalıştırır, bu yüzden ana makinede Node.js gerekmez. Değişen yarn.lock dosyasını commit etmeyin.3
Geliştirme İmajını Derleyin
Servisleri derleyin:
bash
Hizmetler paralel olarak derlenirken Docker’ın RAM’i yetmezse, bu dizinde
COMPOSE_PARALLEL_LIMIT=1 içeren bir .env dosyası oluşturun.4
Çevirileri uygulama
Ayakaleaf Pro modülleri çevirilerini Ana makinede
services/web/locales/locales_patches/ içinde tutar ve commit edilmiş yerel ayar dosyaları bunları içermez. İlk başlatmadan önce bunları bir kez uygulayın; aksi hâlde bu modüllerin sayfaları metin yerine about_to_permanently_delete_accounts gibi anahtarlar gösterir:bash
jq gerektirir. Bir çeviri ekledikten veya dal değiştirdikten sonra yeniden çalıştırın, bkz. i18n Çevirilerini Güncelleme.5
Tüm Mikro Hizmetleri Başlatın
Ardından hizmetleri başlatın:Hizmetler çalışmaya başladığında, ilk yönetici hesabını oluşturmak için http://localhost/launchpad adresini açın.
bash
OVERLEAF_PORT değerini değiştirdiyseniz bağlantı noktasını ekleyin (aşağıya bakın).LDAP varsayılan olarak açıktır (
dev.rc içinde LDAP_ENABLED=true). Launchpad bu durumda LDAP yönetici formunu gösterir: yalnızca bir e-posta ister ve bu yönetici daha sonra LDAP üzerinden giriş yapar, örneğin professor / professor (professor@planetexpress.com) olarak. Test kullanıcıları develop/authentication/README.md içinde listelenmiştir. Bunun yerine parolalı yerel bir yönetici oluşturmak için LDAP_ENABLED=false ve SAML_ENABLED=false ayarlayın.develop/dev.env zaten ADMIN_PRIVILEGE_AVAILABLE=true ayarlar, bu yüzden yöneticiler ek bir ayar yapmadan yönetim panelini açabilir.Yapılandırma (dev.rc)
dev.env dosyasının yanındaki develop/dev.rc, Overleaf Toolkit’teki overleaf.rc gibi geliştirme ortamının anahtarlarını tutar. Bir değeri değiştirip uygulamak için bin/dev komutunu yeniden çalıştırın; kapatılan bir özellik konteynerlerini de durdurur.
Her özellik
docker-compose.yml dosyasını ve diğer dosyalarını kendi klasöründe tutar: authentication/ldap, authentication/saml, mail, s3, hoppscotch ve grafana. Ortam değişkeni olmayan bir web ayarına ihtiyaç duyan özellik /etc/overleaf/settings.d/ içine bir dosya bağlar ve develop/settings.dev-env.cjs hepsini birleştirir. Tüm bin/* betikleri, açık olan özelliklerin dosyalarını ekleyen bin/docker-compose üzerinden çalışır. Kendiniz bir compose komutuna ihtiyaç duyduğunuzda docker compose yerine bin/docker-compose kullanın.
Bağlantı noktaları
Site, RustFS konsolu ve Hoppscotch ana makinenin127.0.0.1 adresini dinler; uzak bir makinede önce bağlantı noktalarını yönlendirin, örneğin ssh -L 9001:localhost:9001 <host>. Site dev.rc içindeki OVERLEAF_PORT değerini kullanır, bu yüzden değiştirdiyseniz aşağıdaki adreslere bağlantı noktasını ekleyin.
Mailpit, Grafana, Mongo Express ve RedisInsight, site tarafından webpack-dev-server üzerinden kendi yollarında sunulur, bu yüzden kendi bağlantı noktalarına ihtiyaç duymazlar. Giriş yaptığınızda sitenin gezinme çubuğundaki Dev tools menüsü bunlara bağlantı verir; özelliği
dev.rc içinde kapalı olan sayfa listelenmez. Geliştirme Araçlarını Kurma her birinin ne yaptığını gösterir.
S3 API’si (bağlantı noktası 9000) ve SMTP (bağlantı noktası 1025) yalnızca Docker ağı içinden erişilebilir. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) ve git-bridge (8000) yalnızca ana makinenin 127.0.0.1 adresinde yayınlanır.
TeX Live
Korumalı alan derlemeleri varsayılan olarak açıktır:develop/dev.env, SANDBOXED_COMPILES=true ile ghcr.io/ayaka-notes/texlive-full:2026.1 ve ghcr.io/ayaka-notes/texlive-full:2025.1 imajlarını ayarlar. clsi imajları kendisi çekmez, bu yüzden bunları bir kez çekin:
dev.env ayrıca PANDOC_IMAGE=overleaf-pandoc:local ile Pandoc dönüştürmelerini açar. Bu imajı deponun kökünden bir kez derleyin:
develop dizininde DOCKER_SOCKET_PATH=/var/run/docker.sock.raw içeren bir .env dosyası oluşturarak Docker soketinin yolunu geçersiz kılmanız gerekebilir
Geliştirme
Her kod değişikliğinden sonrabin/build && bin/up çalıştırmak zorunda kalmamak için Overleaf Community Edition’ı, hizmetlerin kod değişikliklerinde otomatik olarak güncellendiği geliştirme modunda çalıştırabilirsiniz.
Bunu yapmak için birlikte gelen bin/dev betiğini kullanın:
node --watch kullanarak başlatır; bu da kodu otomatik olarak izler ve gerektiğinde hizmetleri yeniden başlatır. dev.rc dosyasını değiştirdikten sonra yeniden çalıştırın.
Performansı artırmak için bin/dev betiğine boşlukla ayrılmış bir liste vererek hizmetlerin yalnızca bir alt kümesini geliştirme modunda başlatabilirsiniz:
web hizmetini geliştirme modunda başlatmak, web hizmetini yalnızca arka uç kodu değiştiğinde günceller. Ön uç kodunun da otomatik olarak güncellenmesi için webpack hizmetini de geliştirme modunda başlattığınızdan emin olun.bin/i18n çalıştırın, bkz. i18n Çevirilerini Güncelleme.
Hata Ayıklama
Geliştirme modunda çalışırken çoğu servis, Chrome Dev Tools’taki inspector veya bir IDE’ye entegre edilmiş hata ayıklayıcı gibi bir hata ayıklayıcı bağlayabileceğiniz bir hata ayıklama bağlantı noktası açar. Aşağıdaki tablo her servis için ana makinenin127.0.0.1 adresinde açılan bağlantı noktasını gösterir:
Chrome’un uzaktan hata ayıklama özelliğini kullanarak bir hizmete bağlanmak için chrome://inspect/ adresine gidin ve Discover network targets seçeneğinin işaretli olduğundan emin olun. Ardından Configure… öğesine tıklayın ve hata ayıklayıcı bağlamak istediğiniz her hizmet için
localhost:[service port] girdisi ekleyin.
Bir girdi ekledikten sonra hizmet, denetleyebileceğiniz ve hata ayıklayabileceğiniz bir Remote Target olarak görünür.
Günlük Kaydı
bin/logs betiği günlükleri izler ve bunyan ile biçimlendirir. Ayrıca macOS’ta Homebrew ile kurulduğunda GNU grep’in adı olan ggrep gerektirir; Ubuntu’da ggrep komutu yoktur.
dev.rc içindeki özelliklerin servislerinin (mailpit, rustfs, ldap, saml, hoppscotch ve Prometheus, Loki ve exporter’larla birlikte grafana) de bulunması için docker compose yerine bin/docker-compose kullanın.
GRAFANA_ENABLED=true ile her konteynerin günlükleri Grafana’da da bulunur; burada servise, düzeye ve metne göre filtrelenebilirler, bkz. Geliştirme Araçlarını Kurma.

