Buku Manual / Menurut meja Anda

Untuk IT

Yang perlu Anda tahu sebelum menyanggupi merawat sistem ini: apa yang dipasang, apa yang lahir di disk, dan apa yang tetap jadi tanggung jawab Anda.

Apa yang sebenarnya dipasang

Satu berkas biner. Tidak ada peladen aplikasi terpisah, tidak ada layanan basis data yang harus dipasang lebih dulu, tidak ada runtime bahasa yang harus ada di mesin, dan tidak ada proses build untuk tampilan.

• Templat HTML, CSS, dan berkas JavaScript pendukung ikut tertanam di dalam biner -- tidak ada direktori aset yang harus dibawa serta.
• Skema basis data dan berkas migrasi juga tertanam.
• Mesin basis datanya ikut di dalam biner, bukan pustaka sistem yang harus dipasang dan versinya dicocokkan.
• Dikompilasi tanpa ketergantungan pustaka C, sehingga biner untuk Windows, Linux (amd64 dan arm64), dan macOS dihasilkan dari satu perintah build yang sama.

Konsekuensi praktisnya: memindahkan Billira ke mesin lain berarti menyalin dua hal -- binernya dan berkas basis datanya.

Menyalakan pertama kali

Urutannya bebas; basis data dibuat oleh perintah mana pun yang lebih dulu membukanya. Yang lazim:

export BILLIRA_DB_KEY="frasa-rahasia-yang-panjang"

# 1. buat akun admin pertama
./billira pengguna tambah \
    -db /var/lib/billira/billira.db \
    -username admin -nama "Nama Admin" -peran admin

# 2. jalankan peladen
./billira -db /var/lib/billira/billira.db -alamat 127.0.0.1:8080

Kata sandi diminta lewat prompt, bukan lewat argumen baris perintah -- supaya tidak tertinggal di riwayat shell atau terlihat di daftar proses. Peran yang tersedia: admin, petugas, kasir.

Golongan tarif contoh terisi otomatis saat peladen pertama kali jalan, sekadar supaya sistem tidak kosong melompong; pengisian ini idempoten dan tidak menimpa golongan yang sudah Anda buat sendiri. Angkanya wajib diganti sebelum dipakai menagih sungguhan.

Kunci enkripsi

Kunci enkripsi at-rest diberikan lewat variabel lingkungan BILLIRA_DB_KEY, bukan lewat flag baris perintah -- argumen proses bisa dibaca pengguna lain di mesin yang sama, variabel lingkungan proses tidak semudah itu.

• Kunci hilang berarti data hilang. Tidak ada pintu belakang, tidak ada pemulihan kunci. Simpan kunci di brankas kata sandi organisasi, bukan di catatan tempel pada monitor peladen.
• Bila variabel ini kosong, basis data tidak dienkripsi dan aplikasi mencatat peringatan saat dinyalakan. Ini sah untuk mencoba-coba, tidak untuk data pelanggan sungguhan.
• Kunci yang sama harus dipakai oleh semua perintah yang menyentuh berkas itu -- termasuk saat mencadangkan dan memeriksa.

Berkas yang lahir di disk

Satu berkas basis data selalu ditemani beberapa berkas pendamping. Ini penting saat menyalin, mencadangkan, atau memindahkan:

Izin berkas basis data dipaksa menjadi 0600 setiap kali dibuka, sehingga izin yang terlanjur longgar akan diperbaiki sendiri.

Menaruhnya di jaringan

Billira tidak melayani HTTPS sendiri. Ia bicara HTTP polos, dengan asumsi berjalan di jaringan internal kantor dan loket.

Bila akses dari luar jaringan internal dibutuhkan -- loket cabang, misalnya -- maka pola pemasangannya: aplikasi diikat ke 127.0.0.1, dan reverse proxy (Caddy, nginx, atau sejenisnya) yang mengurus sertifikat dan HTTPS di depannya. Pembatasan siapa yang boleh menjangkau proxy itu -- VPN, daftar alamat IP, jaringan pemerintah daerah -- juga bagian dari pemasangan, bukan sesuatu yang diatur di dalam aplikasi.

