Ana içeriğe atla

Ön Koşullar

Overleaf, tüm hizmetleri Docker’da çalışan, mikro hizmet mimarisine sahip tipik bir açık kaynak projesidir. Bir Overleaf geliştirme ortamı kurmak için güçlü bir sunucuya ihtiyacınız olacaktır; aynı anda 20’den fazla konteyner çalıştırmanız gerekeceğinden en az 8 çekirdek ve 16 GB RAM’lik bir yapılandırma önerilir.
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.
Bu arada bir geliştirici olarak Docker kurulumuna zaten aşina olduğunuzu varsayıyoruz. Beklenmedik hatalarla karşılaşma olasılığını azalttığı için geliştirme amacıyla güncel ve kararlı bir Ubuntu LTS (ör. 2025–2026 döneminde Ubuntu 24.04) ve en son Docker sürümünü kullanmanızı önemle tavsiye ederiz. Özetle şunlara ihtiyacınız olacak:
  • 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 komutlar develop 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 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
Ana makinede 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:
bash
Hizmetler çalışmaya başladığında, ilk yönetici hesabını oluşturmak için http://localhost/launchpad adresini açın. 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.
Yerel birimler ve RustFS ayrı depolardır: S3_ENABLED=true ile oluşturulan bir projede false değerine geçtikten sonra geçmiş veya ikili dosya yoktur, tersi de geçerlidir. S3_ENABLED var olmadan önce çalışan bir ortamın dosyalarını RustFS’e kopyalamak için develop/README.md içindeki “Moving existing data into RustFS” adımlarını izleyin.

Bağlantı noktaları

Site, RustFS konsolu ve Hoppscotch ana makinenin 127.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:
Ayrıntılar için Sandbox Compiles Kurulumu sayfasına bakın.
SANDBOXED_COMPILES kapalıyken oluşturulan bir projenin TeX Live imajı yoktur. Varsayılan imajla derlenmeye devam eder, ancak kod ile PDF arasında geçiş “That didn’t work. Recompile and try again.” hatasıyla başarısız olur. Bu projelere bir kez TEX_LIVE_DOCKER_IMAGE imajını atayın; --commit olmadan betik yalnızca neyi değiştireceğini gösterir:
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:
macOS ana makinesinde derlemek için, 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 sonra bin/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:
Bu, tüm hizmetleri 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.
Hiçbir hizmet adı belirtilmezse tüm hizmetler geliştirme modunda başlar. Bir çeviri ekledikten veya dal değiştirdikten sonra 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 makinenin 127.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.
Ya da doğrudan şu komutla çalıştırabilirsiniz:
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.

Diğer Araçlar

Tüm bunları tamamladıktan sonra, Overleaf geliştirme ortamınıza bazı hata ayıklama araçları eklemek için sonraki bölüme başvurabilirsiniz.
Son değiştirilme tarihi 20 Kasım 2026