Instalasi dengan Docker Compose

Menjalankan Lenz beserta database, Visionaire, dan Fremis-N dalam satu file Docker Compose, lalu memverifikasi, memperbarui, dan mencadangkan deployment.

Pengenalan

Lenz didistribusikan sebagai satu image Docker yang sudah memuat dashboard web dan backend API. Agar bisa dipakai, image ini membutuhkan tiga layanan pendamping: database PostgreSQL, Visionaire (AI engine untuk analitik video), dan Fremis-N (engine face recognition). Halaman ini memandu Anda menjalankan keempatnya di satu server dengan Docker Compose.

Halaman ini ditujukan untuk admin sistem atau tim deployment. Jika Lenz sudah berjalan dan Anda hanya ingin login, lanjut ke Memulai.

Arsitektur Deployment

Semua service berjalan dengan network_mode: host, sehingga mereka saling menjangkau lewat 127.0.0.1 dan port yang dipakai langsung terbuka di host.

Service	Image	Port host	Database
`lenz`	`registry.gitlab.com/nodefluxio/lenz`	`4003` (web), `6015` (API internal)	`vdashboard`
`db`	`timescale/timescaledb-ha:pg17`	`5432`	—
`visionaire`	`nodefluxio/visionaire4`	`4004`	`nfvisionaire`
`fremis`	`registry.gitlab.com/nodefluxio/fremis-n`	`4005`	`fremisn`

Persyaratan

Komponen	Kebutuhan
Sistem operasi	Linux x86-64 (Ubuntu 22.04/24.04 direkomendasikan).
Docker	Docker Engine dengan plugin Compose v2 (`docker compose version`).
GPU	GPU NVIDIA dengan driver dan NVIDIA Container Toolkit terpasang, untuk Visionaire dan Fremis-N varian `-gpu`. Ikuti Install Dependencies.
Port	`4003`, `4004`, `4005`, `5432`, dan `6015` belum dipakai proses lain di host.
Akses registry	Akun GitLab dengan akses ke registry `nodefluxio`, dan akses ke image Visionaire di Docker Hub.
Lisensi	Access key dan secret key untuk Fremis-N, serta access key, secret key, dan deployment key untuk Visionaire. Diterbitkan oleh Nodeflux.

Database Lenz wajib memiliki extension timescaledb, timescaledb_toolkit, vector, dan vectorscale. Migrasi Lenz membuat extension tersebut saat startup dan akan gagal di image PostgreSQL biasa. Image timescale/timescaledb-ha:pg17 sudah menyertakan keempatnya.

Cara Menggunakan

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

Gunakan personal access token (scope read_registry) sebagai password GitLab. Hubungi Nodeflux jika akun Anda belum memiliki akses.

Siapkan direktori deployment

mkdir -p /opt/lenz && cd /opt/lenz

Direktori ini akan berisi dua file: .env (versi image dan rahasia) dan docker-compose.yml.

Buat file `.env`

.env

# Versi image — selalu gunakan tag versi untuk produksi, bukan latest
LENZ_VERSION=4.0.5
VISIONAIRE_VERSION=4.57.29
FREMISN_VERSION=v2.13.7-gpu

# Password superuser PostgreSQL (dipakai semua service)
DB_PASSWORD=ganti-dengan-password-kuat

# Kunci penanda tangan JWT Lenz — buat dengan: openssl rand -hex 32
SECRET_TOKEN=ganti-dengan-string-acak-panjang

# Lisensi dari Nodeflux
VISIONAIRE_ACCESS_KEY=
VISIONAIRE_SECRET_KEY=
VISIONAIRE_DEPLOYMENT_KEY=
FREMISN_ACCESS_KEY=
FREMISN_SECRET_KEY=

Batasi akses file ini karena berisi rahasia:

chmod 600 .env

Jangan biarkan SECRET_TOKEN kosong. Lenz memakai nilai ini untuk menandatangani access token dan refresh token; bila kosong, token ditandatangani dengan kunci kosong. Mengganti nilainya kemudian membuat semua sesi aktif tidak valid dan pengguna harus login ulang.

Buat file `docker-compose.yml`

docker-compose.yml