Aplikasi menyediakan endpoint kesehatan /sehat yang tetap membalas meski basis data bermasalah, sehingga bisa dipakai pemantauan untuk membedakan "proses mati" dari "proses hidup tapi basis datanya bermasalah".

Cadangan dan pemulihan

Perintah cadangan bawaan mengambil salinan yang konsisten tanpa menghentikan layanan:

./billira cadangkan -db /var/lib/billira/billira.db \
    -ke /cadangan/billira-2026-08-09.db

• Perintah ini menolak menimpa berkas yang sudah ada. Beri nama bertanggal; jangan menulis ke nama yang sama berulang kali.
• Hasil cadangan tetap terenkripsi dengan kunci yang sama. Cadangan tanpa kuncinya adalah berkas tak berguna -- simpan keduanya, di tempat yang berbeda.
• Uji pemulihan secara berkala. Cadangan yang tidak pernah dicoba dipulihkan bukan cadangan, melainkan harapan.

Saat memulihkan, hentikan aplikasi lebih dulu, lalu tempatkan berkas cadangan sebagai basis data aktif. Bila yang dipulihkan ternyata lebih tua dari keadaan terakhir yang dikenal, aplikasi akan mencatat peringatan keras saat dinyalakan -- itu bukan gangguan, melainkan mekanisme yang memberitahu bahwa transaksi setelah titik itu berpotensi hilang. Jangan diabaikan.

Basis data juga diperiksa integritasnya setiap kali dibuka; berkas yang rusak ditolak dan tidak dilayani setengah-setengah. Pemeriksaan yang sama bisa dijalankan kapan saja:

./billira periksa -db /var/lib/billira/billira.db

Naik versi dan migrasi skema

Naik versi berarti mengganti berkas biner, lalu menjalankannya seperti biasa. Bila versi baru membawa perubahan skema, migrasi dijalankan otomatis saat basis data dibuka, dengan dua pengaman:

• Cadangan otomatis dibuat lebih dulu, sebelum migrasi pertama dijalankan.
• Setiap migrasi berjalan di dalam transaksinya sendiri -- migrasi yang gagal tidak meninggalkan skema separuh jadi.

Meski begitu, cadangkan sendiri sebelum naik versi di lingkungan produksi, dan coba versi barunya di salinan terlebih dahulu.

Perilaku saat beban puncak

Ada satu perilaku yang perlu Anda ketahui sebelum ditanya pengguna: saat billing dijalankan untuk satu periode, loket berhenti melayani sesaat. Ini konsekuensi langsung dari desain yang menjamin tidak ada tagihan yang setengah terhitung; penulisan dikerjakan satu per satu, bukan berebutan.

Untuk ukuran PAM yang jadi sasaran produk ini, jedanya singkat -- hitungan detik, bukan menit. Tetap saja, jadwalkan billing run di luar jam sibuk loket, dan beri tahu kasir sebelumnya. Pembacaan halaman berjalan paralel dan tidak ikut terhenti.

Saat dimatikan dengan sinyal berhenti yang wajar, aplikasi menyelesaikan permintaan yang sedang berjalan lebih dulu sebelum keluar, lalu merapikan berkas jurnal. Hindari mematikan paksa.

Yang bukan tanggung jawab aplikasi

Supaya tidak ada kejutan saat pemasangan, ini garis batasnya:

• HTTPS/TLS -- reverse proxy Anda.
• Pembatasan akses jaringan -- VPN, firewall, atau daftar alamat IP di sisi Anda.
• Penjadwalan cadangan -- aplikasi menyediakan perintahnya; penjadwalannya lewat cron atau penjadwal tugas sistem operasi Anda.
• Otentikasi terpusat (LDAP, SSO) -- tidak ada; akun dikelola di dalam Billira sendiri.
• Ketersediaan tinggi / replikasi -- tidak ada; satu proses, satu berkas. Ketahanan datang dari cadangan yang teruji, bukan dari klaster.