Configuration Reference

Halaman ini adalah referensi operasional lengkap untuk FREMIS-N yang sudah berjalan di produksi — dari parameter startup, setup monitoring, manajemen lisensi, backup & restore, hingga prosedur upgrade antar versi.

Parameter Startup

Saat menjalankan FREMIS-N, Anda dapat mengatur parameter berikut:

Parameter Dasar

Parameter Cluster

Contoh konfigurasi minimal standalone:

fremis_n_app httpserver \
  --storage postgres \
  --db-address 127.0.0.1 \
  --db-port 5432 \
  --db-name fremis_production \
  --db-username postgres \
  --db-password secure_password \
  --access-key YOUR_LICENSE_KEY \
  --secret-key YOUR_LICENSE_SECRET \
  --listen-port 4003

Untuk daftar perintah cluster dan coordinator, lihat Installation.

Monitoring & Observability

FREMIS-N mengekspos metrics dalam format Prometheus untuk monitoring real-time. Lihat Services & Ports untuk daftar port yang digunakan.

Setup Monitoring dengan Grafana

git clone https://github.com/stefanprodan/dockprom.git
cd dockprom
docker-compose up -d

- job_name: 'fremis-n'
  scrape_interval: 15s
  static_configs:
    - targets: ['localhost:4040']

docker-compose restart prometheus

Alert yang Wajib Dipantau

Konfigurasi alert Prometheus untuk kasus-kasus kritis berikut:

- alert: FremisNQPSHighUtilization
  expr: fremis_n_qps_actual / fremis_n_qps_limit > 0.8
  for: 5m
  annotations:
    summary: "FREMIS-N QPS mendekati limit (>80%)"

- alert: FremisNLatencyHigh
  expr: fremis_n_latency_p99_ms > 500
  for: 5m
  annotations:
    summary: "FREMIS-N p99 latency tinggi (>500ms)"

- alert: FremisNErrorRateHigh
  expr: rate(fremis_n_errors_total[5m]) > 0.05
  for: 5m
  annotations:
    summary: "FREMIS-N error rate tinggi (>5%)"

- alert: FremisNLicenseExpiringSoon
  expr: fremis_n_license_expires_in_seconds < 86400
  annotations:
    summary: "Lisensi FREMIS-N akan expired dalam 24 jam"

Quota & License Management

FREMIS-N menggunakan sistem lisensi yang membatasi throughput dan enrollment capacity.

Validasi Lisensi

• Lisensi divalidasi ke cloud Nodeflux saat startup FREMIS-N
• Setiap periode tertentu, lisensi di-refresh untuk memverifikasi masih aktif
• Jika refresh gagal, ada grace period yang memungkinkan operasi untuk sementara melanjutkan

Behavior Setelah Lisensi Expired

Ketika lisensi telah expired:

• Semua API request akan ditolak dengan HTTP 403
• Service akan log warning yang jelas
• Monitoring alert akan trigger (lihat bagian Alert di atas)

Hubungi Product Manager Nodeflux untuk renewal lisensi sebelum expiry date.

QPS Limit per Kategori

QPS dibatasi per kategori operasi sesuai paket lisensi:

• Recognition — maximum QPS untuk face search/recognition queries
• Enrollment — maximum QPS untuk enrollment operasi
• Utility — maximum QPS untuk operasi utility lainnya

Jika QPS melebihi limit:

• Request akan di-queue dan menunggu quota tersedia, atau
• Reject dengan HTTP 429 (Too Many Requests), tergantung konfigurasi

Monitoring Quota Utilization

Gunakan Grafana dashboard atau query Prometheus secara langsung:

# Melihat QPS actual vs limit
fremis_n_qps_actual / fremis_n_qps_limit

# Melihat enrollment capacity
fremis_n_enrollment_count / fremis_n_enrollment_limit

Backup & Restore

Melindungi data dengan backup berkala adalah bagian penting dari operational excellence.

Apa yang Harus Dibackup

1. Database persistence — seluruh database yang menyimpan data enrollment dan keyspace
2. Konfigurasi — file YAML coordinator config, environment variable, startup parameter
3. License credentials — access key dan secret key (simpan di secret manager, bukan disk plain-text)

Frekuensi Backup

• Daily backup untuk database dengan traffic aktif
• On-demand backup sebelum upgrade, perubahan konfigurasi besar, atau maintenance
• Minimum 7 hari retention untuk recovery dari data corruption

