Sandboxed Compiles

Ayakaleaf Pro hadir dengan opsi untuk menjalankan kompilasi dalam lingkungan sandbox yang aman demi keamanan tingkat enterprise. Hal ini dilakukan dengan menjalankan setiap proyek di lingkungan docker amannya sendiri.

​

Keamanan yang lebih baik

Sandboxed Compiles adalah pendekatan yang direkomendasikan untuk Ayakaleaf Pro karena banyak dokumen LaTeX memerlukan/memiliki kemampuan untuk mengeksekusi perintah shell arbitrer sebagai bagian dari proses kompilasi PDF. Jika Anda menggunakan Sandboxed Compiles, setiap kompilasi berjalan di kontainer Docker terpisah dengan kemampuan terbatas yang tidak dibagikan dengan pengguna atau proyek lain dan tidak memiliki akses ke sumber daya luar seperti jaringan host.

Jika Anda mencoba menjalankan Ayakaleaf Pro tanpa Sandboxed Compiles, kompilasi berjalan bersama kompilasi lain secara bersamaan di dalam kontainer Docker utama dan pengguna memiliki akses baca dan tulis penuh ke sumber daya kontainer sharelatex (sistem file, jaringan, dan variabel lingkungan) saat menjalankan kompilasi LaTeX.

​

Manajemen paket yang lebih mudah

Untuk menghindari instalasi paket secara manual, kami menyarankan untuk mengaktifkan Sandboxed Compiles. Ini adalah pengaturan yang dapat dikonfigurasi di Server Pro yang akan memberikan pengguna Anda akses ke lingkungan TeX Live yang sama seperti di overleaf.com, tetapi di dalam instalasi on-premise Anda sendiri. Image TeX Live yang digunakan oleh Sandboxed Compiles berisi paket dan font paling populer yang telah diuji terhadap template galeri kami, sehingga memastikan kompatibilitas maksimum dengan proyek on-premise.

Mengaktifkan Sandboxed Compiles memungkinkan Anda mengonfigurasi versi TeX Live mana yang dapat dipilih pengguna dalam proyek mereka, serta menetapkan versi image TeX Live default untuk proyek baru.

Jika Anda mencoba menjalankan Ayakaleaf Pro tanpa Sandboxed Compiles, instance Anda akan secara default menggunakan versi skema dasar TeX Live untuk kompilasi. Versi dasar ini ringan dan hanya berisi subset paket LaTeX yang sangat terbatas, yang kemungkinan besar akan menyebabkan error paket hilang bagi pengguna Anda, terutama jika mereka mencoba menggunakan template yang sudah jadi.

Karena Ayakaleaf Pro dirancang untuk bekerja secara offline, tidak ada cara otomatis untuk mengintegrasikan template galeri overleaf.com ke dalam instalasi on-premise Anda; namun, hal ini dapat dilakukan secara manual untuk setiap template. Untuk informasi lebih lanjut tentang cara kerjanya, silakan lihat panduan kami tentang memindahkan template dari overleaf.com: #transferring-templates-from-overleaf.com.

Sandboxed Compiles mengharuskan kontainer sharelatex memiliki akses ke socket Docker pada mesin host (melalui bind mount) agar dapat mengelola kontainer kompilasi saudara (sibling) ini.

​

Cara kerjanya

Ketika Sandboxed Compiles diaktifkan, socket Docker akan di-mount dari mesin host ke dalam kontainer sharelatex, sehingga layanan compiler di dalam kontainer dapat membuat kontainer Docker baru di host. Kemudian, untuk setiap kali compiler dijalankan di setiap proyek, layanan compiler LaTeX (CLSI) akan melakukan hal berikut:

• Menulis file proyek ke suatu lokasi di dalam OVERLEAF_DATA_PATH.
• Menggunakan socket Docker yang di-mount untuk membuat kontainer texlive baru untuk proses kompilasi tersebut.
• Membuat kontainer texlive membaca data proyek dari lokasi di bawah OVERLEAF_DATA_PATH.
• Mengompilasi proyek di dalam kontainer texlive.

​

Mengaktifkan Sandboxed Compiles

​

Untuk Pengguna Toolkit

Untuk mengaktifkan sandboxed compiles (juga dikenal sebagai Sibling containers), atur opsi konfigurasi berikut di overleaf-toolkit/config/overleaf.rc:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Untuk Pengguna Docker Compose

Mulai dari Overleaf CE/Server Pro 5.0.3, nama variabel lingkungan telah diubah dari SHARELATEX_* menjadi OVERLEAF_*.

