Installation

Halaman ini berisi perintah Docker konkret untuk menjalankan FREMIS-N. Pilih alur yang sesuai dengan keputusan topologi Anda — jika belum memutuskan, baca Prerequisites terlebih dahulu.

Pilih Image Runtime

FREMIS-N didistribusikan sebagai Docker image di GitLab Container Registry Nodeflux. Pilih tag image sesuai runtime yang sudah ditentukan saat fase Prerequisites:

Ganti <version> dengan versi rilis yang diberikan oleh tim Nodeflux (contoh: v1.2.3). Login ke registry terlebih dahulu menggunakan credential GitLab Anda:

docker login registry.gitlab.com -u <gitlab-username>

Tarik image yang dibutuhkan:

docker pull registry.gitlab.com/nodefluxio/fremis-n:<version>-cpu

Quick Start: Standalone

Untuk menjalankan satu node FREMIS-N secara cepat dengan Docker, jalankan perintah berikut. Ganti parameter database dan lisensi sesuai lingkungan Anda.

docker run -d \
  --name fremis-n \
  --net=host \
  --restart unless-stopped \
  registry.gitlab.com/nodefluxio/fremis-n:<version>-cpu \
  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

docker run -d \
  --name fremis-n \
  --gpus all \
  --net=host \
  --restart unless-stopped \
  registry.gitlab.com/nodefluxio/fremis-n:<version>-gpu \
  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

Container sekarang berjalan dan mengekspos API di port 4003 host. Verifikasi dengan:

curl http://localhost:4003/health

Respons HTTP 200 menunjukkan node siap menerima traffic. Anda juga dapat memeriksa log container:

docker logs -f fremis-n

Inisialisasi Database (Sekali Saja)

Sebelum node pertama dapat menyimpan data, schema database harus diinisialisasi. Jalankan subcommand initdb melalui Docker:

docker run --rm \
  --net=host \
  registry.gitlab.com/nodefluxio/fremis-n:<version>-cpu \
  initdb \
    --db-address 127.0.0.1 \
    --db-port 5432 \
    --db-name fremis_production \
    --db-username postgres \
    --db-password secure_password

Tunggu hingga muncul pesan DB Initialization success, lalu lanjutkan menjalankan httpserver. Anda hanya perlu menjalankan ini sekali per database — bukan setiap kali container di-restart.

Setup Cluster

Untuk deployment cluster, Anda perlu menjalankan setiap node dengan partition range-nya, membuat file konfigurasi coordinator, lalu menjalankan coordinator container sebagai entry point untuk klien.

docker run -d \
  --name fremis-n-node1 \
  --net=host \
  --restart unless-stopped \
  registry.gitlab.com/nodefluxio/fremis-n:<version>-cpu \
  httpserver \
    --storage postgres \
    --db-address db.internal \
    --db-name fremis_cluster \
    --db-username postgres \
    --db-password secure_password \
    --access-key YOUR_LICENSE_KEY \
    --secret-key YOUR_LICENSE_SECRET \
    --partition-start 0 \
    --partition-end 127 \
    --listen-port 4003

docker run -d \
  --name fremis-n-node2 \
  --net=host \
  --restart unless-stopped \
  registry.gitlab.com/nodefluxio/fremis-n:<version>-cpu \
  httpserver \
    --storage postgres \
    --db-address db.internal \
    --db-name fremis_cluster \
    --db-username postgres \
    --db-password secure_password \
    --access-key YOUR_LICENSE_KEY \
    --secret-key YOUR_LICENSE_SECRET \
    --partition-start 128 \
    --partition-end 255 \
    --listen-port 4003

version: "v1"
nodes:
  - address: "node1.internal:4003"
    partition_start: 0
    partition_end: 127
  - address: "node2.internal:4003"
    partition_start: 128
    partition_end: 255

