Menyiapkan Debian 13 untuk Instalasi FreePBX.
Panduan ini membahas instalasi FreePBX 17 pada Debian 13 setelah Asterisk selesai dipasang melalui artikel Install Asterisk di Debian. Langkah, error, dan perbaikan di dalam artikel ini mengikuti proses instalasi yang dijalankan langsung pada server, tanpa menambahkan konfigurasi di luar proses tersebut.
Penting: FreePBX pada instalasi ini menggunakan PHP 8.2.33. Pastikan PHP CLI dan PHP-FPM sama-sama menggunakan PHP 8.2 sebelum memulai instalasi.
Menyiapkan Prasyarat FreePBX.
Apabila Apache, MariaDB, PHP, dan phpMyAdmin sudah dipasang melalui artikel Install PHP, MySQL, Apache, dan phpMyAdmin di Debian Linux, tahap tersebut dapat dilewati.
phpMyAdmin tidak menjadi persyaratan FreePBX. Komponen yang digunakan dalam instalasi ini adalah Apache, MariaDB, PHP 8.2, PHP-FPM, Node.js, npm, SOX, dan ekstensi PHP yang dibutuhkan FreePBX.
Perbarui daftar paket:
apt update
Install Apache, MariaDB, Node.js, npm, SOX, dan paket pendukung:
apt install -y apache2 mariadb-server mariadb-client nodejs npm sox git wget curl
Install PHP 8.2 dan ekstensi yang digunakan:
apt install -y php8.2-cli php8.2-fpm php8.2-dev php8.2-mbstring php8.2-xml php8.2-yaml php8.2-bcmath php8.2-bz2 php8.2-snmp php8.2-mysql php8.2-zip php8.2-curl php8.2-gmp php8.2-intl php8.2-gd php8.2-ldap php8.2-soap php8.2-tidy php8.2-redis php8.2-memcached php8.2-imap php8.2-apcu php8.2-dba php8.2-enchant php8.2-embed php8.2-pspell php8.2-imagick
Aktifkan Apache, MariaDB, dan PHP-FPM:
systemctl enable --now apache2 mariadb php8.2-fpm
Periksa PHP yang aktif:
php -v
Pada instalasi ini hasilnya:
PHP 8.2.33
Periksa PHP-FPM:
systemctl status php8.2-fpm --no-pager
Periksa Node.js dan npm:
node -v && npm -v
Periksa SOX:
sox --version
SOX diperlukan oleh FreePBX untuk dukungan pemrosesan audio, termasuk dukungan HTML5.
Mengunduh FreePBX 17.
Masuk ke direktori source:
cd /usr/src
Download paket FreePBX 17:
wget -O freepbx.tgz https://mirror.freepbx.org/modules/packages/freepbx/freepbx-17.0-latest.tgz
Ekstrak paket FreePBX:
tar xzf freepbx-17.0-latest.tgz
Masuk ke direktori installer:
cd /usr/src/freepbx
Source FreePBX sekarang berada di:
/usr/src/freepbx
Memastikan Asterisk Tidak Berjalan sebagai Root.
Installer FreePBX membutuhkan Asterisk yang berjalan sebagai user asterisk.
Dari direktori FreePBX, jalankan:
./start_asterisk start
Periksa user proses Asterisk:
ps -o user,pid,cmd -C asterisk
Pada percobaan awal, ./start_asterisk start menjalankan Asterisk sebagai root. Kondisi tersebut harus diperbaiki sebelum installer dilanjutkan.
Hentikan Asterisk:
killall asterisk 2>/dev/null
Periksa /etc/asterisk/asterisk.conf:
grep -E '^[[:space:]]*runuser|^[[:space:]]*rungroup' /etc/asterisk/asterisk.conf
Konfigurasinya harus menunjukkan:
runuser = asterisk
rungroup = asterisk
rungroup = asterisk
Pastikan direktori Asterisk dimiliki oleh user asterisk:
chown -R asterisk:asterisk /etc/asterisk /var/lib/asterisk /var/log/asterisk /var/spool/asterisk /usr/lib/asterisk
Jalankan kembali Asterisk:
cd /usr/src/freepbx && ./start_asterisk start
Periksa sekali lagi:
ps -o user,pid,cmd -C asterisk
Lanjutkan instalasi hanya setelah kolom user menunjukkan:
asterisk
Menjalankan Installer FreePBX.
Masih dari direktori /usr/src/freepbx, jalankan:
./install -n
Opsi -n menjalankan installer tanpa pertanyaan interaktif.
Installer akan menyiapkan framework FreePBX, file konfigurasi, database, dan web interface.
Mengatasi Half-Baked Install.
Pada percobaan instalasi yang belum selesai, FreePBX mendeteksi kondisi half-baked install.
Kondisi yang ditemukan pada server adalah:
/etc/amportal.conf tersedia
/etc/freepbx.conf tidak tersedia
/etc/freepbx.conf tidak tersedia
Periksa kedua file:
ls -lah /etc/amportal.conf /etc/freepbx.conf 2>/dev/null
Jika /etc/amportal.conf sudah ada tetapi /etc/freepbx.conf belum terbentuk, instalasi dasar FreePBX belum selesai.
Pada instalasi baru yang belum berisi konfigurasi produksi, bersihkan file hasil instalasi tidak lengkap:
rm -f /etc/amportal.conf /etc/freepbx.conf
Kembali ke direktori installer:
cd /usr/src/freepbx
Jalankan kembali instalasi:
./install -n
Pembersihan tersebut hanya berlaku untuk instalasi baru yang memang belum selesai.
Error Framework sebelum Instalasi Dasar Selesai.
Pada saat instalasi FreePBX belum lengkap, perintah pemasangan framework pernah dijalankan:
fwconsole ma install framework
Perintah tersebut berhenti dengan exit code 255 dan menampilkan error seperti:
Undefined ASTLOGDIR
serta:
Class "FreePBX" not found
Error tersebut terjadi karena instalasi dasar belum selesai dan /etc/freepbx.conf belum tersedia. Jangan memasang framework secara terpisah pada kondisi ini.
Selesaikan installer utama terlebih dahulu:
cd /usr/src/freepbx && ./install -n
Setelah installer utama selesai, barulah perintah fwconsole dapat digunakan.
Menyelesaikan Instalasi Dasar.
Setelah ./install -n selesai, perbaiki ownership FreePBX:
fwconsole chown
Reload konfigurasi:
fwconsole reload
Restart FreePBX:
fwconsole restart
Periksa statusnya:
fwconsole status
Mengatasi HTTP 500 dari PHP-FPM.
Setelah instalasi, web FreePBX sempat menampilkan HTTP 500. Error yang ditemukan berkaitan dengan PHP-FPM, socket PHP-FPM, direktori session, dan akses terhadap /etc/freepbx.conf.
Periksa log Apache:
tail -n 100 /var/log/apache2/error.log
Periksa log PHP-FPM:
journalctl -u php8.2-fpm -n 100 --no-pager
Periksa log FreePBX:
tail -n 100 /var/log/asterisk/freepbx.log
Salah satu error yang muncul berkaitan dengan:
session_regenerate_id()
Periksa direktori session PHP:
ls -ld /var/lib/php/sessions
Berikan permission yang digunakan oleh direktori session PHP:
chmod 1733 /var/lib/php/sessions
Restart PHP-FPM dan Apache:
systemctl restart php8.2-fpm apache2
Error lain menunjukkan Apache tidak dapat terhubung ke socket:
/run/php/php8.2-fpm.sock
Periksa socket tersebut:
ls -lah /run/php/php8.2-fpm.sock
Restart PHP-FPM agar socket dibuat ulang, kemudian restart Apache:
systemctl restart php8.2-fpm apache2
Pada instalasi ini tidak dilakukan perubahan APACHE_RUN_USER atau APACHE_RUN_GROUP.
Mengatasi PHP-FPM yang Tidak Dapat Mengakses Konfigurasi FreePBX.
PHP-FPM juga sempat gagal menyertakan:
/etc/freepbx.conf
Selain permission file, service PHP-FPM pada server menggunakan hardening systemd:
ProtectSystem=full
Konfigurasi tersebut membuat beberapa lokasi sistem menjadi read-only bagi proses PHP-FPM.
Periksa konfigurasi service:
systemctl cat php8.2-fpm
Buat override PHP-FPM:
systemctl edit php8.2-fpm
Masukkan konfigurasi berikut:
[Service]
ReadWritePaths=/etc/asterisk /etc/amportal.conf /etc/freepbx.conf /var/lib/asterisk /var/spool/asterisk /var/log/asterisk /var/www/html
ReadWritePaths=/etc/asterisk /etc/amportal.conf /etc/freepbx.conf /var/lib/asterisk /var/spool/asterisk /var/log/asterisk /var/www/html
Simpan, kemudian reload systemd:
systemctl daemon-reload
Restart PHP-FPM dan Apache:
systemctl restart php8.2-fpm apache2
Verifikasi override:
systemctl show php8.2-fpm -p ProtectSystem -p ReadWritePaths
Setelah file FreePBX terbentuk, jalankan:
fwconsole chown
Kemudian:
fwconsole reload
Mengatasi /etc/asterisk yang Terbaca Read-Only.
Pembatasan PHP-FPM juga menyebabkan FreePBX gagal mengganti file konfigurasi Asterisk.
Error yang ditemukan:
rename(/etc/asterisk/amd.conf): Read-only file system
Masalah tersebut tidak dapat diselesaikan hanya dengan mengubah permission file. /etc/asterisk harus terdapat dalam ReadWritePaths PHP-FPM seperti pada override sebelumnya.
Periksa kembali:
systemctl show php8.2-fpm -p ReadWritePaths
Pastikan hasilnya memuat:
/etc/asterisk
Restart PHP-FPM dan Apache:
systemctl restart php8.2-fpm apache2
Kemudian jalankan:
fwconsole chown && fwconsole reload
Mengatasi Permission /etc/asterisk/keys.
FreePBX sempat tidak dapat menulis ke direktori:
/etc/asterisk/keys
Pastikan direktori tersedia:
mkdir -p /etc/asterisk/keys
Perbaiki ownership melalui FreePBX:
fwconsole chown
Pastikan /etc/asterisk sudah masuk dalam ReadWritePaths PHP-FPM, kemudian restart service:
systemctl restart php8.2-fpm apache2
Reload FreePBX:
fwconsole reload
Mengatur Koneksi Asterisk Manager Interface.
FreePBX berkomunikasi dengan Asterisk melalui Asterisk Manager Interface atau AMI.
Pada proses instalasi, FreePBX sempat menampilkan:
Unable to connect to Asterisk Manager
Periksa konfigurasi AMI:
nano /etc/asterisk/manager.conf
Bagian general yang digunakan:
[general]
enabled = yes
port = 5038
bindaddr = 0.0.0.0
enabled = yes
port = 5038
bindaddr = 0.0.0.0
Akses akun AMI dibatasi untuk localhost menggunakan deny dan permit.
Periksa credential AMI yang tersimpan oleh FreePBX:
grep -E 'AMPMGRUSER|AMPMGRPASS' /etc/amportal.conf
Periksa akun yang terdapat dalam manager.conf:
grep -nE '^\[|^secret|^deny|^permit|^read|^write' /etc/asterisk/manager.conf
Nilai AMPMGRUSER harus sama dengan nama akun pada manager.conf, sedangkan AMPMGRPASS harus sama dengan nilai secret.
Setelah credential disesuaikan, reload AMI:
asterisk -rx "manager reload"
Reload FreePBX:
fwconsole reload
Pada instalasi ini koneksi AMI berhasil setelah username dan password pada kedua konfigurasi dibuat sama.
Memperbarui GPG Key FreePBX.
Selama proses instalasi modul, FreePBX menampilkan peringatan GPG key.
Perbarui GPG key FreePBX:
fwconsole ma updategpgkey
Reload konfigurasi:
fwconsole reload
Periksa daftar modul:
fwconsole ma list
Memasang SOX untuk Dukungan HTML5.
SOX diperlukan agar dukungan audio HTML5 FreePBX dapat digunakan.
Install SOX jika belum tersedia:
apt install -y sox
Periksa instalasinya:
sox --version
Reload FreePBX:
fwconsole reload
Memasang Modul ARI Manager.
Halaman Asterisk Info membutuhkan modul arimanager.
Install modul tersebut:
fwconsole ma downloadinstall arimanager
Reload FreePBX:
fwconsole reload
Periksa modul:
fwconsole ma list | grep -i arimanager
Mengaktifkan UCP Daemon.
Periksa status modul UCP:
fwconsole ma list | grep -i ucp
Pada instalasi ini modul yang terpasang adalah:
ucp 17.0.9 Enabled
Periksa proses PM2:
fwconsole pm2 --list
Pada pemeriksaan pertama, tabel PM2 tampil kosong. Karena proses UCP belum terdaftar, perintah berikut gagal:
fwconsole pm2 --restart=ucp
Error yang muncul:
There is no process by that name
Solusi yang berhasil adalah menonaktifkan lalu mengaktifkan kembali modul UCP:
fwconsole ma disable ucp
Aktifkan kembali:
fwconsole ma enable ucp
Reload FreePBX:
fwconsole reload
Restart FreePBX:
fwconsole restart
Periksa kembali PM2:
fwconsole pm2 --list
Setelah berhasil, proses berikut tampil dan berstatus online:
core-calltransfer-monitor
core-fastagi
ucp
core-fastagi
ucp
Simpan state PM2:
fwconsole pm2 --update
Verifikasi sekali lagi:
fwconsole pm2 --list
Format perintah yang digunakan adalah:
fwconsole pm2 --list
Bukan:
fwconsole pm2 list
Verifikasi Akhir FreePBX.
Periksa PHP:
php -v
Periksa PHP-FPM:
systemctl status php8.2-fpm --no-pager
Periksa Apache:
systemctl status apache2 --no-pager
Periksa MariaDB:
systemctl status mariadb --no-pager
Periksa Node.js dan npm:
node -v && npm -v
Periksa Asterisk:
asterisk -rx "core show version"
Periksa status FreePBX:
fwconsole status
Periksa modul FreePBX:
fwconsole ma list
Periksa proses PM2:
fwconsole pm2 --list
Kondisi akhir instalasi yang berhasil adalah Asterisk aktif, Apache dan PHP-FPM berjalan, koneksi AMI berhasil, web FreePBX dapat dibuka, serta proses berikut berstatus online:
core-calltransfer-monitor
core-fastagi
ucp
core-fastagi
ucp
Setelah seluruh pemeriksaan berhasil, buka alamat IP atau hostname server melalui browser untuk membuat akun administrator dan melanjutkan konfigurasi FreePBX.