Cara Install ERPNext di Docker untuk Development (Panduan Lengkap)

Ringkasan singkat: Cara paling direkomendasikan untuk menyiapkan lingkungan development ERPNext adalah menggunakan repositori resmi frappe_docker dikombinasikan dengan VS Code Dev Container. Metode ini menjalankan seluruh dependensi (MariaDB, Redis, Node.js, Python, bench) di dalam container terisolasi, tanpa perlu instalasi manual di sistem operasi host. Panduan ini menjelaskan langkah-langkahnya secara rinci, mulai dari prasyarat hingga situs ERPNext pertama Anda siap diakses di browser.

Catatan penting: Setup ini ditujukan khusus untuk development/lokal, bukan untuk production. Untuk deployment production, gunakan panduan frappe_docker bagian single/multi-bench production setup yang berbeda dari panduan ini.

---

Prasyarat

Sebelum memulai, pastikan perangkat Anda sudah memiliki:

• Docker Desktop (atau Docker Engine + Docker Compose di Linux), versi terbaru.
• Git untuk meng-clone repository.
• Visual Studio Code, ditambah ekstensi Dev Containers (ms-vscode-remote.remote-containers).
• Koneksi internet stabil (image dan dependensi akan diunduh saat build pertama kali).
• Ruang disk kosong minimal beberapa GB untuk image Docker dan dependensi Node/Python.

Jika Anda menggunakan Windows, disarankan menjalankan perintah git/bash melalui Git Bash, bukan Command Prompt atau PowerShell, agar kompatibel dengan skrip shell yang digunakan di dalam container.

Langkah 1 — Clone Repository frappe_docker

Buka terminal, lalu jalankan:

git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker

Repository ini berisi seluruh file Docker Compose, Dockerfile, dan konfigurasi dev container resmi yang dikelola langsung oleh tim Frappe.

Langkah 2 — Siapkan Konfigurasi Dev Container

Salin contoh konfigurasi dev container dan pengaturan VS Code ke lokasi aktifnya:

cp -R devcontainer-example .devcontainer
cp -R development/vscode-example development/.vscode

Folder .devcontainer inilah yang akan dibaca VS Code untuk membangun container development, sedangkan development/.vscode berisi konfigurasi debugger dan koneksi database (SQLTools) yang sudah disesuaikan untuk Frappe/ERPNext.

Langkah 3 — Buka di VS Code dan Masuk ke Dev Container

Buka folder frappe_docker di VS Code:

code .

VS Code biasanya akan otomatis mendeteksi folder .devcontainer dan menampilkan notifikasi untuk membuka ulang folder di dalam container. Jika notifikasi tidak muncul, buka Command Palette (Ctrl+Shift+P di Windows/Linux atau Cmd+Shift+P di macOS), lalu jalankan:

Dev Containers: Reopen in Container

Proses build pertama kali akan memakan waktu beberapa menit karena Docker perlu mengunduh image dan menyiapkan seluruh service pendukung (MariaDB, Redis cache, Redis queue, dan sebagainya).

Langkah 4 — Inisialisasi Bench

Setelah berada di dalam dev container, buka terminal baru di VS Code (otomatis berada di dalam container), lalu pindah ke direktori kerja:

cd /workspace/development

Inisialisasi bench baru. Sebaiknya tentukan versi Frappe secara eksplisit agar sinkron dengan versi ERPNext yang akan diinstal:

bench init --skip-redis-config-generation --frappe-branch version-15 frappe-bench
cd frappe-bench

Ganti version-15 sesuai kebutuhan (misalnya version-14 atau branch versi lain), dan pastikan versi ini konsisten dengan branch ERPNext yang akan diambil di langkah berikutnya.

Langkah 5 — Hubungkan Bench ke Container MariaDB dan Redis

Karena MariaDB dan Redis berjalan sebagai container terpisah (bukan di localhost), bench perlu diarahkan ke nama service container tersebut:

bench set-config -g db_host mariadb
bench set-config -g redis_cache redis://redis-cache:6379
bench set-config -g redis_queue redis://redis-queue:6379
bench set-config -g redis_socketio redis://redis-socketio:6379

Langkah 6 — Buat Situs Baru dan Install ERPNext

Ambil aplikasi ERPNext ke dalam bench:

bench get-app --branch version-15 --resolve-deps erpnext

Buat situs baru (ganti development.localhost sesuai preferensi domain lokal Anda):

bench new-site development.localhost \
  --db-host mariadb \
  --admin-password admin \
  --mariadb-user-host-login-scope=%

Install ERPNext ke situs yang baru dibuat:

bench --site development.localhost install-app erpnext

Opsi --mariadb-user-host-login-scope=% penting agar kredensial database situs kompatibel dengan koneksi dari dalam jaringan Docker.

Langkah 7 — Jalankan Server Development

Di dalam direktori frappe-bench, alih-alih menjalankan bench start seperti pada instalasi non-Docker, gunakan honcho untuk menjalankan proses pendukung (worker, scheduler, socketio, watcher):

honcho start socketio watch schedule worker_short worker_long

Proses web server utamanya dijalankan terpisah lewat debugger VS Code (tab Run and Debug, pilih konfigurasi yang tersedia lalu klik tombol play). Ini memungkinkan Anda memasang breakpoint dan men-debug kode Frappe/ERPNext secara langsung selama development.

Setelah web server berjalan, ERPNext dapat diakses melalui browser di alamat situs yang dibuat, misalnya http://development.localhost:8000. Jika menggunakan macOS/Linux/WSL dan domain lokal tidak dikenali browser, tambahkan entri ke file /etc/hosts yang mengarahkan development.localhost ke 127.0.0.1.

Langkah 8 — Login dan Aktifkan Developer Mode

