Ana içeriğe atla
Ayakaleaf Pro, kurumsal güvenlik için derlemeleri güvenli bir sandbox ortamında çalıştırma seçeneğiyle birlikte gelir. Bunu, her projeyi kendi güvenli Docker ortamında çalıştırarak yapar.

Gelişmiş güvenlik

Birçok LaTeX belgesi, PDF derleme sürecinin bir parçası olarak rastgele kabuk komutları çalıştırmayı gerektirdiğinden/çalıştırabildiğinden, Sandboxed Compiles (Sandbox Derlemeleri) Ayakaleaf Pro için önerilen yaklaşımdır. Sandboxed Compiles kullanırsanız her derleme, başka hiçbir kullanıcı veya projeyle paylaşılmayan, kısıtlı yeteneklere sahip ve ana makine ağı gibi dış kaynaklara erişimi olmayan ayrı bir Docker konteynerinde çalışır.
Ayakaleaf Pro’yu Sandboxed Compiles olmadan çalıştırmaya çalışırsanız, derleme ana Docker konteyneri içinde diğer eşzamanlı derlemelerle birlikte çalışır ve kullanıcılar LaTeX derlemeleri çalıştırırken sharelatex konteynerinin kaynaklarına (dosya sistemi, ağ ve ortam değişkenleri) tam okuma ve yazma erişimine sahip olur.

Daha kolay paket yönetimi

Paketleri elle kurmaktan kaçınmak için Sandboxed Compiles özelliğini etkinleştirmenizi öneririz. Bu, Ayakaleaf Pro içinde yapılandırılabilen bir ayardır ve kullanıcılarınıza overleaf.com’dakiyle aynı TeX Live ortamına, ancak kendi şirket içi kurulumunuzda erişim sağlar. Sandboxed Compiles tarafından kullanılan TeX Live imajları, galeri şablonlarımızla test edilmiş en popüler paketleri ve yazı tiplerini içerir ve şirket içi projelerle en yüksek uyumluluğu sağlar. Sandboxed Compiles’ı etkinleştirmek, kullanıcıların projelerinde hangi TeX Live sürümleri arasından seçim yapabileceğini yapılandırmanıza ve yeni projeler için varsayılan bir TeX Live imaj sürümü belirlemenize olanak tanır.
Ayakaleaf Pro’yu Sandboxed Compiles olmadan çalıştırmaya çalışırsanız, örneğiniz derlemeler için varsayılan olarak TeX Live’ın basic scheme sürümünü kullanır. Bu temel sürüm hafiftir ve LaTeX paketlerinin yalnızca çok sınırlı bir alt kümesini içerir; bu da büyük olasılıkla kullanıcılarınız için, özellikle hazır şablonları kullanmaya çalıştıklarında, eksik paket hatalarına yol açar.
Ayakaleaf Pro çevrimdışı çalışacak şekilde tasarlandığından, overleaf.com galeri şablonlarını şirket içi kurulumunuza entegre etmenin otomatik bir yolu yoktur; ancak bunu şablon bazında elle yapmak mümkündür. Bunun nasıl çalıştığı hakkında daha fazla bilgi için lütfen overleaf.com’dan şablon aktarma kılavuzumuza göz atın: #transferring-templates-from-overleaf.com.
Sandboxed Compiles, sharelatex konteynerinin bu kardeş derleme konteynerlerini yönetebilmesi için ana makinedeki Docker soketine (bir bind mount aracılığıyla) erişimi olmasını gerektirir.

Nasıl çalışır

Sandboxed Compiles etkinleştirildiğinde, Docker soketi ana makineden sharelatex konteynerine bağlanır; böylece konteynerdeki derleyici servisi ana makinede yeni Docker konteynerleri oluşturabilir. Ardından her projedeki her derleme çalıştırması için LaTeX derleyici servisi (CLSI) şunları yapar:
  • Proje dosyalarını OVERLEAF_DATA_PATH içindeki bir konuma yazar.
  • Derleme çalıştırması için yeni bir texlive konteyneri oluşturmak üzere bağlanan Docker soketini kullanır.
  • texlive konteynerinin proje verilerini OVERLEAF_DATA_PATH altındaki konumdan okumasını sağlar.
  • Projeyi texlive konteyneri içinde derler.

