Konfigurasi
Referensi environment variable Liodra (inti, storage, flag fitur, auto-restart, upload, on-demand, eksperimental) serta format recordings.yaml dan retentions.yaml.
Seluruh konfigurasi Liodra dibaca dari environment variable (atau file .env saat dijalankan langsung dari source). Tidak ada file konfigurasi aplikasi selain dua file YAML di volume storage yang ditulis Liodra sendiri: recordings.yaml (device) dan retentions.yaml (retensi). Nilai default di bawah adalah default binary; entrypoint container mengubah beberapa di antaranya (ditandai).
Path default di kolom "Default" adalah default binary (./storage/..., relatif terhadap direktori kerja). Image Docker menimpanya menjadi ./nginx/html/storage/... dengan direktori kerja /usr/share, sehingga semuanya mendarat di volume /usr/share/nginx/html/storage. Pada image Docker standar Anda tidak perlu mengubahnya.
Inti
| Variable | Default | Keterangan |
|---|---|---|
PORT | 9080 | Port REST API dan WebSocket Liodra. |
LOG_LEVEL | info | debug, info, warn, error. Flag --verbose menyetelnya ke debug. |
MODE | production | development atau production. |
APP_VERSION | dev | Diisi CI dari git tag; muncul di /api/v1/version. |
NVR_BACKEND | srs | srs (backend standar) atau hikvision. Diset otomatis oleh argumen posisi hikvision pada entrypoint. |
RTMP_SECRET | (kosong) | Bila diisi, setiap publish dan play RTMP/RTSP harus membawa token yang valid; lihat Otentikasi RTMP. Kosong berarti semua koneksi diizinkan (dicatat sebagai peringatan saat startup). |
Storage
| Variable | Default | Keterangan |
|---|---|---|
RECORDING_DIR | ./storage/recordings | Direktori segmen DVR. |
VOD_DIR | ./storage/vods | Direktori video unggahan. |
LOG_DIR | ./storage/logs | Log per proses media (ingest dan on-demand). |
RECORDINGS_FILEPATH | ./storage/recordings.yaml | File persistensi device. |
RETENTIONS_FILEPATH | ./storage/retentions.yaml | File kebijakan retensi. |
DEVICE_PERSISTENCE_INTERVAL | 60s | Interval penulisan recordings.yaml (minimum 10s). File hanya ditulis bila ada perubahan. |
Flag Fitur
| Variable | Default binary | Default container | Keterangan |
|---|---|---|---|
ENABLE_PLAYBACK | true | false (--as-nvr → true) | DVR, /playbacks, /recordings, /retention. Backend Hikvision selalu true. |
ENABLE_VOD | true | false (--with-vod → true) | /videos dan channel vod. |
ENABLE_BROADCAST | true | false (--broadcast-on → true) | /broadcast dan /ws/v1/broadcast. |
Retensi dan Disk
| Variable | Default | Keterangan |
|---|---|---|
MAX_DISK_USAGE | 80 | Persentase pemakaian volume rekaman yang memicu cleanup darurat pada heartbeat, untuk mencegah disk penuh dan server macet. Juga menjadi acuan max_recommended_quota_mb pada GET /api/v1/retention. |
RETENTION_HEARTBEAT_INTERVAL | 1m | Interval pemeriksaan disk (minimum 30s). |
Kesehatan Device dan Auto-Restart
Device yang gagal health check di-restart otomatis, tetapi restart itu mahal (koneksi ke sumber dibangun ulang, segmen DVR baru dibuka) dan di bawah saturasi CPU dapat memperparah keadaan. Variabel berikut mengatur pengaman-pengamannya; default sudah teruji untuk ratusan kamera.
| Variable | Default | Keterangan |
|---|---|---|
AUTO_RESTART_GRACE | 10s | Lama device harus terus tidak sehat sebelum restart otomatis pertama. Dilewati bila proses ingest keluar bersih (sumber berhingga mencapai akhir). 0 menonaktifkan grace. |
AUTO_RESTART_BACKOFF_BASE | 2s | Jeda pertama sebelum retry, berlipat dua tiap percobaan (minimum 1s). Direset saat device sehat. |
AUTO_RESTART_BACKOFF_MAX | 60s | Batas atas backoff. |
AUTO_RESTART_CONCURRENCY | 2 | Jumlah device yang boleh restart bersamaan di seluruh fleet. Yang tidak mendapat slot mencoba lagi pada tick berikutnya. |
RESTART_JITTER_MAX | 2s | Jitter acak yang ditambahkan ke setiap backoff agar device yang gagal bersamaan tidak kembali serempak. |
INITIAL_LAUNCH_JITTER_MAX | 500ms | Jitter saat memulihkan device dari recordings.yaml pada startup. |
SUSPEND_THRESHOLD | 60s | Bila proses ingest terus gagal (keluar saat connect: RTSP ditolak, password salah, kamera dicabut) selama durasi ini, device disuspensi: retry dihentikan dan status menampilkan suspended: true. Minimum 10s. |
SUSPEND_PROBE_INTERVAL | 10s | Resume prober mengecek satu device suspensi (yang tertua) tiap interval ini; device dipulihkan otomatis saat sumbernya kembali. |
Proses On-Demand dan Monitor
| Variable | Default | Keterangan |
|---|---|---|
MAX_ONDEMAND_PROCESSES | 32 | Batas proses media on-demand bersamaan (preview playback, proxy ?transcode=true, stream VoD, unduhan MP4). Di atas batas, request dijawab 503 dengan Retry-After: 5. 0 = tanpa batas. Ingest tidak dihitung. |
MAX_STOPPED_PROCESSES | 10 | Jumlah proses on-demand yang sudah berhenti yang masih ditampilkan di /api/v1/monitor/ondemand. |
MAX_LOG_LINES | 500 | Jumlah baris default untuk endpoint log. |
Upload (VoD)
| Variable | Default | Keterangan |
|---|---|---|
MAX_UPLOAD_FILE_SIZE | 53687091200 (50 GB) | Ukuran file maksimum. |
MAX_UPLOAD_CHUNK_SIZE | 1048576 (1 MB) | Ukuran chunk maksimum per request. Chunk lebih besar berarti lebih sedikit round-trip. |
MAX_UPLOAD_RESOLUTION | 4096 | Tinggi video maksimum (piksel) untuk pembuatan thumbnail nyata; di atasnya dipakai placeholder. 0 menonaktifkan batas. |
UPLOAD_FILENAME_DATETIME_FORMAT | YYYYMMDDHHMMSS | Pola tanggal-waktu pada nama file yang diekstrak menjadi started_at. |
Backend Hikvision
| Variable | Default | Keterangan |
|---|---|---|
HIKV_BASE_URL | (wajib) | URL dasar NVR, mis. http://192.168.1.64. Container keluar bila kosong. |
HIKV_USERNAME | admin | Username NVR. |
HIKV_PASSWORD | (wajib) | Password NVR. |
Eksperimental
| Variable | Default | Keterangan |
|---|---|---|
EXPERIMENTAL | false | Gerbang untuk semua variable di bawah. Tanpa ini, TRANSCODE_* dilaporkan lalu diabaikan. |
TRANSCODE_INTO | (kosong) | h264 atau hevc (h265 diterima sebagai alias). Kosong = stream copy. |
TRANSCODE_QUALITY | 30 | Kualitas dasar 0-51 pada skala encoder hardware (semakin besar semakin kecil bitrate). Dikalibrasi naik per kamera. |
TRANSCODE_THREADS | 2 | Batas thread per ingest (sisi decoder software). 0 = tanpa batas. |
TRANSCODE_MAX_BPP | 0.06 | Batas bitrate per kamera dalam bit per piksel per detik (0,06 = 1,4 Mbps di 720p25, 3,1 Mbps di 1080p25). 0 menonaktifkan batas dan kalibrasi. |
Nilai TRANSCODE_* yang salah format membuat validasi konfigurasi gagal dan proses berhenti, terlepas dari EXPERIMENTAL. Penjelasan lengkap ada di Ingest Transcode.
recordings.yaml
Daftar device yang dikelola. Ditulis Liodra; Anda umumnya tidak perlu menyuntingnya, tetapi format-nya berguna untuk backup, migrasi, atau menyiapkan fleet awal sebelum container pertama kali dijalankan.
version: 1.0.0
last_updated: 2026-09-15T10:30:00Z
devices:
- name: camera_front
url: rtsp://admin:[email protected]:554/stream1
scheme: rtsp
channel: live
silent_audio: true
- name: youtube_test
url: https://www.youtube.com/watch?v=jfKfPfyJRdk
scheme: social
channel: vop/youtubeSaat startup, setiap entri dijalankan kembali (dengan jitter INITIAL_LAUNCH_JITTER_MAX). Device yang dihapus lewat API hilang dari file pada penulisan berikutnya. Password pada URL disimpan apa adanya di file ini; lindungi volume storage sebagaimana Anda melindungi kredensial kamera.
retentions.yaml
Jadwal cleanup dan kebijakan retensi. Dibuat oleh --set-retention dari template default, lalu diubah lewat API Retention. Durasi di file memakai satuan d (hari), w (minggu), m (bulan); API mengekspos nilai yang sama sebagai duration_days.
version: 1.0.0
last_updated: 2026-09-15T10:30:00Z
cleanup_schedule:
time: "02:00:00" # cleanup harian pukul 02:00 waktu server
default_retention:
duration: 7d # berlaku untuk channel tanpa kebijakan khusus
channel_policies:
- channel: live/security
retention:
duration: 90d
disk_quota_mb: 5242880 # 5 TB
headroom_percent: 10 # hapus sampai 90% kuota saat kuota terlampaui
time_of_day_start: "00:00:00"
time_of_day_end: "23:59:59"Untuk menonaktifkan retensi sepenuhnya, kosongkan cleanup_schedule (hapus time dan default_retention) lalu restart container; --as-nvr tanpa --set-retention tidak akan membuatnya kembali.
Selanjutnya
Instalasi
Menjalankan Liodra dengan Docker, memilih flag fitur (NVR, VoD, broadcast), memetakan port dan volume, lalu memverifikasi bahwa layanan hidup dan siap didaftarkan ke Lenz.
Backend Hikvision
Menjalankan Liodra di atas NVR Hikvision yang sudah ada lewat ISAPI, sehingga Lenz dan integrator memakai API yang sama untuk penemuan rekaman dan playback.