Referensi Konfigurasi

Pendahuluan

Dokumen ini memberikan referensi lengkap untuk semua pengaturan konfigurasi yang digunakan oleh backend Ravenxcope. Konfigurasi dikelola melalui sistem konfigurasi standar ASP.NET Core menggunakan file appsettings.json, dengan penimpaan (overrides) variabel lingkungan untuk penyebaran kontainer.

---

File Konfigurasi

File	Tujuan	Diabaikan Git
appsettings.json	Templat konfigurasi produksi	Tidak
appsettings.Development.json	Penimpaan lingkungan pengembangan	Ya

---

Pola Placeholder

appsettings.json produksi menggunakan placeholder kurung kurawal ganda untuk nilai yang harus disediakan saat runtime:

"Host": "{{PostgresqlSettings__Host}}"

Validasi konfigurasi saat startup mendeteksi placeholder ini dan menganggapnya sebagai nilai yang hilang, menyebabkan kegagalan startup jika tidak ditimpa oleh variabel lingkungan.

---

Bagian Konfigurasi

PostgresqlSettings

{
  "PostgresqlSettings": {
    "Host": "{{PostgresqlSettings__Host}}",
    "Port": "{{PostgresqlSettings__Port}}",
    "Username": "{{PostgresqlSettings__Username}}",
    "Password": "{{PostgresqlSettings__Password}}",
    "Database": "{{PostgresqlSettings__Database}}",
    "MaxPoolSize": "100"
  }
}

Kunci	Tipe	Default	Wajib	Validasi
Host	string	localhost	Ya	Tidak boleh kosong
Port	string	5432	Ya	Integer positif
Username	string	hduser	Ya	Tidak boleh kosong
Password	string	—	Ya	Tidak boleh kosong
Database	string	me	Ya	Tidak boleh kosong
MaxPoolSize	string	20	Tidak	—

Format string koneksi:

Host={Host};Port={Port};Username={Username};Password={Password};Database={Database};Maximum Pool Size={MaxPoolSize}

---

RedisSettings

{
  "RedisSettings": {
    "Host": "{{RedisSettings__Host}}",
    "Port": "{{RedisSettings__Port}}",
    "Password": "{{RedisSettings__Password}}",
    "DefaultDatabase": "{{RedisSettings__DefaultDatabase}}"
  }
}

Kunci	Tipe	Default	Wajib	Validasi
Host	string	localhost	Ya	Tidak boleh kosong
Port	string	6379	Ya	Integer positif
Password	string	null	Tidak	—
DefaultDatabase	string	0	Tidak	—

Format string koneksi:

• Dengan kata sandi: {Host}:{Port},password={Password},defaultDatabase={DefaultDatabase}
• Tanpa kata sandi: {Host}:{Port},defaultDatabase={DefaultDatabase}

---

JwtSettings

{
  "JwtSettings": {
    "Secret": "{{JwtSettings__Secret}}",
    "Issuer": "{{JwtSettings__Issuer}}",
    "Audience": "{{JwtSettings__Audience}}",
    "ExpiryMinutes": 1440
  }
}

Kunci	Tipe	Default	Wajib	Catatan
Secret	string	—	Ya	Rekomendasi min 32 kar
Issuer	string	Ravenxcope.Backend	Tidak	Klaim issuer JWT
Audience	string	RavenxcopeUsers	Tidak	Klaim audience JWT
ExpiryMinutes	int	1440	Tidak	Masa berlaku token (24 jam)

Peringatan Keamanan: Jika Secret lebih pendek dari 32 karakter, peringatan startup akan dikeluarkan. JwtService akan melempar InvalidOperationException jika rahasia kosong atau kurang dari 32 karakter.

---

InfluxDb

{
  "InfluxDb": {
    "Url": "{{InfluxDb__Url}}",
    "Token": "{{InfluxDb__Token}}",
    "Org": "{{InfluxDb__Org}}",
    "Bucket": "{{InfluxDb__Bucket}}",
    "Precision": "ms",
    "TimeoutSeconds": 30
  }
}