services:
  db:
    image: timescale/timescaledb-ha:pg17
    network_mode: host
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: vdashboard
    volumes:
      - db_data:/home/postgres/pgdata/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 30

  # Membuat database untuk Fremis-N dan Visionaire, lalu berhenti.
  db-init:
    image: timescale/timescaledb-ha:pg17
    network_mode: host
    restart: "no"
    depends_on:
      db:
        condition: service_healthy
    environment:
      PGPASSWORD: ${DB_PASSWORD}
    entrypoint: >
      bash -c "
        psql -h 127.0.0.1 -U postgres -c 'CREATE DATABASE fremisn;' || true;
        psql -h 127.0.0.1 -U postgres -c 'CREATE DATABASE nfvisionaire;' || true
      "

  lenz:
    image: registry.gitlab.com/nodefluxio/lenz:${LENZ_VERSION}
    network_mode: host
    restart: unless-stopped
    environment:
      DB_HOST: 127.0.0.1:5432
      DB_USERNAME: postgres
      DB_PASSWORD: ${DB_PASSWORD}
      DB_NAME: vdashboard
      SECRET_TOKEN: ${SECRET_TOKEN}
      VISIONAIRE_HOST: 127.0.0.1:4004
      FREMISN_URL: http://127.0.0.1:4005/v1
      TZ: Asia/Jakarta
    depends_on:
      db:
        condition: service_healthy

  fremis:
    image: registry.gitlab.com/nodefluxio/fremis-n:${FREMISN_VERSION}
    network_mode: host
    restart: unless-stopped
    command:
      - httpserver
      - --storage=postgres
      - --db-address=127.0.0.1
      - --db-port=5432
      - --db-name=fremisn
      - --db-username=postgres
      - --db-password=${DB_PASSWORD}
      - --access-key=${FREMISN_ACCESS_KEY}
      - --secret-key=${FREMISN_SECRET_KEY}
      - --listen-port=4005
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    depends_on:
      db-init:
        condition: service_completed_successfully

  visionaire:
    image: nodefluxio/visionaire4:${VISIONAIRE_VERSION}
    network_mode: host
    restart: unless-stopped
    shm_size: 16gb
    command:
      - --access-key=${VISIONAIRE_ACCESS_KEY}
      - --secret-key=${VISIONAIRE_SECRET_KEY}
      - --deployment-key=${VISIONAIRE_DEPLOYMENT_KEY}
      - --db-host=127.0.0.1
      - --db-password=${DB_PASSWORD}
      - --fr-address=127.0.0.1:4005
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    depends_on:
      db-init:
        condition: service_completed_successfully

volumes:
  db_data:

Service db-init hanya membuat database fremisn dan nfvisionaire, lalu keluar. Status Exited (0) pada service ini normal. Database vdashboard untuk Lenz dibuat oleh container db itu sendiri lewat POSTGRES_DB.

Inisialisasi schema Fremis-N (sekali saja)

Jalankan database terlebih dahulu, lalu inisialisasi schema Fremis-N sebelum service-nya menyala untuk pertama kali:

docker compose up -d db db-init
docker compose run --rm fremis initdb \
  --db-address=127.0.0.1 \
  --db-port=5432 \
  --db-name=fremisn \
  --db-username=postgres \
  --db-password="$(grep ^DB_PASSWORD= .env | cut -d= -f2-)"

Tunggu hingga muncul DB Initialization success. Langkah ini tidak perlu diulang saat restart atau upgrade. Detailnya ada di Instalasi Fremis-N.

Jalankan semua service

docker compose up -d
docker compose ps

Saat pertama kali menyala, Lenz menjalankan migrasi database dan seeder konfigurasi secara otomatis sebelum menerima request. Pada database kosong proses ini hanya beberapa detik, tetapi bisa lebih lama saat upgrade database yang sudah berisi banyak data. Pantau lognya:

docker compose logs -f lenz

Lenz siap dipakai setelah log menampilkan finished run database migration dan tidak ada error setelahnya.

Verifikasi

curl http://localhost:4003/api/version      # Lenz: versi image yang berjalan
curl http://localhost:4004/node_status      # Visionaire: status node dan lisensi
curl http://localhost:4005/health           # Fremis-N: HTTP 200 berarti siap

Buka http://<ip-server>:4003 di browser. Halaman login Lenz akan tampil.

Seeder membuat satu akun superadmin bawaan. Minta kredensial awalnya ke tim Nodeflux, login, lalu segera ganti password-nya di halaman Akun. Setelah itu buat user dan role untuk tim Anda di User & Access, dan lanjutkan dengan Memulai.

Konfigurasi

Environment Variable Lenz

Variabel berikut paling sering diatur. Semuanya dibaca saat container start, jadi setelah mengubahnya jalankan docker compose up -d lenz agar container dibuat ulang.

Prop

Type

Integration Lock

Request API yang memakai Authorization: Bearer wajib membawa header X-Integration-Signature, yaitu JWT pendek yang ditandatangani dengan secret integration lock. Anda tidak perlu mengonfigurasi apa pun: setiap kali container lenz dijalankan, Lenz membuat secret acak baru (32 byte) dan membagikannya hanya ke backend dan dashboard. Secret ini tidak ditulis ke disk, tidak muncul di environment, dan tidak bisa diambil lewat API.

