Konfigurasi Agent BYOC

Setiap pengaturan yang dibaca Raklane Node Agent di server Anda, lokasinya, dan cara mengubahnya dengan aman.

Fri Oct 02 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

Raklane Node Agent di server BYOC Anda dikonfigurasi dengan environment variable. Perintah instalasi menuliskan yang dibutuhkan, dan setiap pengaturan lain punya nilai bawaan yang masuk akal. Anda hanya perlu halaman ini untuk menyesuaikan sesuatu: log yang lebih detail saat debugging, lokasi penyimpanan database yang berbeda, mematikan pembaruan otomatis, dan sebagainya.

Lokasi pengaturan

Agent berjalan sebagai layanan systemd raklane-agent, yang memuat pengaturannya dari:

/etc/default/raklane-agent

File ini berformat KEY=VALUE biasa, satu pengaturan per baris, dan hanya bisa dibaca root (mode 600). Tepat setelah instalasi, isinya seperti ini:

RAKLANE_CONTROL_PLANE_URL=https://your-raklane.example.com
RAKLANE_CONTROL_PLANE_GRPC_ADDR=your-raklane.example.com:8443
RAKLANE_ENROLLMENT_TOKEN=...
RAKLANE_AGENT_STATE_DIR=/etc/raklane-agent

Pengaturan apa pun yang tidak ada di file memakai nilai bawaannya (lihat referensi di bawah).

Mengubah pengaturan

Edit file sebagai root:
```
sudo nano /etc/default/raklane-agent
```
Tambahkan atau ubah baris yang dibutuhkan, misalnya:
```
RAKLANE_LOG_LEVEL=debug
```
Restart agent agar perubahannya terbaca:
```
sudo systemctl restart raklane-agent
```

Pastikan agent kembali sehat:

sudo systemctl status raklane-agent
sudo journalctl -u raklane-agent -f

Me-restart agent tidak me-restart aplikasi atau database Anda. Semuanya adalah container Docker dan tetap berjalan. Server akan tampil Offline selama beberapa detik di dashboard sementara agent terhubung kembali.

Menjalankan ulang perintah instalasi akan menulis ulang file ini hanya dengan empat pengaturan di atas, sehingga pengaturan yang Anda tambahkan akan hilang. Salin dulu baris kustom Anda, lalu tambahkan kembali setelahnya.

Referensi pengaturan

Durasi ditulis sebagai angka dengan satuan: 30s, 5m, 1h, 1h30m. Jika durasi tidak bisa dibaca, agent diam-diam memakai nilai bawaan, jadi periksa kembali penulisannya.

Koneksi

Pengaturan ini ditulis oleh perintah instalasi. Anda hanya perlu mengubahnya jika instalasi Raklane pindah ke alamat baru.

Variabel	Bawaan	Fungsi
`RAKLANE_CONTROL_PLANE_URL`	— (diatur saat instalasi)	URL instalasi Raklane Anda. Dipakai untuk mendaftar dan mengunduh pembaruan agent.
`RAKLANE_CONTROL_PLANE_GRPC_ADDR`	— (diatur saat instalasi)	`host:port` endpoint koneksi agent di Raklane. Agent menjaga satu koneksi terenkripsi tetap terbuka ke alamat ini. Biasanya hostname instalasi Anda di port `8443`.
`RAKLANE_ENROLLMENT_TOKEN`	— (diatur saat instalasi)	Token sekali pakai untuk mendaftar. Hanya dibaca saat pertama kali menyala, sebelum server punya sertifikat. Setelah itu diabaikan dan tidak bisa dipakai ulang, jadi aman dibiarkan di file.

Identitas dan penyimpanan

Variabel	Bawaan	Fungsi
`RAKLANE_AGENT_STATE_DIR`	`/etc/raklane-agent`	Tempat agent menyimpan identitasnya: sertifikat, private key, dan sertifikat CA Raklane. Jaga kerahasiaan direktori ini dan ikut sertakan dalam backup server.
`RAKLANE_DATABASE_VOLUME_ROOT`	`/var/lib/raklane-agent`	Tempat database di server ini menyimpan datanya. Arahkan ke disk yang lebih besar atau lebih cepat jika perlu — misalnya volume yang di-mount di `/mnt/data/raklane`.

Ubah lokasi penyimpanan hanya sebelum dipakai. Memindahkan RAKLANE_AGENT_STATE_DIR tanpa memindahkan file-filenya membuat agent mencoba mendaftar ulang, yang akan gagal karena token sudah terpakai. Mengubah RAKLANE_DATABASE_VOLUME_ROOT hanya berlaku untuk database yang dibuat setelahnya. Database yang sudah ada tetap menyimpan datanya di lokasi lama, jadi atur ini sebelum membuat database apa pun di server.

