2‐Panduan Instalasi - lindduncoding/database-bsb GitHub Wiki

0. Mengakses Server

Dalam terminologi IT, server adalah segala perangkat yang berperan memberikan layanan atau informasi kepada perangkat lain yang meminta layanan tersebut (disebut sebagai client). Di proyek ini, server adalah perangkat yang akan menjalankan komponen database, backend server, dan me-render halaman frontend supaya dapat diakses oleh client. Setelah menemukan perangkat dengan spesifikasi minimum (atau rekomendasi) yang ingin dijadikan server, ketahui beberapa hal berikut:

Must Read

• Pastikan port 22 (SSH) bisa diakses oleh perangkat lain. Langkah pertama ini penting sebagai jalan akses pengembang dengan server.
• Ketahui IP Address server. Router memiliki cara dan konfigurasi berbeda dalam memberikan alamat IP ke perangkat yang berada dalam jaringan. Untuk memudahkan konfigurasi, pastikan router TIDAK mengaktifkan mode DHCP pada alamat IP server. Hal ini untuk mencegah alamat IP server berubah-ubah setiap waktu. Untuk mengetahui alamat IP server, gunakan tools seperti nmap berbasis CLI (tersedia untuk semua OS) atau Advanced IP Scanner berbasis GUI pada Windows.
• Jaga koneksi dan daya server stabil.

Langkah-langkah Akses:

1. Pastikan server dan client berada di 1 jaringan.
2. Ketahui alamat IP lokal perangkat untuk menemukan alamat IP jaringan. Buka Terminal atau Command Prompt.

UNIX/Linux:

ifconfig

Windows

ipconfig

Contoh luaran/hasil (hasil dapat berbeda tergantung kondisi jaringan):

wlo1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 192.168.0.33  netmask 255.255.255.0  broadcast 192.168.0.255

Maka, alamat jaringan adalah 192.168.0.0

3. Lakukan IP Scanning untuk mencari alamat IP server.

Linux:

nmap -sn 192.168.0.0/24