Jika Anda menggunakan versi 4.x (atau lebih lama), pastikan variabel diberi prefiks yang sesuai (misalnya SHARELATEX_MONGO_URL alih-alih OVERLEAF_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"
            #...
        #...

​

Menyiapkan Image TexLive

Untuk pengguna di Tiongkok daratan, Anda dapat mengganti ghcr.io dengan ghcr.nju.edu.cn untuk mempercepat unduhan. Tetapi JANGAN menggunakan ghcr.nju.edu.cn secara langsung di pengaturan env toolkit Anda. Anda harus tetap menggunakan ghcr.io sebagai satu-satunya pilihan.

Ayakaleaf Pro menggunakan tiga variabel lingkungan untuk menentukan image TeX Live mana yang digunakan untuk Sandboxed Compiles:

• TEX_LIVE_DOCKER_IMAGE (wajib), Image TeX Live default yang digunakan untuk mengompilasi proyek baru. Image ini harus disertakan dalam ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (wajib), Daftar nama ramah untuk image yang dipisahkan koma, digunakan untuk opsi di frontend.
• ALL_TEX_LIVE_DOCKER_IMAGES (wajib), Daftar image TeX Live yang akan digunakan, dipisahkan koma. Jika Overleaf Toolkit digunakan untuk deployment, image-image ini akan diunduh atau diperbarui. Untuk melewati pengunduhan, atur SIBLING_CONTAINERS_PULL=false di config/overleaf.rc.

Saat memulai instance Ayakaleaf Pro Anda menggunakan perintah bin/up, Toolkit akan secara otomatis menarik semua image yang tercantum di ALL_TEX_LIVE_DOCKER_IMAGES.

Berikut contoh di mana kami menggunakan TeX Live 2026 sebagai default untuk proyek baru, dan tetap menggunakan 2025 untuk proyek lama.

Instalasi minimum

Konfigurasi berikut menginstal semua image Docker TeX Live lengkap dari 2025 hingga 2026. Kami menyarankan agar Anda memiliki setidaknya 64 GB ruang penyimpanan yang tersedia sebelum menggunakan konfigurasi ini.

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

Instalasi lengkap

Konfigurasi berikut menginstal semua image Docker TeX Live lengkap dari 2020 hingga 2026. Kami menyarankan agar Anda memiliki setidaknya 150 GB ruang penyimpanan yang tersedia sebelum menggunakan konfigurasi ini.

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

Sangat disarankan untuk mengatur setidaknya 2 image texlive-full. Untuk alasan selengkapnya, lihat #known-issues

​

Image TeX Live yang tersedia

Berikut adalah serangkaian image TeX Live yang dioptimalkan khusus untuk Overleaf, dan juga dapat ditambahkan ke TEX_LIVE_DOCKER_IMAGE dan ALL_TEX_LIVE_DOCKER_IMAGES:

• ghcr.io/ayaka-notes/texlive-full:2026.1 (juga tag latest)
• 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

Terdapat skema yang ketat mengenai bagaimana image harus diberi tag (berlaku regex ^[0-9]+.[0-9]+, di mana angka pertama menentukan tahun TeX Live dan angka kedua menentukan versi patch).

​

Bisakah Saya Menggunakan Image Registry Lain

Sebagian orang mungkin bertanya-tanya apakah saya dapat mengganti ghcr.io dengan situs mirror lain, atau mengganti texlive dengan image lain dari docker hub?

Tidak, kami tidak menyarankannya karena konfigurasinya relatif rumit. Jika Anda mengunduh dari situs mirror, Anda dapat mengganti nama image Anda menjadi ghcr.io/ayaka-notes/texlive-full.

Namun, jika Anda benar-benar ingin menggunakan Image Registry Anda sendiri, tambahkan:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Kemudian, Anda perlu memastikan bahwa semua image texlive berada di your-repo, seperti

• hub.your.com/your-repo/texlive-full:2025.1
• hub.your.com/your-repo/texlive-full:2024.1

Untuk informasi lebih lanjut, baca kode sumber di bawah ini untuk memahami bagaimana kami mem-parsing variabel lingkungan Anda:

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
}

​

Sinkronisasi Image TeX Live Otomatis

Untuk menghindari pembaruan manual instance Anda dengan bin/up setiap saat, Anda dapat mengotomatiskan pembaruan image TeX Live Anda. Lihat updating-tex-live-full-images-automatically.md.

​

Masalah yang Diketahui

Berikut adalah kasus nyata dari komunitas Overleaf:

Menggunakan 6.0.1-ext-v3.3, saya memiliki pengaturan berikut di variables.env:

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

Ini berfungsi dengan baik dengan texlive/texlive:latest-full. Namun, saya menarik image texlive lain danteev/texlive:2025-10-15 dan mengubah kedua variabel ini ke nama image baru, tetapi tidak berhasil:

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

Di log, saya melihat hal berikut:

{"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 ... 

Tampaknya pengaturan yang diperbarui di variables.env tidak diterapkan. Kompilasi masih mencoba menjalankan image texlive/texlive:latest-full, bukan image yang baru.

Saya sudah mencoba me-reboot, menghapus kontainer, dan menjalankannya ulang, tetapi masalahnya tetap sama.

Ada solusi?

Karena beberapa keterbatasan teknis, jika Anda hanya menyiapkan satu image Docker TeXLive, seperti texlive-fullA:latest

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

Dan setelah menjalankan instance Overleaf Anda selama beberapa waktu, Anda mungkin ingin mengubah image TeXLive menjadi texlive-fullB:latest. Kemudian, Anda akan melihat bahwa pengguna Anda tidak dapat mengompilasi semua proyek.

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

Hal ini karena nama image TeXLive-Full (untuk sandbox compile) di setiap proyek disimpan secara permanen di database. Hanya ketika pengguna mengganti versi TeXLive proyeknya, misalnya dari 2024 ke 2025, nama image di database akan berubah.

Ketika CLSI mengompilasi sebuah proyek, CLSI menggunakan nama image kontainer yang ditemukan di database untuk langsung mengompilasi proyek tersebut.

Jika Anda hanya menyediakan satu image Docker, pengguna tidak akan dapat mengubah image yang digunakan untuk mengompilasi proyek. Dalam hal ini, Anda perlu menulis skrip untuk mengubah secara manual image TeXLive untuk semua proyek pengguna di mongoDB.

​

Debug dan Pelaporan

Jalankan perintah berikut untuk memeriksa log clsi dari toolkit:

bin/logs clsi

Jika Anda mengalami masalah saat mengompilasi dengan image TeX Live, silakan kirimkan issue di sini:

https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml

Untuk membantu kami mereproduksi dan memecahkan masalah, Anda mungkin diminta untuk mengunggah proyek Anda ke Overleaf. Kami kemudian akan menarik proyek tersebut dan menjalankan pengujian kompilasi dengan GitHub Action.