Kesehatan dan metrik

Variabel	Bawaan	Fungsi
`RAKLANE_AGENT_HEARTBEAT_INTERVAL`	`15s`	Seberapa sering agent memberi tahu Raklane bahwa ia masih hidup. Raklane menganggap server tidak melapor jika tidak terdengar kabarnya sekitar dua menit, jadi jaga nilainya jauh di bawah itu — interval yang lebih panjang membuat dashboard lebih lambat mendeteksi masalah, dan yang terlalu panjang membuat pemeriksaan Heartbeat gagal.
`RAKLANE_AGENT_METRICS_INTERVAL`	`15s`	Seberapa sering agent melaporkan statistik CPU, memori, dan container untuk halaman Metrics. Nilai lebih tinggi mengirim lebih sedikit data tetapi membuat grafik lebih kasar. `0` mematikan pelaporan metrik, sehingga tab Metrics aplikasi kosong; daftar proses live tetap berfungsi. Lihat Metrik & Proses.

Pembaruan otomatis

Variabel	Bawaan	Fungsi
`RAKLANE_AGENT_UPDATE_INTERVAL`	`1h`	Seberapa sering agent memeriksa apakah Raklane menyediakan build agent yang berbeda. Jika ya, agent mengunduhnya, memverifikasi checksum, lalu restart ke versi baru di tempat (container tetap berjalan). Ada jeda acak kecil agar banyak server tidak memperbarui di saat yang sama. `0` mematikan pembaruan otomatis.

Jika Anda mematikan pembaruan otomatis, jaga agent tetap terbaru dengan menjalankan ulang perintah instalasi sesekali (ingat bahwa perintah itu menulis ulang file pengaturan). Agent yang tertinggal jauh dari instalasi Raklane mungkin melewatkan fitur-fitur baru.

Penghentian

Pengaturan ini mengatur apa yang terjadi saat agent sendiri berhenti — misalnya saat systemctl restart, OS dimatikan, atau pembaruan otomatis.

Variabel	Bawaan	Fungsi
`RAKLANE_AGENT_SHUTDOWN_WARN_PERIOD`	`0`	Berapa lama agent menunggu setelah diminta berhenti sebelum mulai mematikan diri. Memberi waktu bagi pekerjaan yang sedang berjalan (misalnya koneksi yang sedang diteruskan) untuk selesai.
`RAKLANE_AGENT_SHUTDOWN_TIMEOUT`	`10s`	Waktu maksimal untuk setiap langkah penghentian sebelum dihentikan paksa.

Logging

Variabel	Bawaan	Fungsi
`RAKLANE_LOG_LEVEL`	`info`	Seberapa banyak yang dicatat agent: `debug`, `info`, `warn`, atau `error`. Gunakan `debug` saat memecahkan masalah, lalu kembalikan.
`RAKLANE_LOG_FORMAT`	`json`	`json` menulis satu objek JSON per baris, cocok untuk pengirim log. `text` menulis baris ringkas yang mudah dibaca manusia, lebih nyaman dibaca di `journalctl`.

Resep umum

Membaca log agent dengan nyaman saat debugging:

RAKLANE_LOG_LEVEL=debug
RAKLANE_LOG_FORMAT=text

Menyimpan data database di disk terpisah (sebelum membuat database apa pun):

RAKLANE_DATABASE_VOLUME_ROOT=/mnt/data/raklane

Mengunci versi agent (tanpa pembaruan otomatis):

RAKLANE_AGENT_UPDATE_INTERVAL=0

Instalasi Raklane pindah ke alamat baru: perbarui kedua pengaturan koneksi, lalu restart.

RAKLANE_CONTROL_PLANE_URL=https://new-raklane.example.com
RAKLANE_CONTROL_PLANE_GRPC_ADDR=new-raklane.example.com:8443

Jangan lupa menjalankan sudo systemctl restart raklane-agent setelah setiap perubahan.

Pengaturan yang tidak ada di agent

Beberapa hal ditentukan oleh instalasi Raklane Anda, bukan oleh agent, sehingga tidak bisa diubah dari server Anda:

Domain URL bawaan aplikasi Anda (domain BYOC di my-app.203.0.113.10.byoc.example.com).
Berapa lama Raklane menunggu heartbeat sebelum server dianggap tidak melapor.
Apakah database eksternal diteruskan lewat Raklane atau dijangkau langsung di server Anda.
Image registry tempat server Anda menarik image.

Tanyakan kepada pengelola instalasi Raklane Anda jika ada yang perlu diubah.

Lihat juga

Mengelola Server BYOC — pemeriksaan status, pemeliharaan, menghentikan server.
Pemecahan Masalah BYOC — membaca log agent untuk mendiagnosis masalah.