Kunci	Tipe	Default	Wajib
Url	string	—	Ya
Token	string	—	Ya
Org	string	—	Ya
Bucket	string	—	Ya
Precision	string	ms	Tidak
TimeoutSeconds	int	30	Tidak

---

OpenSearch

{
  "OpenSearch": {
    "Url": "{{OpenSearch__Url}}",
    "Username": "{{OpenSearch__Username}}",
    "Password": "{{OpenSearch__Password}}",
    "IndexName": "{{OpenSearch__IndexName}}"
  }
}

Kunci	Tipe	Default	Wajib
Url	string	https://localhost:9200	Ya
Username	string	admin	Ya
Password	string	—	Ya
IndexName	string	mataelang-sensor-events-stream	Ya

---

Kunci Integrasi dan Runtime

{
  "AnsibleSettings": { "ServiceUrl": "{{AnsibleSettings__ServiceUrl}}" },
  "SensorApiSettings": { "ApiKey": "{{SensorApiSettings__ApiKey}}" },
  "SensorSettings": {
    "HeartbeatTimeoutMinutes": "{{SensorSettings__HeartbeatTimeoutMinutes}}",
    "ProvisioningSudoPassword": "{{SensorSettings__ProvisioningSudoPassword}}"
  },
  "OpenSearchAnalytics": {
    "DefaultTimeoutSeconds": "{{OpenSearchAnalytics__DefaultTimeoutSeconds}}",
    "DashboardTimeoutSeconds": "{{OpenSearchAnalytics__DashboardTimeoutSeconds}}",
    "AggregationTimeoutSeconds": "{{OpenSearchAnalytics__AggregationTimeoutSeconds}}",
    "ListQueryTimeoutSeconds": "{{OpenSearchAnalytics__ListQueryTimeoutSeconds}}"
  },
  "AnalyticsCacheWarming": {
    "Enabled": "{{AnalyticsCacheWarming__Enabled}}",
    "IntervalMinutes": "{{AnalyticsCacheWarming__IntervalMinutes}}",
    "InitialDelaySeconds": "{{AnalyticsCacheWarming__InitialDelaySeconds}}"
  },
  "DockerRegistry": {
    "Registry": "{{DockerRegistry__Registry}}",
    "Username": "{{DockerRegistry__Username}}",
    "Password": "{{DockerRegistry__Password}}"
  },
  "DataCollector": {
    "Endpoint": "{{DataCollector__Endpoint}}",
    "Port": "{{DataCollector__Port}}"
  },
  "BackendUrl": "{{BackendUrl}}"
}

Kunci	Tipe	Default	Wajib	Validasi
AnsibleSettings:ServiceUrl	string	—	Ya	Tidak boleh kosong
SensorApiSettings:ApiKey	string	—	Ya	Bukan placeholder
SensorSettings:HeartbeatTimeoutMinutes	int	1	Tidak	—
SensorSettings:ProvisioningSudoPassword	string	—	Ya	Tidak boleh kosong
OpenSearchAnalytics:DefaultTimeoutSeconds	int	20	Tidak	Integer positif (disarankan)
OpenSearchAnalytics:DashboardTimeoutSeconds	int	30	Tidak	Integer positif (disarankan)
OpenSearchAnalytics:AggregationTimeoutSeconds	int	15	Tidak	Integer positif (disarankan)
OpenSearchAnalytics:ListQueryTimeoutSeconds	int	25	Tidak	Integer positif (disarankan)
AnalyticsCacheWarming:Enabled	bool	true	Tidak	—
AnalyticsCacheWarming:IntervalMinutes	int	5	Tidak	Integer positif (disarankan)
AnalyticsCacheWarming:InitialDelaySeconds	int	20	Tidak	Integer non-negatif (disarankan)
DockerRegistry:Registry	string	—	Tidak	—
DockerRegistry:Username	string	—	Tidak	—
DockerRegistry:Password	string	—	Tidak	—
DataCollector:Endpoint	string	—	Ya	Tidak boleh kosong
DataCollector:Port	string	—	Ya	Integer positif
BackendUrl	string	—	Ya	Tidak boleh kosong