Sandboxed Compiles’ı Etkinleştirme

Toolkit Kullanıcıları İçin

Sandbox derlemelerini (Sibling containers / kardeş konteynerler olarak da bilinir) etkinleştirmek için overleaf-toolkit/config/overleaf.rc içinde aşağıdaki yapılandırma seçeneklerini ayarlayın:
config/overleaf.rc
Bunları devre dışı bırakmak için SIBLING_CONTAINERS_ENABLED=false ayarlayın ve bin/up çalıştırın. Derlemeler bu durumda sharelatex kapsayıcısı içinde, onun temel TeX Live’ı ile çalışır.

Docker Compose Kullanıcıları İçin

TexLive İmajını Ayarlama

Çin anakarasındaki kullanıcılar, indirmeyi hızlandırmak için imajları ghcr.nju.edu.cn aynasından çekebilir, ardından bunları ghcr.io adlarıyla etiketleyebilir:
Toolkit ortam ayarlarınızda ghcr.nju.edu.cn adresini KULLANMAYIN: orada ghcr.io adlarını koruyun. bin/up komutunun imajları ghcr.io adresinden yeniden çekmesini durdurmak için config/overleaf.rc içinde SIBLING_CONTAINERS_PULL=false ayarlayın. İmajları ayna üzerinden güncel tutmak için bkz. TeX Live Full İmajlarını Otomatik Olarak Güncelleme.
Ayakaleaf Pro, Sandboxed Compiles için hangi TeX Live imajlarının kullanılacağını belirlemek üzere üç ortam değişkeni kullanır:
  • TEX_LIVE_DOCKER_IMAGE (isteğe bağlı), Yeni projeler tarafından kullanılan TeX Live imajı. ALL_TEX_LIVE_DOCKER_IMAGES içindeki imajlardan biri olmalıdır. Ayarlanmazsa yeni projeler ALL_TEX_LIVE_DOCKER_IMAGES içindeki ilk imajı kullanır.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (isteğe bağlı), Derleyici ayarlarında gösterilen, imajlarla aynı sırada, virgülle ayrılmış adlar listesi. Ayarlanmazsa veya imaj listesinden kısaysa, imaj etiketiyle gösterilir, örneğin 2026.1.
  • ALL_TEX_LIVE_DOCKER_IMAGES (zorunlu), Kullanılacak TeX Live imajlarının virgülle ayrılmış listesi. Dağıtım için Overleaf Toolkit kullanılıyorsa bu imajlar indirilir veya güncellenir. İndirmeyi atlamak için config/overleaf.rc içinde SIBLING_CONTAINERS_PULL=false ayarlayın.
Ayakaleaf Pro örneğinizi bin/up komutuyla başlattığınızda Toolkit, ALL_TEX_LIVE_DOCKER_IMAGES içinde listelenen tüm imajları otomatik olarak çeker. Aşağıda, yeni projeler için varsayılan olarak TeX Live 2026’yı kullandığımız ve eski projeler için 2025’i kullanmaya devam ettiğimiz bir örnek yer almaktadır.
Aşağıdaki yapılandırma 2025’ten 2026’ya kadar tüm tam TeX Live Docker imajlarını kurar. Bu yapılandırmayı kullanmadan önce en az 64 GB boş depolama alanına sahip olmanızı öneririz.
config/variables.env
En az 2 texlive-full imajı ayarlamanız şiddetle önerilir. Ayrıntılı neden için #known-issues bölümüne bakın.

Kullanılabilir TeX Live imajları