Login menggunakan:

• Username: Administrator
• Password: sesuai yang ditentukan pada opsi --admin-password saat membuat situs (pada contoh di atas: admin).

Jika Anda berencana mengembangkan aplikasi/kustomisasi kustom (bukan hanya memakai ERPNext apa adanya), aktifkan developer mode pada situs:

bench --site development.localhost set-config developer_mode 1
bench --site development.localhost clear-cache

Developer mode diperlukan agar perubahan skrip, laporan, dan Doctype kustom dapat disimpan sebagai berkas kode (bukan hanya tersimpan di database), sehingga bisa dikelola dengan git.

Troubleshooting Umum

Container gagal start / port bentrok. Pastikan port 80, 8000, 3306, atau 6379 tidak sedang dipakai proses lain di mesin Anda. Hentikan service yang bentrok atau ubah pemetaan port di file compose.

Error terkait versi Python/library saat build (misalnya masalah kompatibilitas pypika dengan Python versi terbaru). Jika mengalami kegagalan build terkait versi Python atau tool uv bawaan image bench terbaru, coba gunakan tag image bench versi sebelumnya yang lebih stabil pada file docker-compose.yaml di dalam .devcontainer, lalu build ulang.

Situs tidak bisa diakses di browser. Periksa apakah domain lokal (misalnya development.localhost) sudah dipetakan dengan benar ke 127.0.0.1 di file hosts sistem Anda, terutama di Windows/WSL.

Bench tidak menemukan MariaDB/Redis. Pastikan langkah bench set-config -g db_host mariadb dan konfigurasi Redis pada Langkah 5 sudah dijalankan sebelum membuat situs baru.

Alternatif: Instalasi Cepat Tanpa VS Code

Bagi yang hanya ingin mencoba ERPNext dengan cepat tanpa alur devcontainer/VS Code, tersedia juga skrip installer.py otomatis di dalam folder development pada repository frappe_docker, yang akan menanyakan nama situs dan aplikasi yang ingin diinstal secara interaktif setelah dev container aktif:

cd /workspace/development
python installer.py

Metode ini cocok untuk eksplorasi cepat, sementara langkah manual pada bagian sebelumnya lebih cocok jika Anda ingin memahami/mengendalikan setiap tahapan secara rinci atau mengembangkan aplikasi kustom di atas Frappe/ERPNext.

---

FAQ Instalasi ERPNext di Docker

Apakah setup ini bisa langsung dipakai untuk production?

Tidak. Panduan ini khusus untuk kebutuhan development lokal (hot-reload, debugging, kustomisasi kode). Untuk production, frappe_docker menyediakan panduan terpisah dengan pendekatan image production dan reverse proxy (misalnya Traefik) yang berbeda konfigurasinya.

Apakah wajib menggunakan VS Code?

Tidak wajib, namun sangat direkomendasikan karena integrasi Dev Container resmi dari tim Frappe dirancang untuk VS Code, termasuk konfigurasi debugger dan koneksi database siap pakai. Tanpa VS Code, Anda perlu menjalankan container secara manual dan mengelola bench dari dalam container lewat docker exec.

Kenapa harus menentukan versi Frappe secara eksplisit saat bench init?

Karena ERPNext memiliki dependensi versi terhadap Frappe framework. Jika versi keduanya tidak sinkron (misalnya Frappe versi terbaru dipasangkan dengan ERPNext versi lama), instalasi aplikasi dapat gagal atau menimbulkan error kompatibilitas saat migrasi database.

Apa fungsi developer_mode?

Developer mode mengizinkan perubahan seperti skrip kustom, laporan, dan Doctype baru disimpan sebagai berkas kode yang dapat dikelola dengan git, bukan hanya tersimpan di database. Ini penting untuk alur kerja pengembangan aplikasi kustom di atas ERPNext.

Apakah data di dalam container akan hilang setiap kali container di-restart?

Tidak, selama Anda tidak menghapus volume Docker terkait (MariaDB data volume) dan tidak menjalankan docker compose down -v yang menghapus volume. Folder development/ di luar container juga tetap tersimpan di mesin host karena di-mount, sehingga kode bench Anda tidak hilang meski container dihentikan.

Kenapa harus pakai honcho bukan bench start?

Karena Redis pada setup Docker ini sudah berjalan sebagai container terpisah, sehingga bench start bawaan (yang mengasumsikan semua service berjalan lokal) tidak diperlukan. honcho di sini hanya menjalankan proses pendukung (worker, scheduler, socketio, watcher), sementara proses web server dijalankan terpisah lewat debugger VS Code agar breakpoint dapat digunakan.

Bisakah menggunakan PostgreSQL sebagai pengganti MariaDB?

Frappe framework mendukung PostgreSQL sejak versi tertentu untuk situs baru, namun perlu dicek kompatibilitasnya dengan versi ERPNext yang digunakan, karena tidak semua versi ERPNext mendukung PostgreSQL secara penuh. Jika ingin mencoba, konfigurasi service postgresql perlu diaktifkan pada file compose dev container sebagai pengganti mariadb.

Apakah bisa install banyak custom app sekaligus di bench yang sama?

Bisa. Setelah bench diinisialisasi, aplikasi tambahan dapat diambil dengan bench get-app <nama-app> dan diinstal ke situs dengan bench --site <nama-situs> install-app <nama-app>, selama kompatibel dengan versi Frappe yang digunakan.

---

Panduan ini bersifat teknis untuk kebutuhan pengembangan (development) ERPNext secara lokal. Untuk kebutuhan deployment production, migrasi data, atau kustomisasi tingkat lanjut yang melibatkan proses bisnis nyata, disarankan berkoordinasi dengan tim developer atau mitra implementasi ERPNext berpengalaman.