Contoh output:
Starting Nmap 7.92 ( https://nmap.org ) at 2025-07-28 18:24 WIB
Nmap scan report for _gateway (192.168.0.1)
Host is up (0.0079s latency).
Nmap scan report for 192.168.0.4
Host is up (0.022s latency).
Nmap scan report for 192.168.0.5
Host is up (0.0070s latency).

Kemudian lakukan port scanning untuk masing-masing alamat IP guna mencari server yang memiliki port 22 terbuka.

nmap 192.168.0.4

Contoh output:
PORT   STATE SERVICE
53/tcp open  domain
80/tcp open  http
22/tcp open  ssh

Atau gabungkan kedua command menjadi satu:

nmap -sn 192.168.1.0/24 | grep "Nmap scan report" | awk '{print $5}' | xargs -I {} nmap {}

Windows: Jalankan program Advanced IP Scanner dan cari host yang memiliki spesifikasi sama dengan server.

4. SSH ke alamat server. Buka Terminal atau Command Prompt dan jalankan perintah berikut.

ssh root@[alamat_server]

Ketik password kemudian jika berhasil maka tampilan Terminal atau Command Prompt akan berubah dan menunjukkan banner OS server. Lanjut ke bagian-bagian selanjutnya.

1. Setup Database

Install mariadb di perangkat yang akan berperan sebagai server. Lalu, install DBeaver di perangkat yang berperan sebagai client untuk memudahkan setup database.

Koneksi Database

Langkah koneksi ke database dikhususkan pada perangkat Linux karena hardware tempat sistem ini bekerja menggunakan OS Linux. Panduan bagi OS lain dapat diakses melalui tautan resmi MariaDB: https://mariadb.com/docs/server/mariadb-quickstart-guides/installing-mariadb-server-guide

Langkah-langkah di bawah hanya untuk melakukan koneksi ke server database. Maka dari itu, lakukan instalasi dan setup user root terlebih dahulu

Konfigurasi Server

1. Cek status layanan mariadb

sudo systemctl status mariadb

2. Jalankan layanan mariadb jika hasil perintah di atas tidak menunjukan bahwa mariadb sudah berjalan

sudo systemctl start mariadb

3. Atur supaya mariadb mendengarkan koneksi masuk dari remote host dengan mengubah file /etc/my.cnf seperti di bawah:

[mysqld]
bind-address = 0.0.0.0 # atur sesuai dengan kebutuhan

Jika file konfigurasi tidak berada di /etc/my.conf, jalankan perintah berikut:

maraidb --help --verbose

Cari output yang menandakan Default options are read from the following files in the given order: /etc/my.cnf /etc/mysql/my.cnf ~/.my.cnf. Dari sini akan terlihat path file konfigurasi yang digunakan mariadb.

4. Atur supaya firewall tidak memblokir koneksi masuk ke port 3306 melalui tcp (port dan protokol bawaan MySQL):

sudo ufw allow 3306/tcp

5. Buat dan berikan permission khusus untuk akun remote. Contoh, perintah berikut memberikan akses semua operasi (ALL PRIVILEGE) terhadap semua table di database 'sampah' untuk remote host dengan username 'remote_user' dari IP range '192.168.100.0/24' dengan password 'securepass':

CREATE USER 'remote_user'@'192.168.100.%' IDENTIFIED BY 'securepass';
GRANT ALL PRIVILEGES ON sampah.* TO 'remote_user'@'192.168.100.%';
FLUSH PRIVILEGES;

Kemudian berikan password yang sudah di-setup sebelumnya

Konfigurasi Client

1. (Recommended) Koneksi ke server mariadb dilakukan melalui tool GUI seperti DBeaver

2. Pilih menu Database > New Database Connection

3. Pilih MariaDB kemudian isikan Server Host (alamat server mariadb), username dan password yang sudah di-setup sebelumnya.

4. Lakukan test connection. Jika berhasil, maka klik finish kemudian koneksi akan muncul di bagian kiri interface. Jika belum, maka download driver MariaDB yang diperlukan.

*Note: Perangkat yang membutuhkan koneksi ke server MariaDB TIDAK perlu di-instal MariaDB, hanya perlu file drivernya saja!

5. (Alternatif) Masuk ke server mariadb menggunakan CLI dengan melakukan perintah berikut

mariadb -h [alamat_server] -u username -p nama_database

Pastikan perangkat yang digunakan untuk melakukan koneksi ke MariaDB berada di range IP yang sudah didefinisikan sebelumnya (kalau mengikuti contoh, berarti perangkat kita harus berada di range IP 192.168.100.0/24, alias di local network saja)

Script SQL

Di repo ini, terutama di folder sql, terdapat beberapa script SQL untuk mendefinisikan data (DDL) dan memanipulasi data (DML) seperti operasi insertion. Catatan: operasi insertion drekomendasikan untuk dilakukan menggunakan antarmuka web app tidak langsung melalui DBeaver atau console MariaDB. Untuk menggunakan script tersebut (terutama script DDL), lakukan langkah-langkah berikut:

1. Buka DBeaver dan pilih tanda panah ke bawah dekat SQL Script. Klik Open SQL Script

2. Navigasi ke menu SQL Editor kemudian pilih Import SQL Script.

3. Menu tersebut akan membuka Window untuk memilih script yang sudah di-download sebelumnya. Pilih script tersebut kemudian jika sudah berhasil di-import tampilannya akan seperti ini:

4. Pilih icon Play untuk menjalankan script yang sudah di-import sebelumnya.

Tambahan untuk script Triggers:

Triggers adalah script khusus SQL yang akan berjalan ketika seuatu event terjadi. Pada kasus database ini, saya menggunakan trigger untuk melakukan auto-generation terhadap no rekening nasabah, nomor unik pembeli, dan nomor invoice pembelian serta penjualan. Hal ini untuk memudahkan proses insertion ke depannya, sehingga admin hanya menambahkan data yang diperlukan saja (nama, jenis sampah, berat, dsb) tanpa perlu memikirkan logic identifier di belakang layar :D

1. Pada DBeaver, pilih tabel yang ingin diberikan trigger, contohnya tabel pembelian. Klik kanan folder Triggers dan pilih New Trigger.

2. Beri nama Trigger. Jika ingin melakukan import dari script yang ada di repo ini. Pastikan nama Trigger sama dengan nama Trigger yang tertera pada script

3. Lakukan Copy & Paste script Trigger yang diinginkan pada bagian ini.

4. Jika sukses makan Trigger akan muncul di bawa tabel Trigger:

2. Menjalankan Server

Komponen Backend projek ini menggunakan FastAPI. Berikut adalah langkah untuk menjalankan komponen backend pada server:

1. Git Clone

Untuk memudahkan proses download semua file repository, lakukan git clone dengan cara:

git clone https://github.com/lindduncoding/database-bsb.git

2. Install Requirements

Install dependensi menggunakan pip. Disarankan membuat virtual environment ketika melakukan instalasi dependensi:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Environment Variables

Beberapa variabel seperti username, password, secret key JWT token, dan alamat database dibutuhkan dalam pengembangan tetapi tidak boleh terekspos secara publik. Maka dari itu, sebelum menjalankan server, buatlah file bernama .env untuk menyimpan variabel-variabel di atas. Daftar variabel yang paling dibutuhkan adalah DATABASE_URL dan SECRET_KEY untuk JWT. Tambahkan 2 baris konfigurasi ini ke file .env yang baru saja dibuat:

DATABASE_URL=[isi_sendiri]
SECRET_KEY=[isi_sendiri]

4. Menjalankan Uvicorn dengan Nohup

Jalankan server FastAPI menggunakan nohup supaya walaupun sesi SSH telah berakhir, server masih terus berjalan dan masih diakses oleh client.

nohup uvicorn main:app --host 0.0.0.0 > output.log 2>&1 &

• main adalah nama file Python utama (contohnya main.py).
• app adalah nama objek FastAPI yang dideklarasikan di code.
• --host adalah alamat server akan menerima request
• > output.log 2>&1 berfungsi untuk mencatat output dan error backend ke file bernama output.log (penting untuk troubleshooting)
• & berfungsi untuk menjalankan nohup di latar belakang

Backend berjalan di alamat IP server.

4. Informasi Tambahan

Bisa diakses melalui dokumentasi FastAPI.

API Endpoints

Untuk mengakses tabel lengkap API endpoint bisa mengunjungi endpoint /docs.

3. Mengakses Admin Panel

Ketika server dijalankan, admin panel akan secara otomatis ter-load. Masukkan username dan password untuk mengakses dashboard serta endpoint lainnya.