Aşağıdakiler, Overleaf için özel olarak optimize edilmiş ve TEX_LIVE_DOCKER_IMAGE ile ALL_TEX_LIVE_DOCKER_IMAGES değişkenlerine de eklenebilen bir dizi TeX Live imajıdır:
  • ghcr.io/ayaka-notes/texlive-full:2026.1 (Ayrıca latest etiketi)
  • ghcr.io/ayaka-notes/texlive-full:2025.1
  • ghcr.io/ayaka-notes/texlive-full:2024.1
  • ghcr.io/ayaka-notes/texlive-full:2023.1
  • ghcr.io/ayaka-notes/texlive-full:2022.1
  • ghcr.io/ayaka-notes/texlive-full:2021.1
  • ghcr.io/ayaka-notes/texlive-full:2020.1
İmajların nasıl etiketlenmesi gerektiğine dair katı bir şema vardır (^[0-9]+.[0-9]+ düzenli ifadesi geçerlidir; burada ilk sayı TeX Live yılını, ikinci sayı ise yama sürümünü belirler).

Başka Bir İmaj Kayıt Defteri (Registry) Kullanabilir miyim?

Bazı kişiler ghcr.io adresini başka bir yansı (mirror) siteyle değiştirip değiştiremeyeceklerini veya texlive’ı Docker Hub’daki başka bir imaja geçirip geçiremeyeceklerini merak edebilir.
Hayır, yapılandırma görece karmaşık olduğundan bunu önermiyoruz. Bir yansı siteden indiriyorsanız imajınızı ghcr.io/ayaka-notes/texlive-full olarak yeniden adlandırabilirsiniz. Ancak gerçekten kendi imaj kayıt defterinizi kullanmak istiyorsanız lütfen şunu ekleyin:
config/variables.env
Ardından tüm texlive imajlarının your-repo içinde bulunduğundan emin olmanız gerekir, örneğin:
  • hub.your.com/your-repo/texlive-full:2025.1
  • hub.your.com/your-repo/texlive-full:2024.1
Ayrıntılı bilgi için, ortam değişkeninizi nasıl ayrıştırdığımızı anlamak üzere aşağıdaki kaynak kodu okuyun:
sandboxed-compiles/index.mjs

Otomatik TeX Live İmajı Senkronizasyonu

Örneğinizi her seferinde bin/up ile elle güncellemekten kaçınmak için TeX Live imajınızın güncellemelerini otomatikleştirebilirsiniz. Bkz. updating-tex-live-full-images-automatically.md.

Bilinen Sorunlar

Overleaf topluluğundan gerçek bir vaka:
6.0.1-ext-v3.3 kullanıyorum ve variables.env içinde şu ayarlar var:
Bu, texlive/texlive:latest-full ile sorunsuz çalışıyor. Ancak başka bir texlive imajı olan danteev/texlive:2025-10-15 imajını çektim ve her iki değişkeni de yeni imaj adıyla değiştirdim, fakat çalışmıyor:
Günlüklerde şunu görüyorum:
Görünüşe göre variables.env içindeki güncellenmiş ayarlar etkili olmuyor. Derleme hâlâ yeni imajı değil, texlive/texlive:latest-full imajını çalıştırmaya çalışıyor. Yeniden başlatmayı, konteynerleri silip yeniden çalıştırmayı denedim, ama sorun aynı. Herhangi bir çözüm var mı?
Bazı teknik sınırlamalar nedeniyle, texlive-fullA:latest gibi yalnızca tek bir Docker TeXLive imajı ayarlarsanız
ve Overleaf örneğinizi bir süre çalıştırdıktan sonra TeXLive imajını texlive-fullB:latest olarak değiştirmek isterseniz, kullanıcılarınızın hiçbir projeyi derleyemediğini görürsünüz.
Bunun nedeni, her projedeki TeXLive-Full imajının adının (sandbox derlemesi için) veritabanında kalıcı olarak saklanmasıdır. İmaj adı veritabanında yalnızca kullanıcı projesinin TeXLive sürümünü değiştirdiğinde (örneğin 2024’ten 2025’e) değişir. CLSI bir projeyi derlerken, projeyi doğrudan derlemek için veritabanında bulunan konteyner imajı adını kullanır. Yalnızca bir Docker imajı sağlarsanız, kullanıcılar projeyi derlemek için kullanılan imajı değiştiremez. Bu durumda MongoDB’deki tüm kullanıcı projelerinin TeXLive imajını elle değiştirmek için bir betik yazmanız gerekir.

