Geliştirme Ortamını Kurma (Yerel)

Geliştirme ortamınızı yerel sunucunuzda veya masaüstü bilgisayarınızda kurun.

​

Ö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.
• Overleaf Pro Edition GitHub Ayaka-notes/overleaf-pro adresinde mevcuttur.

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 yapılandırılacağını göstermek için örnek olarak overleaf-cep kullanacağız.

1. Kaynak Kodunu Çekin

   Öncelikle depoyu klonlayalım:

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. package-lock.json Dosyasını Eşitleyin

   Overleaf bir dahili depoda geliştirildiğinden, bazı geliştirme sorunları nedeniyle package-lock.json dosyasının eşitliğini yitirmesi çok olasıdır. Eşitlemek için aşağıdaki komutu çalıştırmamız gerekir (yerel bir nodejs ortamınız varsa).

   bash

   npm install --package-lock-only --ignore-scripts
   

   nodejs kurulu değilse endişelenmeyin; aynı komutu doğrudan docker ile çalıştırabilirsiniz. Overleaf deposunun kök dizininden çalıştırın:

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. Geliştirme İmajını Derleyin

   Overleaf, geliştirme betiklerini saklamak için özel bir /develop dizini sağlar. Hizmetleri derlemeniz yeterlidir:

   bash

   cd ./develop
   bin/build
   

   Hizmetler paralel olarak derlenirken Docker’ın RAM’i yetmezse, bu dizinde COMPOSE_PARALLEL_LIMIT=1 içeren bir .env dosyası oluşturun.

4. Tüm Mikro Hizmetleri Başlatın

   Ardından hizmetleri başlatın:

   bash

   bin/up
   

   Hizmetler çalışmaya başladığında, ilk yönetici hesabını oluşturmak için http://localhost/launchpad adresini açın.

   bin/dev komutunu çalıştırmadan önce bin/up komutunu çalıştırmanız gerekir. Aksi halde bir dizi izin sorunuyla karşılaşabilirsiniz.

Varsayılan olarak yönetici ayrıcalığı kullanılamaz. Bunu develop/dev.env dosyasına eklemeniz gerekir. Bundan sonra Yönetici paneline erişebilirsiniz.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

PDF derlemek için, derlemeyi Docker içinde gerçekleştirecek bir TeX Live imajı oluşturmak gerekir:

docker build texlive -t texlive-full

macOS ana bilgisayarında derleme yapmak için, bu dizinde DOCKER_SOCKET_PATH=/var/run/docker.sock.raw içeren bir .env dosyası oluşturarak Docker soketinin yolunu geçersiz kılmanız gerekebilir.

Ayrıca ayaka-notes/texlive-full imajını da kullanabilirsiniz; bunun yerine texlive’ın en küçük sürümü olan base etiketini de kullanabilirsiniz.

​

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:

bin/dev

Bu, tüm hizmetleri node --watch kullanarak başlatır; bu da kodu otomatik olarak izler ve gerektiğinde hizmetleri yeniden başlatır.

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:

bin/dev [service1] [service2] ... [serviceN]

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.

​

Hata Ayıklama

Geliştirme modunda çalıştırıldığında çoğu hizmet, Chrome Dev Tools’daki denetleyici (inspector) veya bir IDE’ye entegre 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 hizmet için ana makinede açılan bağlantı noktasını gösterir:

Hizmet	Bağlantı noktası
web	9229
clsi	9230
chat	9231
contacts	9232
docstore	9233
document-updater	9234
filestore	9235
notifications	9236
real-time	9237
references	9238
history-v1	9239
project-history	9240
linked-url-proxy	9241

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ı

Geliştirme ortamında Overleaf bir bin/logs betiği sağlar; ancak bazı bağımlılıkları kurmanız gerekir:

sudo npm install -g bunyan
# Or sudo apt install node-bunyan 

Ya da doğrudan şu komutla çalıştırabilirsiniz:

docker compose logs -f [service name]

​

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.