docker run -d \
  --name fremis-n-coordinator \
  --net=host \
  --restart unless-stopped \
  -v $(pwd)/coordinator_config.yml:/app/coordinator_config.yml:ro \
  registry.gitlab.com/nodefluxio/fremis-n:<version>-cpu \
  coordinator \
    --access-key YOUR_LICENSE_KEY \
    --secret-key YOUR_LICENSE_SECRET \
    --listen-port 4005 \
    --config-path /app/coordinator_config.yml

curl http://localhost:4005/health

curl -X POST http://localhost:4005/api/v1/keyspaces/test/enrollments \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "test-001", "images": [{"url": "https://..."}]}'

Pertimbangan Jaringan Cluster

Dalam mode cluster, coordinator berkomunikasi dengan setiap node untuk setiap request yang membutuhkan data dari lebih dari satu partition. Latency jaringan antar node berkontribusi langsung pada latency yang dirasakan klien.

Rekomendasi: Jalankan semua node dan coordinator dalam satu data center atau private network dengan latency antar node di bawah 1 ms. Hindari menempatkan node di lokasi geografis berbeda atau melewati jaringan publik.

Mengelola Container

Operasi rutin Docker untuk node FREMIS-N:

docker logs -f fremis-n          # ikuti log real-time
docker stop fremis-n             # hentikan container
docker start fremis-n            # jalankan kembali container yang ada
docker restart fremis-n          # restart container
docker rm -f fremis-n            # hapus container (data di Postgres tetap aman)

Untuk upgrade ke versi baru, tarik image baru, hentikan container lama, lalu jalankan ulang docker run dengan tag versi yang baru. Data tetap aman selama database eksternal tidak terpengaruh.

Database & Storage Issues

Container gagal start karena masalah database, atau data hilang setelah restart. Dua skenario paling umum.

Container Exits — Database Error

Container keluar segera setelah docker run dengan error startup yang mereferensikan database connection atau initialization failure.

1. Cek log container. Jalankan docker logs fremis-n untuk melihat pesan error lengkap dari proses di dalam container.
2. Pastikan database server running. Cek service PostgreSQL di host yang dikonfigurasi. Test koneksi manual dari host: psql -h <db-address> -U <username> -d <db-name>.
3. Verifikasi credentials. Pastikan --db-address, --db-port, --db-username, --db-password, dan --db-name cocok dengan database yang berjalan. Jika container menggunakan --net=host, 127.0.0.1 mengarah ke host. Jika tidak menggunakan --net=host, ganti dengan alamat yang dapat dijangkau dari container (mis. host.docker.internal di Docker Desktop).
4. Jalankan initdb jika schema belum ada. Gunakan perintah pada bagian Inisialisasi Database. Tunggu hingga melihat DB Initialization success, lalu jalankan ulang container httpserver.
5. Cek disk space. Pastikan /var/lib/postgresql (atau lokasi data database Anda) memiliki space cukup.

Data Hilang Setelah Restart

Enrollment berhasil di-insert (HTTP 200 dengan variation), tetapi setelah restart container data menghilang.

1. Verifikasi persistent storage database. Jika PostgreSQL juga berjalan sebagai container, volume database harus di-mount dari path persistent — bukan path internal container. Contoh: docker run -v /persistent/path:/var/lib/postgresql/data:rw postgres:15.
2. Verifikasi alamat database. --db-address dan --db-port harus mengarah ke database server yang persistent, bukan container ephemeral. Container FREMIS-N tidak menyimpan data enrollment di filesystem-nya sendiri — semua data ada di PostgreSQL.
3. Query database langsung. Sebelum restart, jalankan SELECT COUNT(*) FROM enrollments; di database. Jika data sudah tidak ada di database (bukan hanya di runtime FREMIS-N), kemungkinan besar volume PostgreSQL tidak persistent.
4. Reconfigure dan restart dengan persistent volume yang benar pada container PostgreSQL; data baru akan bertahan.

Selanjutnya

• Services & Ports — port apa saja yang diekspos FREMIS-N dan komponen monitoring
• Configuration Reference — referensi lengkap semua parameter startup, monitoring, backup, dan upgrade