---

Kontrol Migrasi Database

{
  "Database": {
    "AutoMigrate": true,
    "MigrationMaxRetries": 10,
    "MigrationRetryDelaySeconds": 5
  }
}

Kunci	Tipe	Default	Deskripsi
AutoMigrate	bool	true	Jalankan migrasi EF Core saat startup
MigrationMaxRetries	int	10	Jumlah maksimal percobaan ulang migrasi
MigrationRetryDelaySeconds	int	5	Penundaan antar percobaan (detik)

---

Logging (Serilog)

{
  "Serilog": {
    "Using": ["Serilog.Sinks.Console"],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.AspNetCore": "Warning",
        "Microsoft.Hosting.Lifetime": "Information"
      }
    },
    "Enrich": ["FromLogContext", "WithMachineName"],
    "WriteTo": [
      {
        "Name": "Console",
        "Args": {
          "outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {SourceContext} {Message:lj}{NewLine}{Exception}"
        }
      }
    ]
  }
}

---

Pemetaan Variabel Lingkungan

Untuk penyebaran kontainer, gunakan konvensi garis bawah ganda ASP.NET Core untuk menimpa nilai appsettings:

Kunci appsettings	Variabel Lingkungan
JwtSettings:Secret	JwtSettings__Secret
PostgresqlSettings:Host	PostgresqlSettings__Host
PostgresqlSettings:Port	PostgresqlSettings__Port
RedisSettings:Host	RedisSettings__Host
OpenSearch:Url	OpenSearch__Url
InfluxDb:Url	InfluxDb__Url
BackendUrl	BackendUrl
DataCollector:Endpoint	DataCollector__Endpoint

---

Ringkasan Kelas Typed Options

Semua kelas opsi didefinisikan dalam Extensions/BackendConfiguration.cs:

Kelas	Bagian Konfigurasi	Catatan
PostgresqlSettingsOptions	PostgresqlSettings	Termasuk MaxPoolSize
RedisSettingsOptions	RedisSettings	Kata sandi bisa null
JwtSettingsOptions	JwtSettings	Termasuk ExpiryMinutes
InfluxDbOptions	InfluxDb	Semua field wajib
OpenSearchOptions	OpenSearch	Memiliki default yang masuk akal
AnsibleSettingsOptions	AnsibleSettings	Hanya ServiceUrl
SensorApiSettingsOptions	SensorApiSettings	Hanya ApiKey
DataCollectorOptions	DataCollector	Endpoint dan Port
DockerRegistryOptions	DockerRegistry	Registry, Username, Password
SensorSettingsOptions	SensorSettings	HeartbeatTimeoutMinutes, ProvisioningSudoPassword
OpenSearchAnalyticsOptions	OpenSearchAnalytics	Kontrol timeout jenis kueri
AnalyticsCacheWarmingOptions	AnalyticsCacheWarming	Kontrol jadwal pemanasan cache
DatabaseOptions	Database	Kontrol migrasi
BackendAppOptions	(komposit)	Url dari kunci BackendUrl
SensorRuntimeOptions	(komposit)	Menggabungkan beberapa bagian

---

Validasi Preflight

Gunakan defense_center/scripts/preflight-env.sh untuk mendeteksi nilai konfigurasi yang hilang atau lemah sebelum startup Docker Compose:

sh defense_center/scripts/preflight-env.sh defense_center/.env

Skrip ini memeriksa:

• Variabel lingkungan wajib yang hilang
• Nilai placeholder yang belum diganti
• Rahasia JWT yang lemah