Backup Workflow

# Contoh: PostgreSQL backup
pg_dump -h db.internal -U postgres fremis_production > backup_fremis_$(date +%Y%m%d_%H%M%S).sql

gzip backup_fremis_*.sql
# Upload ke cloud storage (S3, Azure Blob, dll)
aws s3 cp backup_fremis_*.sql.gz s3://your-backup-bucket/fremis/

# Jangan commit ke git; gunakan secret manager (Vault, Sealed Secrets, dll)
vault kv put secret/fremis/backup \
  access_key=... \
  secret_key=...

Restore Workflow

docker stop fremis-n-instance-id

# Contoh: PostgreSQL restore
psql -h db.internal -U postgres < backup_fremis_20240530_143022.sql

psql -h db.internal -U postgres fremis_production -c "VACUUM ANALYZE;"

docker start fremis-n-instance-id

curl http://localhost:4003/health
# Pastikan endpoint return HTTP 200 dan status "ready"

Upgrade Antar Versi

Upgrade FREMIS-N dengan minimal downtime dan zero data loss.

Pre-Upgrade Checklist

• Baca CHANGELOG dari versi saat ini ke target version
• Backup database dan konfigurasi
• Test upgrade di staging environment terlebih dahulu
• Notifikasi users tentang scheduled maintenance window
• Pastikan database disk space mencukupi (migrations mungkin memerlukan space sementara)

Standalone (Single Node)

1. Backup database:

   pg_dump -h db.internal -U postgres fremis_production > backup_pre_upgrade.sql

2. Stop service:

   docker stop fremis-n-service

3. Upgrade Docker image:

   docker pull registry.gitlab.com/nodefluxio/fremis-n:v2.0.0-cpu  # atau gpu variant

4. Start dengan image baru:

   docker run -d \
     --name fremis-n-service \
     -e DB_CONNECTION_STRING="..." \
     -e FREMIS_ACCESS_KEY="..." \
     -e FREMIS_SECRET_KEY="..." \
     registry.gitlab.com/nodefluxio/fremis-n:v2.0.0-cpu \
     httpserver --listen-port 4003

5. Verifikasi:

   curl http://localhost:4003/health

Cluster (Multi-Node)

Upgrade dapat dilakukan secara rolling (node-by-node) selama coordinator masih bisa merutekan request ke node yang sedang aktif.

1. Upgrade node satu per satu (mulai dari node dengan traffic paling rendah):

   # 1. Stop node
   docker stop fremis-n-node1
   # 2. Upgrade image
   docker pull registry.gitlab.com/nodefluxio/fremis-n:v2.0.0-cpu
   # 3. Start dengan image baru
   docker run -d ... registry.gitlab.com/nodefluxio/fremis-n:v2.0.0-cpu httpserver ...
   # 4. Tunggu node ready di health endpoint
   # 5. Verifikasi via metrics — pastikan load sudah di-handle node lain

2. Upgrade coordinator terakhir:

   docker stop fremis-n-coordinator
   docker pull registry.gitlab.com/nodefluxio/fremis-n:v2.0.0-cpu
   docker run -d ... registry.gitlab.com/nodefluxio/fremis-n:v2.0.0-cpu coordinator ...

Rollback

Jika upgrade gagal:

1. Hentikan instance baru:

   docker stop fremis-n-service

2. Restore database dari backup:

   psql -h db.internal -U postgres < backup_pre_upgrade.sql

3. Start ulang dengan image lama:

   docker run -d ... registry.gitlab.com/nodefluxio/fremis-n:v1.9.0-cpu httpserver ...

4. Verifikasi:

   curl http://localhost:4003/health

Diagnosis & Logs

Panduan troubleshooting tinggal di halaman fitur masing-masing — lebih dekat ke konteks penggunaan:

• Recognition tidak akurat / threshold tuning — 1:N Search — Tips & Troubleshooting
• Enrollment ditolak / tidak muncul di recognition — Enrollment — Tips & Troubleshooting
• Latency tinggi, throughput rendah, HTTP 429 — Developer Guide — Performance Issues
• Service tidak start / 401-403 lisensi — Services — License & Connectivity Issues
• Database error saat startup, data hilang setelah restart — Installation — Database & Storage Issues
• Coordinator error, partition imbalance — Cluster Sharding — Troubleshooting Cluster