Langsung ke konten utama

Prasyarat

Overleaf adalah proyek open source khas dengan arsitektur microservice, di mana semua layanan berjalan di Docker. Untuk menyiapkan lingkungan pengembangan Overleaf, Anda memerlukan server yang bertenaga; konfigurasi minimal 8 core dan RAM 16GB disarankan, karena Anda perlu menjalankan lebih dari 20 kontainer secara bersamaan.
Karena server dengan 8 core CPU atau lebih biasanya mahal, sangat disarankan untuk menggunakan komputer lokal Anda untuk pengembangan.
Selain itu, sebagai pengembang, kami yakin Anda sudah familier dengan instalasi Docker. Kami sangat menyarankan penggunaan Ubuntu LTS yang terbaru dan stabil (misalnya Ubuntu 24.04 pada 2025–2026) serta Docker versi terbaru untuk pengembangan, karena hal ini mengurangi kemungkinan menemui error yang tidak terduga. Singkatnya, Anda akan membutuhkan:
  • Server/desktop yang bertenaga untuk pengembangan
  • Ubuntu LTS yang terbaru dan stabil (misalnya Ubuntu 24.04)
  • Lingkungan Docker dan Git

Tutorial Konfigurasi

Di sini, kami menggunakan Ayakaleaf Pro untuk menunjukkan cara menyiapkan lingkungan pengembangan Overleaf. Semua perintah di bawah dijalankan di direktori develop kecuali disebutkan lain.
1

Tarik Kode Sumber

Pertama-tama, mari kita clone repositorinya:
bash
2

Menyinkronkan yarn.lock

Repositori menggunakan Yarn 4 (packageManager di package.json root), dan yarn.lock-nya bisa tidak sinkron dengan file package.json. Sinkronkan setelah clone pertama dan setelah setiap perubahan package.json:
bash
bin/sync menjalankan yarn install --mode=update-lockfile di container node:24.18.1, jadi Anda tidak memerlukan Node.js di host. Jangan commit yarn.lock yang berubah.
3

Build Image Pengembangan

Bangun layanan:
bash
Jika Docker kehabisan RAM saat mem-build layanan secara paralel, buat file .env di direktori ini yang berisi COMPOSE_PARALLEL_LIMIT=1.
4

Menerapkan terjemahan

Modul Ayakaleaf Pro menyimpan terjemahannya di services/web/locales/locales_patches/, yang tidak ada di file locale yang di-commit. Terapkan sekali sebelum start pertama, atau halaman modul ini akan menampilkan kunci seperti about_to_permanently_delete_accounts alih-alih teks:
bash
Perintah ini memerlukan jq di host. Jalankan lagi setelah menambahkan terjemahan atau berganti branch, lihat Memperbarui Terjemahan i18n.
5

Jalankan Semua Microservice

Kemudian jalankan layanannya:
bash
Setelah layanan berjalan, buka http://localhost/launchpad untuk membuat akun admin pertama. Tambahkan port jika Anda mengubah OVERLEAF_PORT (lihat di bawah).
LDAP aktif secara default (LDAP_ENABLED=true di dev.rc). Launchpad kemudian menampilkan formulir admin LDAP: formulir ini hanya meminta email, dan admin tersebut setelahnya login melalui LDAP, misalnya sebagai professor / professor (professor@planetexpress.com). Pengguna uji tercantum di develop/authentication/README.md. Atur LDAP_ENABLED=false dan SAML_ENABLED=false untuk membuat admin lokal dengan kata sandi sebagai gantinya.
develop/dev.env sudah menetapkan ADMIN_PRIVILEGE_AVAILABLE=true, sehingga admin dapat membuka panel Admin tanpa penyiapan tambahan.

Konfigurasi (dev.rc)