Hata Ayıklama ve Bildirme

Toolkit üzerinden clsi günlüğünü kontrol etmek için aşağıdaki komutu çalıştırın:
TeX Live imajlarıyla derleme yaparken herhangi bir sorunla karşılaşırsanız lütfen buradan bir issue gönderin: https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml Sorunu yeniden oluşturup gidermemize yardımcı olmak için projenizi Overleaf’e yüklemeniz istenebilir. Ardından projeyi çekip GitHub Action ile derleme testleri çalıştıracağız.

Soru&Cevap

Yanıt: Konteynerler ve derleme dosyaları bir gecikmeden sonra kaldırılır; TeX Live imajları ise kaldırılmaz.
  • Derleme konteynerleri (project-<project id>-<hash>) aynı projenin derlemelerinde yeniden kullanılır; bu nedenle bir derlemeden sonra kalırlar. Her saat çalışan bir denetim, bir saatten eski olan ve projesi son bir saat içinde derlenmemiş olanları kaldırır. Bir konteyner genellikle son derlemeden bir ila iki saat sonra kaldırılmış olur. Overleaf’i yeniden başlatmak bunları kaldırmaz; bir sonraki saatlik denetim kaldırır.
  • Kelime sayımı, SyncTeX ve dönüştürme konteynerleri işleri biter bitmez kaldırılır.
  • Derleme dosyaları (data/overleaf/data/compiles ve output), bir proje bir gün boyunca kullanılmadığında kaldırılır; bu her 10 dakikada bir denetlenir. Disk alanı azaldığında bu süre adım adım yarım güne kadar kısaltılır.
  • TeX Live imajları, her derleme bunlara ihtiyaç duyduğu için hiçbir zaman kaldırılmaz. Bir imajı ALL_TEX_LIVE_DOCKER_IMAGES listesinden çıkardıktan sonra yer açmak için onu docker image rm <image> ile silin.
Bu konteynerleri elle silmeye gerek yoktur.
Yanıt: Hayır. Her derleme konteyneri yalnızca kendi projesinin derleme dizinini /compile konumuna bağlar ve ağ erişimi yoktur; ayrıca başka ana makine dizinlerini bu konteynere bağlamak için bir ayar bulunmaz. Bunun yerine projenin ihtiyaç duyduğu dosyaları projeye yükleyin.
Yanıt: Evet. ghcr.io/ayaka-notes/texlive-basic:<year>.1 (2020.1 ile 2026.1 arası), TeX Live basic şemasına ek olarak latexmk, xetex ve fontspec gibi birkaç paket içerir, ancak tam yazı tipi setini içermez. texlive-full imajından çok daha küçüktür, fakat başka paketler kullanan projelerde eksik paket hataları oluşur. TeX Live 2025 basic için:
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base bir basic imaj değildir: TeX Live içermez ve derleme yapamaz.
Yanıt: Düzenleyici bunu göstermez ve clsi günlüğü bunu yalnızca debug düzeyinde kaydeder. Yine de her derleme isteği bu bilgiyi döndürür: tarayıcının geliştirici araçlarını açın, Network sekmesine gidin, yeniden derleyin ve compile isteğini seçin. JSON yanıtında milisaniye cinsinden timings bulunur; burada compileE2E derleme hizmetindeki derlemenin tamamı, compile ise LaTeX çalıştırmasının kendisidir.
Son değiştirilme tarihi 13 Kasım 2026