Langsung ke konten utama
Ayakaleaf Pro mendukung penskalaan horizontal. Kami telah menguji dan memverifikasi bahwa Ayakaleaf Pro berjalan dengan benar dengan beberapa replika.
Dokumen ini mencantumkan persyaratan teknis dan memberikan panduan untuk menjalankan Ayakaleaf Pro di lebih dari satu node. Menyiapkan penskalaan horizontal memerlukan upaya yang cukup besar. Kami menyarankan untuk mempertimbangkan penskalaan horizontal hanya ketika mencapai skala tertentu. Sebagai contoh, Overleaf melaporkan sebuah instalasi on-premise untuk total 1.000 pengguna yang berjalan dengan baik pada satu server dengan dua prosesor 4-core dan memori sistem 32GB. Lihat dokumentasi persyaratan perangkat keras untuk rekomendasi. Penerapan Ayakaleaf Pro dengan penskalaan horizontal melibatkan sejumlah komponen eksternal, seperti Load Balancer dan backend penyimpanan yang kompatibel dengan S3.

Persyaratan

Penyimpanan data eksternal terpusat

Penyimpanan data di Ayakaleaf Pro dapat dibagi menjadi empat penyimpanan data:
  • MongoDB
    • Sebagian besar data disimpan secara persisten di MongoDB.
    • Kami mendukung instans lokal maupun instans eksternal, seperti MongoDB Atlas (layanan MongoDB yang dikelola sepenuhnya dan berjalan di dalam infrastruktur AWS).
    Catatan: Sayangnya, saat ini tidak ada dukungan resmi untuk database yang kompatibel dengan MongoDB seperti CosmoDB/DocumentDB, karena kami belum menguji Ayakaleaf Pro dengan database tersebut. Meskipun menerapkan Ayakaleaf Pro dengan database yang kompatibel mungkin dapat dilakukan, kami hanya secara resmi mendukung penerapan yang menggunakan MongoDB.
  • Redis
    • Redis menyimpan data sementara, seperti pembaruan dokumen yang tertunda sebelum di-flush ke MongoDB.
    • Redis digunakan untuk mengomunikasikan pembaruan dokumen antar layanan yang berbeda dan memberi tahu editor tentang perubahan status dalam suatu proyek.
    • Redis digunakan untuk menyimpan sesi pengguna.
    • Kami mendukung instans lokal maupun instans eksternal.
    Catatan: Sayangnya, saat ini tidak ada dukungan resmi untuk penyimpanan key/value yang kompatibel dengan Redis seperti KeyDB/Valkey, karena kami belum menguji Ayakaleaf Pro dengan penyimpanan tersebut. Meskipun menerapkan Ayakaleaf Pro dengan penyimpanan yang kompatibel mungkin dapat dilakukan, kami hanya secara resmi mendukung penerapan yang menggunakan Redis.
  • File proyek dan file History
    • File proyek yang tidak dapat diedit disimpan di luar MongoDB. Sistem riwayat proyek juga menyimpan riwayat di luar MongoDB.
    • Untuk instans tunggal yang kecil, kami mendukung sistem file lokal (yang dapat didukung oleh SSD lokal, NFS, atau EBS) maupun sistem penyimpanan data yang kompatibel dengan S3.
    • Untuk penskalaan horizontal, kami hanya mendukung sistem penyimpanan data yang kompatibel dengan S3.
    Penting: NFS/Amazon EFS/Amazon EBS tidak didukung untuk penskalaan horizontal. Silakan lihat bagian persyaratan penyimpanan perangkat keras tentang penskalaan penyimpanan di Ayakaleaf Pro untuk detail lebih lanjut.
  • File sementara (ephemeral)
    • Kompilasi LaTeX perlu berjalan pada disk lokal yang cepat untuk kinerja optimal. Output kompilasi tidak perlu disimpan secara persisten atau dicadangkan.
    • Buffering unggahan file baru dan pembuatan file zip proyek juga mendapat manfaat dari penggunaan disk lokal.
Kami sangat menyarankan penggunaan disk lokal. Menggunakan jenis disk jaringan apa pun (seperti NFS atau EBS) dapat mengakibatkan error kompilasi yang tidak terduga dan masalah kinerja lainnya.

Git-bridge