Konsekuensinya bagi deployment:

Secret berganti setiap container start, termasuk saat restart, docker compose up -d yang membuat ulang container, dan upgrade. Tab dashboard yang masih terbuka dari sebelumnya akan menampilkan indikator Integration tidak sinkron dan request-nya ditolak 403 integration_lock. Pengguna cukup melakukan hard refresh (Ctrl+Shift+R / Cmd+Shift+R).
Integrasi berbasis API key tidak terpengaruh. Request dengan X-Api-Key tanpa header Authorization tidak perlu signature, sehingga tetap berjalan setelah restart. Arahkan semua integrasi pihak ketiga ke API key; lihat Otentikasi.

Jangan mengisi INTEGRATION_LOCK_SECRET di deployment produksi. Variabel ini adalah override untuk pengembangan dan pengujian integrator: nilainya menggantikan secret yang dibuat otomatis, tidak pernah berganti, dan terlihat oleh siapa pun yang bisa menjalankan docker inspect di server.

Argumen Container

Argumen ditulis di field command service lenz.

Argumen	Efek
`--offline-map`	Menyajikan peta dari file `.pmtiles` lokal alih-alih peta online. Lihat varian di bawah.
`--debug-mode`	Mengaktifkan log debug.

Varian Deployment

Untuk server tanpa akses internet, siapkan file peta indonesia.pmtiles di host, lalu tambahkan ke service lenz:

  lenz:
    # ...konfigurasi sebelumnya...
    command: ["--offline-map"]
    volumes:
      - /opt/lenz/maps:/var/maps
    environment:
      # ...variabel sebelumnya...
      MAPSOURCE_REGION: indonesia   # nama file tanpa .pmtiles

Lenz akan menyajikan /var/maps/<MAPSOURCE_REGION>.pmtiles ke peta di dashboard.

Jika Visionaire, Fremis-N, dan database sudah berjalan di server terpisah, cukup jalankan service lenz dan arahkan variabelnya ke alamat server tersebut. Dengan network bridge biasa, publikasikan port 4003:

docker-compose.yml

services:
  lenz:
    image: registry.gitlab.com/nodefluxio/lenz:${LENZ_VERSION}
    container_name: lenz
    restart: unless-stopped
    ports:
      - 4003:4003
    environment:
      DB_HOST: 10.0.0.10:5432
      DB_USERNAME: postgres
      DB_PASSWORD: ${DB_PASSWORD}
      DB_NAME: vdashboard
      SECRET_TOKEN: ${SECRET_TOKEN}
      VISIONAIRE_HOST: 10.0.0.11:4004
      FREMISN_URL: http://10.0.0.11:4005/v1

Pastikan database tujuan memenuhi syarat extension di atas dan dapat dijangkau dari container.

Pembaruan dan Backup

Backup database

Selalu backup sebelum upgrade, karena migrasi versi baru berjalan otomatis dan tidak dibatalkan saat Anda kembali ke image lama.

docker compose exec -T db pg_dump -U postgres -Fc vdashboard > vdashboard-$(date +%F).dump

Ganti versi dan tarik image

Ubah LENZ_VERSION (atau versi service lain) di .env, lalu:

docker compose pull
docker compose up -d
docker compose logs -f lenz

Migrasi versi baru dijalankan otomatis saat container start.

Untuk mengembalikan backup ke database kosong:

docker compose exec -T db pg_restore -U postgres -d vdashboard --clean --if-exists < vdashboard-2026-09-25.dump

docker compose down -v menghapus volume db_data beserta seluruh data Lenz, Visionaire, dan Fremis-N. Gunakan docker compose down tanpa -v untuk sekadar menghentikan service.

Instalasi dengan Docker Compose

Pengenalan

Arsitektur Deployment

Persyaratan

Cara Menggunakan

Siapkan direktori deployment

Buat file `.env`

Buat file `docker-compose.yml`

Inisialisasi schema Fremis-N (sekali saja)

Jalankan semua service

Verifikasi

Konfigurasi

Environment Variable Lenz

Integration Lock

Argumen Container

Varian Deployment

Pembaruan dan Backup

Backup database

Ganti versi dan tarik image

Tips & Troubleshooting

Memulai

Media Servers

Instalasi Visionaire

On this page

Instalasi dengan Docker Compose

Container lenz terus restart dengan error migrasi

Error 'address already in use' saat service start

Visionaire atau Fremis-N gagal start

Semua pengguna tiba-tiba harus login ulang

Setelah restart atau upgrade muncul 'Integration tidak sinkron' atau error 403 integration_lock

Dashboard tampil, tetapi stream atau enrollment wajah gagal

Memulai

Media Servers

Instalasi Visionaire

On this page