Sandbox Derlemeleri

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, Server 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

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Docker Compose Kullanıcıları İçin

Overleaf CE/Server Pro 5.0.3 sürümünden itibaren ortam değişkenleri SHARELATEX_* yerine OVERLEAF_* olarak yeniden adlandırılmıştır.

4.x (veya daha eski) bir sürüm kullanıyorsanız, lütfen değişkenlerin uygun önekle başladığından emin olun (ör. OVERLEAF_MONGO_URL yerine SHARELATEX_MONGO_URL).

version: '2'
services:
    sharelatex:
        #...
        volumes:
            - /data/overleaf_data:/var/lib/overleaf
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            #...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
            #...
        #...

​

TexLive İmajını Ayarlama

Çin anakarasındaki kullanıcılar, indirmeyi hızlandırmak için ghcr.io yerine ghcr.nju.edu.cn kullanabilir. Ancak toolkit ortam ayarlarınızda ghcr.nju.edu.cn adresini doğrudan KULLANMAYIN. Tek seçeneğiniz olarak ghcr.io adresini korumalısınız.

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 (zorunlu), Yeni projeleri derlemek için kullanılan varsayılan TeX Live imajı. Bu imaj ALL_TEX_LIVE_DOCKER_IMAGES içinde yer almalıdır.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (zorunlu), İmajlar için ön yüz seçeneklerinde kullanılan, virgülle ayrılmış kullanıcı dostu adlar listesi.
• 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.

Minimum kurulum

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

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1, ghcr.io/ayaka-notes/texlive-full:2025.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026, Texlive 2025
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

Tam kurulum

Aşağıdaki yapılandırma 2020’den 2026’ya kadar tüm tam TeX Live Docker imajlarını kurar. Bu yapılandırmayı kullanmadan önce en az 150 GB boş depolama alanına sahip olmanızı öneririz.

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1,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
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026,Texlive 2025,Texlive 2024,Texlive 2023,Texlive 2022,Texlive 2021,Texlive 2020
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

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

IMAGE_ROOT=hub.your.com/your-repo

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

if (process.env.SANDBOXED_COMPILES === 'true') {
  // Set default image root if not provided
  let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes";
  // Export imageRoot to Settings
  Settings.imageRoot = imageRootPath

  // allowedImageNames should be:
  // [
  //  { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" },
  //  { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" },
  // ]
  Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES)
    .map((texImage, index) => ({
      imageName: texImage.split("/")[texImage.split("/").length - 1],
      imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index]
        || texImage.split(':')[1],
    }))
  
  // In the end, imageName will be put together with imageRoot to form the full image path
  // The full name will be like: ghcr.io/ayaka-notes/texlive-2023:latest

  // Set default image name if not provided
  if(!process.env.TEX_LIVE_DOCKER_IMAGE) {
    process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName
  }

  // Export currentImageName to Settings
  // This is the new created projects' image name
  Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE
}

​

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:

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

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:

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

Günlüklerde şunu görüyorum:

{"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ... 

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

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

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.

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

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:

bin/logs clsi

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.