develop/dev.rc, di samping dev.env, berisi sakelar lingkungan pengembangan, seperti overleaf.rc di Overleaf Toolkit. Ubah sebuah nilai lalu jalankan bin/dev lagi untuk menerapkannya; fitur yang dinonaktifkan juga menghentikan container-nya. Setiap fitur menyimpan docker-compose.yml dan file lainnya di foldernya sendiri: authentication/ldap, authentication/saml, mail, s3, hoppscotch, dan grafana. Fitur yang memerlukan pengaturan web tanpa variabel lingkungan memasang file ke /etc/overleaf/settings.d/, dan develop/settings.dev-env.cjs menggabungkan semuanya. Semua skrip bin/* melewati bin/docker-compose, yang menambahkan file fitur yang aktif. Panggil bin/docker-compose alih-alih docker compose saat Anda sendiri memerlukan perintah compose.
Volume lokal dan RustFS adalah penyimpanan terpisah: proyek yang dibuat dengan S3_ENABLED=true tidak memiliki riwayat atau file biner setelah beralih ke false, dan sebaliknya. Untuk menyalin file dari lingkungan yang berjalan sebelum S3_ENABLED ada ke RustFS, ikuti “Moving existing data into RustFS” di develop/README.md.

Port

Situs, konsol RustFS, dan Hoppscotch mendengarkan di 127.0.0.1 host; di mesin jarak jauh, teruskan port-nya terlebih dahulu, misalnya ssh -L 9001:localhost:9001 <host>. Situs menggunakan OVERLEAF_PORT dari dev.rc, jadi tambahkan port ke alamat di bawah jika Anda mengubahnya. Mailpit, Grafana, Mongo Express, dan RedisInsight disajikan oleh situs di path-nya sendiri melalui webpack-dev-server, sehingga tidak memerlukan port sendiri. Setelah Anda login, menu Dev tools di bilah navigasi situs menautkannya; halaman yang fiturnya dinonaktifkan di dev.rc tidak ditampilkan. Menyiapkan Alat Pengembangan menunjukkan fungsi masing-masing. S3 API (port 9000) dan SMTP (port 1025) hanya dapat dijangkau di dalam jaringan Docker. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540), dan git-bridge (8000) hanya dipublikasikan di 127.0.0.1 host.

TeX Live

Kompilasi sandbox aktif secara default: develop/dev.env menetapkan SANDBOXED_COMPILES=true serta image ghcr.io/ayaka-notes/texlive-full:2026.1 dan ghcr.io/ayaka-notes/texlive-full:2025.1. clsi tidak menarik image sendiri, jadi tarik image tersebut sekali:
Lihat Menyiapkan Sandbox Compiles untuk detailnya.
Proyek yang dibuat saat SANDBOXED_COMPILES nonaktif tidak memiliki image TeX Live. Proyek itu tetap terkompilasi dengan image default, tetapi lompat antara kode dan PDF gagal dengan “That didn’t work. Recompile and try again.” Berikan image TEX_LIVE_DOCKER_IMAGE ke proyek tersebut sekali; tanpa --commit, skrip hanya menampilkan apa yang akan diubah:
dev.env juga mengaktifkan konversi Pandoc dengan PANDOC_IMAGE=overleaf-pandoc:local. Bangun image itu sekali dari root repositori:
Untuk mengompilasi di host macOS, Anda mungkin perlu menimpa path ke socket Docker dengan membuat file .env di direktori develop yang berisi DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Pengembangan

Agar tidak perlu menjalankan bin/build && bin/up setiap kali kode berubah, Anda dapat menjalankan Overleaf Community Edition dalam mode pengembangan, di mana layanan akan diperbarui secara otomatis saat kode berubah. Untuk melakukannya, gunakan skrip bin/dev yang disertakan:
Ini akan menjalankan semua layanan menggunakan node --watch, yang akan memantau kode secara otomatis dan memulai ulang layanan bila diperlukan. Jalankan lagi setelah mengubah dev.rc. Untuk meningkatkan performa, Anda dapat menjalankan hanya sebagian layanan dalam mode pengembangan dengan memberikan daftar yang dipisahkan spasi ke skrip bin/dev:
Menjalankan layanan web dalam mode pengembangan hanya akan memperbarui layanan web saat kode backend berubah. Agar kode frontend juga diperbarui secara otomatis, pastikan untuk menjalankan layanan webpack dalam mode pengembangan juga.
Jika tidak ada layanan yang disebutkan, semua layanan akan berjalan dalam mode pengembangan. Setelah menambahkan terjemahan atau berganti branch, jalankan bin/i18n, lihat Memperbarui Terjemahan i18n.

Debugging

Saat berjalan dalam mode pengembangan, sebagian besar layanan membuka port debugging yang dapat Anda sambungkan ke debugger, seperti inspector di Chrome Dev Tools atau debugger yang terintegrasi di IDE. Tabel berikut menunjukkan port yang dibuka di 127.0.0.1 pada mesin host untuk setiap layanan: Untuk terhubung ke layanan menggunakan remote debugging Chrome, buka chrome://inspect/ dan pastikan Discover network targets dicentang. Selanjutnya klik Configure… dan tambahkan entri localhost:[service port] untuk setiap layanan yang ingin Anda hubungkan dengan debugger. Setelah menambahkan entri, layanan akan muncul sebagai Remote Target yang dapat Anda inspeksi dan debug.

Logging

Skrip bin/logs mengikuti log dan memformatnya dengan bunyan. Skrip ini juga memerlukan ggrep, yaitu nama GNU grep saat diinstal dengan Homebrew di macOS; Ubuntu tidak memiliki perintah ggrep.
Atau, Anda dapat langsung menjalankan:
Gunakan bin/docker-compose alih-alih docker compose, agar layanan dari fitur di dev.rc (mailpit, rustfs, ldap, saml, hoppscotch, dan grafana beserta Prometheus, Loki, dan exporter) juga ditemukan. Dengan GRAFANA_ENABLED=true, log setiap container juga ada di Grafana, tempat log dapat difilter berdasarkan layanan, level, dan teks, lihat Menyiapkan Alat Pengembangan.

Alat Lainnya

Setelah semuanya selesai, Anda dapat merujuk ke bagian berikutnya untuk menambahkan beberapa alat debug ke pengembangan Overleaf Anda.
Terakhir diubah pada 20 November 2026