Repositori git disimpan secara lokal di disk. Tidak ada opsi replikasi yang tersedia. Git-bridge harus dijalankan sebagai singleton. Untuk kinerja optimal, kami menyarankan penggunaan disk lokal untuk data git-bridge. Disk data git-bridge harus dicadangkan secara rutin. Untuk penyimpanan data dengan penskalaan horizontal, Anda memerlukan:
  • instans MongoDB terpusat yang dapat diakses dari semua instans Ayakaleaf Pro
  • instans Redis terpusat yang dapat diakses dari semua instans Ayakaleaf Pro
  • backend penyimpanan terpusat yang kompatibel dengan S3 untuk file proyek dan file riwayat
  • disk lokal di setiap instans untuk file sementara
  • disk lokal di instans yang meng-host kontainer git-bridge untuk data git-bridge

Persyaratan load balancer

  • Routing persisten, misalnya menggunakan cookie Persyaratan ini berasal dari komponen-komponen berikut:
    • Kemampuan penyuntingan real-time di Ayakaleaf Pro menggunakan WebSockets dengan fallback ke XHR polling. Setiap sesi penyuntingan memiliki state lokal di sisi server dan permintaan dari suatu sesi penyuntingan harus selalu dirutekan ke instans Ayakaleaf Pro yang sama. Fitur kolaborasi menggunakan Redis Pub/Sub untuk berbagi pembaruan antar beberapa instans Ayakaleaf Pro.
    • Kompilasi LaTeX menyimpan output dan cache kompilasi secara lokal untuk kinerja yang optimal. Setelah mengirim permintaan kompilasi ke satu instans Ayakaleaf Pro, permintaan unduhan PDF/log berikutnya harus dirutekan ke instans Ayakaleaf Pro yang sama.
  • Batas waktu permintaan yang panjang untuk mendukung kompilasi dokumen LaTeX yang besar
  • Dukungan WebSocket untuk kinerja optimal
  • Ukuran payload POST sebesar 50MB
  • Batas waktu keep-alive harus lebih rendah dari batas waktu keep-alive Ayakaleaf Pro Batas waktu keep-alive di Ayakaleaf Pro dapat dikonfigurasi menggunakan variabel lingkungan NGINX_KEEPALIVE_TIMEOUT. Nilai default-nya adalah 65 detik. Dengan nilai default, batas waktu keep-alive 60 detik pada load balancer akan berfungsi. Dengan NGINX_KEEPALIVE_TIMEOUT=120, load balancer dapat menggunakan 115 detik.
  • IP klien Atur header permintaan X-Forwarded-For ke IP klien.
  • Saat mengakhiri SSL (SSL termination) Load balancer perlu menambahkan header permintaan X-Forwarded-Proto: https.

Konfigurasi Ayakaleaf Pro

Secret Instans-instans Ayakaleaf Pro perlu menggunakan secret bersama yang sama:
  • WEB_API_PASSWORD (autentikasi web api)
  • STAGING_PASSWORD dan V1_HISTORY_PASSWORD dengan nilai yang sama (autentikasi history)
  • CRYPTO_RANDOM (untuk cookie sesi)
  • OT_JWT_AUTH_KEY (autentikasi history)
  • OVERLEAF_INVITE_TOKEN_SECRET (token berbagi tautan, wajib: tanpanya Ayakaleaf Pro menolak untuk berjalan)
Semua secret ini perlu dikonfigurasi dengan nilai uniknya masing-masing dan dibagikan di antara instans-instans. Jika tidak dikonfigurasi dan permintaan pengguna dirutekan ke instans Ayakaleaf Pro yang berbeda, permintaan mereka akan gagal dalam pemeriksaan autentikasi dan mereka akan sering diarahkan ke halaman login atau tindakan mereka di UI akan gagal dengan cara yang tidak terduga. Jika tidak dikonfigurasi, Ayakaleaf Pro menggunakan nilai acak baru untuk setiap secret berdasarkan 32 byte acak dari /dev/urandom (256 bit acak).
MongoDB Arahkan OVERLEAF_MONGO_URL ke instans MongoDB terpusat. Redis Arahkan OVERLEAF_REDIS_HOST dan REDIS_HOST ke instans Redis terpusat. Penyimpanan yang kompatibel dengan S3 untuk file proyek dan file riwayat Silakan lihat dokumentasi tentang penyimpanan yang kompatibel dengan S3 untuk detailnya. File sementara (ephemeral) Bind-mount default dari SSD lokal ke /var/lib/overleaf sudah cukup. Pastikan untuk mengarahkan SANDBOXED_COMPILES_HOST_DIR ke titik mount di host.
Kami sangat menyarankan penggunaan disk lokal. Menggunakan jenis disk jaringan apa pun (seperti NFS atau EBS) dapat mengakibatkan error kompilasi yang tidak terduga dan masalah kinerja lainnya.
Konfigurasi proxy
  • Atur OVERLEAF_TRUSTED_PROXY_IPS ke loopback ditambah IP load balancer, misalnya loopback,198.18.0.1, untuk mendapatkan IP klien yang akurat. Beberapa IP atau CIDR dapat ditentukan, dipisahkan dengan koma.
