Menginstall Frappe dan ERPNext di lokal itu seperti merakit mesin: banyak komponennya, urutan pemasangannya penting, dan satu versi yang tidak cocok bisa membuat semuanya gagal jalan. Tulisan ini saya susun dari pengalaman membangun bench development di Mac saya sendiri, yang sampai hari ini menampung belasan aplikasi Frappe termasuk ERPNext v16, HRMS, dan CRM sekaligus. Saya tulis semua langkahnya secara berurutan lengkap dengan jebakan yang pernah saya jatuh ke dalamnya, supaya Anda tidak mengulang kesalahan yang sama.
Apa itu Frappe, Bench, dan ERPNext
Sebelum masuk ke terminal, penting memahami tiga istilah ini karena sering tertukar. Frappe Framework adalah framework fullstack Python dan JavaScript yang menjadi fondasi semuanya: dia yang mengurus DocType, ORM, REST API, sampai server rendering. Bench adalah command line tool sekaligus struktur direktori yang mengelola satu atau banyak situs Frappe sekaligus, mirip konsep workspace. ERPNext adalah aplikasi bisnis lengkap yang dibangun di atas Frappe: akuntansi, inventori, pembelian, penjualan, sampai payroll lewat modul HRMS.
Hubungannya berlapis: bench mengelola situs, situs menjalankan aplikasi, aplikasi dibangun di atas framework. Satu bench bisa berisi banyak situs dengan kombinasi aplikasi berbeda, dan semua berbagi satu environment Python serta satu set proses Redis. Memahami layering ini akan sangat membantu saat debugging nanti.
Persiapan sistem
Frappe v16 butuh Python 3.12 ke atas. Bench development saya sendiri berjalan di Python 3.14 dan tidak ada masalah, jadi jangan takut memakai versi baru selama minimal requirement terpenuhi. Selain Python, komponen wajibnya: Node.js 20 atau lebih baru untuk asset build dan realtime socket, MariaDB 10.6+ atau PostgreSQL 14+ sebagai database, Redis untuk cache dan queue, ImageMagick untuk pemrosesan gambar, dan git untuk mengambil source code aplikasi.
Untuk pengguna Mac, semua bisa dipasang lewat Homebrew: brew install python@3.14 node mariadb redis. Di Mac saya, MariaDB justru berjalan sebagai container Docker di port 3306 dengan nama mariadb114, sementara Redis diinstall via brew. Pendekatan campuran ini sah saja, yang penting bench bisa menjangkau service tersebut lewat host dan port yang benar.
Satu konfigurasi database yang wajib dilakukan sebelum lanjut: MariaDB harus memakai character set utf8mb4 dan collation utf8mb4_unicode_ci. Kalau ini dilewatkan, pembuatan situs akan gagal di tengah jalan dengan error karakter set yang membingungkan. Tambahkan baris berikut di file konfigurasi MariaDB Anda lalu restart service database.
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
[mysql]
default-character-set = utf8mb4Install bench dan inisialisasi
Bench dipasang lewat pip ke environment Python tersendiri supaya tidak mencemari package sistem. Cara paling bersih adalah memakai pipx yang mengisolasi tiap CLI tool, atau manual dengan venv. Setelah bench tersedia, perintah bench init akan membuat struktur direktori lengkap sekaligus menyiapkan environment virtual Python di dalamnya.
# install bench via pipx (direkomendasikan)
brew install pipx
pipx install frappe-bench
# atau manual via venv
python3 -m venv ~/.venvs/bench
~/.venvs/bench/bin/pip install frappe-bench
export PATH="$HOME/.venvs/bench/bin:$PATH"
# buat bench baru dengan branch develop v16
bench init frappe-bench --frappe-branch version-16
cd frappe-benchProses init akan meng-clone repo Frappe, membuat venv, dan menginstall dependency Python termasuk headless Chrome untuk testing. Di Mac dengan chip Apple Silicon, kadang proses ini berhenti saat kompilasi wheel lxml atau weasyprint. Kalau menabrak, pasang dulu build dependency-nya: brew install libxml2 libxslt gettext. Di Linux Ubuntu, padanannya adalah apt install libxml2-dev libxslt1-dev libjpeg-dev.
Pointing bench ke MariaDB dan Redis yang benar
Inilah jebakan pertama yang menjatukan saya berjam-jam dulu: bench di local Mac tidak otomatis tahu MariaDB Anda jalan di Docker, apalagi kalau Redis juga dipakai aplikasi lain. File sites/common_site_config.json adalah pusat konfigurasi semua situs dalam bench. Di bench saya, isinya menunjuk Redis cache ke port 13000 dan Redis queue ke port 11000, bukan port default 6379, karena port default bentrok dengan Redis milik service lain di mesin yang sama.
Ubah file tersebut sesuai topologi mesin Anda. Contoh untuk MariaDB di Docker dengan nama container mariadb114:
{
"db_host": "127.0.0.1",
"db_port": 3306,
"redis_cache": "redis://127.0.0.1:13000",
"redis_queue": "redis://127.0.0.1:11000",
"redis_socketio": "redis://127.0.0.1:12000",
"socketio_port": 9000
}Kalau MariaDB berjalan sebagai container dengan nama DNS (di kasus saya host-nya bahkan ditulis mariadb114 langsung di site config), pastikan nama itu resolve dari dalam bench. Untuk Redis yang dipakai bersama, bench menyediakan file config siap pakai di config/redis_cache.conf dan config/redis_queue.conf yang bisa Anda jalankan sendiri: redis-server config/redis_cache.conf di terminal terpisah.
Membuat situs baru
Setelah database dan Redis beres, saatnya membuat situs. Perintah new-site akan membuat database baru, menjalankan migrasi awal Frappe, dan membuat user Administrator. password-file sebaiknya diisi dari awal supaya Anda tidak perlu reset password di kemudian hari.
bench new-site erp.localhost --mariadb-user-host-login-scope '%' \
--admin-password admin123 --db-root-password password_root_andaTrik penting untuk Mac dan Linux: pakai nama situs berakhiran .localhost seperti erp.localhost supaya browser otomatis me-resolve-nya ke 127.0.0.1 tanpa perlu mengedit file /etc/hosts. Kalau Anda lebih suka nama polos seperti development, tambahkan sendiri baris 127.0.0.1 development ke /etc/hosts.
Flag –mariadb-user-host-login-scope ‘%’ menyuruh MariaDB membuat user database yang bisa login dari host mana pun. Tanpa flag ini di setup Docker, Anda akan ketiban error akses ditolak saat situs pertama kali dicoba diakses, karena user dibatasi ke localhost saja.
Install ERPNext dan aplikasi turunannya
Situs yang baru dibuat hanya berisi Frappe framework. ERPNext dipasang dua tahap: get-app mengambil source code ke folder apps/, lalu install-app mendaftarkannya ke situs dan menjalankan migrasi database. Versi aplikasi harus satu saluran dengan versi Frappe: ERPNext v16 untuk Frappe v16.
bench get-app erpnext --branch version-16
bench --site erp.localhost install-app erpnext
# modul pendamping yang biasa dibutuhkan
bench get-app hrms --branch version-16
bench --site erp.localhost install-app hrmsProses install-app ERPNext lumayan lama, lima sampai sepuluh menit di mesin standar, karena ribuan DocType dibuat satu per satu ke database. Jangan panik kalau terminal kelihatan diam lama. Setelah selesai, folder bench Anda akan berisi apps/frappe dan apps/erpnext berdampingan, persis struktur bench produksi saya yang juga menampung master, rms, operation, dan beberapa custom app internal.
Menjalankan semua proses development
Satu perintah untuk menghidupkan semuanya: bench start. Perintah ini membaca Procfile dan menjalankan web server di port 8000, Redis cache dan queue di port hasil konfigurasi, socketio, scheduler, dan worker queue. Buka http://erp.localhost:8000 di browser, login dengan user Administrator dan password yang tadi dibuat.
bench start
# kalau butuh mode development penuh (server restart otomatis + asset watch):
bench --site erp.localhost set-config developer_mode 1Di Mac saya, Procfile memakai bench serve untuk web karena versi development terbaru sudah pindah dari gunicorn/werkzeug ke arsitektur async. Kalau Anda melihat tutorial lama yang menyuruh edit Procfile untuk gunicorn, itu tutorial era lama dan tidak relevan lagi untuk v16.
Jebakan yang sering menjatuhkan pemula
Pertama, error host not allowed ketika membuka situs. Ini terjadi karena situs baru belum di-set sebagai situs default bench. Jalankan bench use erp.localhost, atau buka langsung URL lengkap dengan port. Kedua, error Redis connection refused: berarti service Redis di config belum dijalankan. Jalankan dua redis-server dengan file config bench sebelum bench start.
Ketiga, stuck di layar login setelah password benar. Biasanya socketio belum jalan atau Redis socketio salah port, sehingga request realtime menggantung. Keempat, asset CSS dan JS tidak termuat setelah edit tampilan: jalankan bench build –hard untuk memaksa rebuild, lalu hard refresh browser.
Kelima, dan ini spesifik pengalaman saya dengan bench multi-aplikasi: watch process memakan CPU tinggi terus menerus. Solusinya jalankan bench watch hanya saat benar-benar mengedit asset, dan matikan saat development backend saja. Keenam, kalau Anda pernah mengganti versi Python sistem, venv lama bench bisa rusak diam-diam: perintah bench tiba-tiba error import. Perbaikannya dengan membuat ulang environment lewat bench setup requirements, bukan reinstall dari nol.
Alur kerja harian yang sehat
Setelah semuanya jalan, rutinitas development saya sederhana: bench start di satu terminal untuk server, buka situs di browser untuk UI, dan editor untuk kode di folder apps. Update source code dengan git pull di masing-masing folder app lalu bench –site erp.localhost migrate untuk menjalankan perubahan schema. Backup berkala lewat bench –site erp.localhost backup yang menghasilkan file database dan files di folder backups situs.
Satu kebiasaan yang menyelamatkan saya berkali-kali: sebelum experiment apa pun yang berpotensi merusak data, jalankan backup dulu. Bench yang menampung banyak aplikasi berarti banyak tabel, dan migrasi yang gagal di tengah bisa meninggalkan schema setengah jadi. Dengan backup, pulihnya cepat: bench –site erp.localhost restore path/ke/backup.sql.
Cara kedua: semuanya di Docker
Instalasi bench native di Mac punya satu masalah mendasar: sebagian dependency Linux berperilaku beda, dan kolaborasi dengan tim yang pakai Linux atau Windows sering berujung beda versi wheel. Solusi yang saya pakai sehari-hari: menjalankan bench di dalam container Linux, sambil tetap mengedit kode dari Mac. Setup ini sudah berjalan berbulan-bulan menampung sebelas aplikasi termasuk ERPNext v16.14, HRMS, CRM, dan enam custom app internal, jadi semua langkah berikut terbukti stabil.
Arsitekturnya tiga lapis. Pertama, image container development berbasis Ubuntu 24.04 yang saya build sendiri: Python 3.14 dari PPA deadsnakes, Node.js 24 dari NodeSource plus yarn, MariaDB client, Redis server, dan seluruh library gambar seperti pango, harfbuzz, dan libjpeg yang dibutuhkan weasyprint. Kedua, satu container MariaDB 11.4 terpisah sebagai database server. Ketiga, folder bench di Mac yang di-mount ke dalam container, jadi kode tetap diedit pakai editor lokal sementara prosesnya jalan di Linux.
Build image development dan siapkan container
Image dibuat sekali lalu dipakai selamanya. Simpan Dockerfile berikut, sesuaikan versi Python dan Node sesuai kebutuhan framework Anda:
FROM ubuntu:24.04
ENV TZ=Asia/Jakarta LANG=C.UTF-8 LC_ALL=C.UTF-8
ARG systemUser=frappe
ARG appBranch=version-16
RUN ln -fs /usr/share/zoneinfo/$TZ /etc/localtime && \
apt-get update && apt-get upgrade -y && apt-get install -y \
sudo tzdata git vim nano curl wget zip unzip \
software-properties-common build-essential pkg-config && \
add-apt-repository ppa:deadsnakes/ppa -y && \
apt-get install -y python3.14 python3.14-dev python3.14-venv python3-pip \
redis-server mariadb-client libmariadb-dev cron && \
curl -fsSL https://deb.nodesource.com/setup_24.x | bash - && \
apt-get install -y nodejs && npm install -g yarn && \
apt-get install -y libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz0b \
libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev \
libtiff5-dev libfribidi-dev libxcb1-dev libffi-dev && \
adduser --disabled-password --gecos "" $systemUser && \
usermod -aG sudo $systemUser && \
echo "%sudo ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/sudoers && \
apt-get clean && rm -rf /var/lib/apt/lists/*
USER $systemUser
WORKDIR /home/$systemUser
RUN pip3 install frappe-bench --break-system-packagesBuild lalu buat jaringan internal dan container database. MariaDB di sini memakai image resmi versi 11.4; container saya diberi nama mariadb114 yang sekaligus jadi hostname-nya di jaringan Docker:
docker build -t frappe-local:16 .
docker network create dev-network
docker run -d --name mariadb114 --network dev-network \
-p 3306:3306 \
-e MARIADB_ROOT_PASSWORD=password_root_anda \
mariadb:11.4Yang penting di sini hanya dua: container database dan container bench harus satu jaringan supaya bisa saling menemukan lewat nama, dan port 3306 di-expose ke host hanya demi kemudahan inspeksi lewat client database di Mac. Kalau Anda tidak butuh itu, baris -p boleh dibuang karena trafik bench ke MariaDB tidak lewat host sama sekali.
Jalankan bench di dalam container, kode di Mac
Sekarang bagian yang membuat setup ini enak: folder bench di Mac di-mount sebagai volume ke path home user di container. Edit kode dari VS Code di Mac, proses berjalan di Linux, tidak ada sinkronisasi apa pun karena keduanya melihat file yang sama.
docker run -it --name erpnext-local \
--network dev-network \
-p 8000:8000 -p 9000:9000 \
-v /Users/nama-anda/Documents/project/frappe_local:/home/frappe \
frappe-local:16 /bin/bashDi dalam container, semua langkah artikel sebelumnya berlaku sama persis, dengan satu penyesuaian: host database ditulis sebagai nama container MariaDB, bukan 127.0.0.1. Di site config situs saya, db_host berisi mariadb114, dan Docker DNS yang me-resolve-nya. Redis tidak perlu container terpisah: empat proses Redis untuk cache, queue, dan socketio cukup berjalan di dalam container bench yang sama, karena ini environment development yang penghuninya satu orang.
# dari dalam container, di folder ~/frappe-bench
bench new-site erp.localhost \
--db-root-password password_root_anda \
--admin-password admin123 \
--mariadb-db-host mariadb114
bench get-app erpnext --branch version-16
bench --site erp.localhost install-app erpnext
bench startSatu jebakan khas kombinasi ini: flag –mariadb-db-host membuat user database dibuat dengan scope host sesuai jaringan Docker. Kalau Anda membuat situs dari Mac (native) tetapi databasenya di container, user yang dibuat tidak akan bisa dipakai dari dalam container, atau sebaliknya, karena asal koneksi berbeda. Konsisten saja: semua operasi bench dijalankan dari dalam container yang sama, masalah itu tidak akan muncul.
Alur harian dengan container
Setelah semuanya jalan, rutinitasnya ringkas. Container database hidup terus dengan restart policy, sedangkan container bench saya jalankan interaktif: docker start erpnext-local lalu docker attach erpnext-local kalau perlu masuk, karena sesi bash dengan honcho start tetap hidup selama container hidup. Kode diedit langsung dari Mac, dan karena watch process juga berjalan di dalam container, perubahan file langsung ke-pickup tanpa refresh manual.
Buka http://localhost:8000 dari browser Mac dan Anda mendapat ERPNext penuh dengan performa native Linux, sementara folder proyek tetap aman di backup Time Machine Mac. Pemisahan ini juga membuat eksperimen berbahaya jadi murah: snapshot image, buat container baru, rusak semaunya, hapus, ulangi. Satu-satunya yang perlu dijaga adalah data di MariaDB container dan folder sites, karena keduanya hidup di luar image.
Terakhir, kalau nanti butuh deploy ke server produksi, konsepnya sama persis hanya beda medium: image production resmi dari frappe_docker, atau Easy Stack script di Ubuntu. Pemahaman komponen lokal yang Anda bangun sekarang akan langsung terpakai saat menyusun arsitektur produksi, karena pertanyaannya sama: Python versi berapa, database di mana, Redis port berapa, dan aplikasi apa saja yang terinstall.