Integrasi Git-bridge Kontainer git-bridge memerlukan kontainer Ayakaleaf Pro pendamping (sibling) untuk menangani permintaan git yang masuk. Kontainer pendamping ini juga dapat melayani lalu lintas pengguna biasa. Dalam contoh konfigurasi, instans pertama berperan sebagai kontainer pendamping untuk git-bridge, tetapi sebenarnya instans mana pun dapat menjalankan fungsi tersebut. Mengapa kita perlu menunjuk satu kontainer Ayakaleaf Pro sebagai pendamping untuk git-bridge? Ayakaleaf Pro memberikan URL unduhan untuk layanan history kepada git-bridge. Kita perlu mengonfigurasi URL history ini agar dapat diakses dari kontainer git-bridge. Konfigurasi kontainer Ayakaleaf Pro:
  • Atur GIT_BRIDGE_ENABLED ke 'true'
  • Atur GIT_BRIDGE_HOST ke <git-bridge container name>, misalnya git-bridge
  • Atur GIT_BRIDGE_PORT ke 8000
  • Atur V1_HISTORY_URL ke http://<server-pro sibling container name>:3100/api. Catatan: Ini hanya diperlukan pada kontainer pendamping untuk kontainer git-bridge. Instans lainnya dapat menggunakan URL localhost, yang merupakan nilai default.
Konfigurasi kontainer git-bridge:
  • Atur GIT_BRIDGE_API_BASE_URL ke http://<server-pro sibling container name>/api/v0, misalnya http://server-pro-ha-1/api/v0
  • Atur GIT_BRIDGE_OAUTH2_SERVER ke http://<server-pro sibling container name>, misalnya http://server-pro-ha-1
  • Atur GIT_BRIDGE_POSTBACK_BASE_URL ke http://<git-bridge container name>:8000, misalnya http://git-bridge:8000
  • Atur GIT_BRIDGE_ROOT_DIR ke disk data git-bridge yang di-bind-mount, misalnya /data/git-bridge
Konfigurasi berikut menunjukkan penyiapan yang mandiri (self-contained). Agar demo berfungsi, Anda perlu menyediakan kunci/sertifikat SSL yang valid dan menyesuaikan OVERLEAF_SITE_URL. Untuk penyiapan sungguhan, Anda harus mengganti secret contoh dengan secret yang sebenarnya seperti yang dicatat di dalam konfigurasi. Untuk penyiapan sungguhan, Anda perlu memindahkan setiap kontainer ke node khusus dan menyesuaikan alamat IP dengan penyiapan jaringan lokal Anda.Kompilasi berjalan di kontainer TeX Live di samping setiap instans Ayakaleaf Pro. Tarik terlebih dahulu image TeX Live di setiap host Ayakaleaf Pro, misalnya docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Perangkat keras

Kami menyarankan penggunaan spesifikasi perangkat keras yang sama untuk semua instans Ayakaleaf Pro yang terlibat dalam penskalaan horizontal. Rekomendasi umum tentang spesifikasi perangkat keras untuk instans Ayakaleaf Pro tetap berlaku.

Meningkatkan Ayakaleaf Pro

Sebagai bagian dari proses peningkatan, Ayakaleaf Pro secara otomatis menjalankan migrasi database. Migrasi ini tidak dirancang untuk dijalankan dari beberapa instans secara paralel. Migrasi harus selesai sebelum aplikasi web yang sebenarnya dimulai. Anda dapat memeriksa log untuk entri Finished migrations atau menunggu hingga aplikasi menerima lalu lintas. Prosedur peningkatan terlihat seperti ini:
  1. Jadwalkan jendela pemeliharaan
  2. Hentikan semua instans Ayakaleaf Pro
  3. Buat cadangan yang konsisten seperti yang dijelaskan dalam dokumentasi
  4. Jalankan satu instans Ayakaleaf Pro dengan versi baru
  5. Validasi bahwa instans baru berfungsi seperti yang diharapkan
  6. Jalankan instans-instans lainnya dengan versi baru
Terakhir diubah pada 2 November 2026