Copy page

Pendahuluan

Quickstart

Quickstart

Halaman ini menuntun Anda menjalankan stack OmniStream end-to-end pada mesin pengembangan. Target: login ke UI sebagai admin, menerima webhook uji, dan mengirim pesan balasan lewat salah satu saluran.

Prasyarat

• Docker Desktop atau Docker Engine + Docker Compose plugin.
• Rust stable (rustup default stable). Proyek tidak memerlukan nightly.
• Node.js 20+ dan npm untuk frontend SvelteKit.
• psql client untuk menjalankan skrip seed admin.
• (Opsional) Python 3 untuk menjalankan scripts/e2e_test.py.

1. Clone dan siapkan .env

Code
git clone https://github.com/<org>/omnistream.git
cd omnistream
cp .env.example .env

Variabel minimal yang harus diisi supaya layanan dapat start (semua berasal dari .env.example):

Variabel	Nilai dev	Keterangan
DATABASE_URL	postgres://omnistream:secret@localhost:5432/omnistream	Tidak ada default fallback — wajib diisi
MONGODB_URI	mongodb://omnistream:secret@localhost:27017	Wajib diisi
MONGODB_DATABASE	omnistream	Nama database Mongo yang dipakai
REDIS_URL	redis://localhost:6379	Untuk pub/sub real-time
KAFKA_BROKERS	localhost:9092	Redpanda broker
JWT_SECRET	string acak min 32 karakter	Wajib; validator akan menolak yang lebih pendek
JWT_EXPIRATION_HOURS	24	Durasi token access
META_APP_SECRET, META_VERIFY_TOKEN	(opsional di dev)	Dipakai saat Anda menguji webhook WhatsApp/Instagram
SMTP_HOST, SMTP_PORT	mailpit, 1025	Default Mailpit di docker-compose
SMTP_FROM_ADDRESS	noreply@omnistream.local	Alamat pengirim email keluar
SMTP_ENCRYPTION	none	Untuk Mailpit; gunakan starttls di produksi

Catatan: Jangan menambahkan variabel yang tidak ada di .env.example. Semua variabel yang dikenal kode berasal dari sana.

2. Jalankan infrastruktur

docker-compose.yml menyediakan PostgreSQL, MongoDB, Redis, Redpanda, MinIO, dan Mailpit. Untuk development Rust lokal, Anda cukup menyalakan infrastrukturnya:

Code
docker compose up -d postgres mongodb redis redpanda minio minio-init mailpit

Verifikasi:

Code
docker compose ps

Semua layanan harus healthy/running. Port yang bisa Anda sentuh:

• PostgreSQL → localhost:5432
• MongoDB → localhost:27017
• Redis → localhost:6379
• Redpanda (Kafka) → localhost:9092
• MinIO API → localhost:9000, console localhost:9001
• Mailpit SMTP → localhost:1025, web UI http://localhost:8025

Migrasi SQL dijalankan otomatis saat crate pertama kali konek ke PostgreSQL (sqlx::migrate! dari omni-common). 41 file migrasi ada di migrations/ (verifikasi: find migrations -name "*.sql" | wc -l).

3. Seed akun admin default

Jalankan skrip seed supaya Anda bisa login ke UI:

Code
psql "$DATABASE_URL" -f scripts/seed_agents.sql

Skrip ini membuat:

• admin@omnistream.com / admin123 (role admin)

Ganti password segera setelah login pertama.

4. Build workspace Rust

Code
cargo build --workspace

Pada Windows/Docker Desktop, cargo test --workspace bisa OOM karena rdkafka-sys. Gunakan per-crate saat menguji:

Code
cargo test -p omni-common
cargo test -p chat-engine
# ... dst.

Alternatif lain adalah build via Docker:

Code
docker build -f Dockerfile.test -t omnistream-test .
docker run --rm omnistream-test

5. Jalankan layanan backend

Buka terminal terpisah untuk tiap binary yang ingin Anda jalankan. Urutan yang direkomendasikan di dev:

Code
# Terminal 1 — API REST utama
cargo run -p api-gateway

# Terminal 2 — WebSocket server
cargo run -p ws-server

# Terminal 3 — Webhook ingestor (satu binary, empat route)
cargo run -p webhook-ingestor

# Terminal 4 — Chat engine (satu binary, dispatch per saluran)
cargo run -p chat-engine

# Terminal 5 — Message sender (satu binary, dispatch per saluran)
cargo run -p message-sender

Tidak ada binary -whatsapp/-instagram/-email terpisah — webhook-ingestor, chat-engine, dan message-sender masing-masing adalah satu binary yang men-dispatch ke modul per saluran di dalam proses. Nama per-saluran yang masih muncul di CLAUDE.md adalah drift historis.

Log yang sukses terlihat seperti:

Code
INFO api_gateway: listening on 0.0.0.0:3000
INFO ws_server: listening on 0.0.0.0:3002
INFO webhook_ingestor: listening on 0.0.0.0:3001

6. Jalankan frontend

Code
cd frontend
npm install
npm run dev

Frontend SvelteKit akan hidup di http://localhost:4000. Login dengan admin@omnistream.com / admin123. API client otomatis menunjuk http://localhost:3000 dan ws://localhost:3002.

7. Kirim webhook uji (opsional)

Untuk menguji alur inbound tanpa konfigurasi Meta, kirim payload mentah WhatsApp ke webhook-ingestor:

Code
curl -X POST http://localhost:3001/webhook/whatsapp \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=<hmac-hex>" \
  -d @scripts/fixtures/whatsapp_text.json

Jika META_APP_SECRET kosong, verifikasi HMAC dilewati (tidak direkomendasikan untuk produksi). Percakapan baru akan muncul di UI dalam 1 detik melalui WebSocket.

8. Jalankan E2E test suite

Skrip Python menutup pipeline inbound + outbound dan memvalidasi event:

Code
python scripts/e2e_test.py

Skrip ini mengasumsikan seluruh layanan hidup di port default dan admin@omnistream.com sudah terseed.

Masalah umum

• ECONNREFUSED ke 5432/27017/6379/9092 — infrastruktur Docker belum start. Jalankan docker compose up -d <service>.
• JWT_SECRET must be at least 32 characters — isi JWT_SECRET minimal 32 karakter acak. Jangan pakai default.
• cargo test --workspace membeku atau OOM di Windows — build rdkafka-sys perlu CMake + librdkafka. Pakai cargo test -p <crate> atau docker build -f Dockerfile.test.
• Webhook masuk 401 InvalidSignature — META_APP_SECRET di .env tidak cocok dengan secret app Anda. Restart webhook-ingestor setelah mengubah nilai — tidak hot-reload.
• Config tests flaky — 6 test di omni-common::config saling meracuni state environment. Ini diketahui dan bukan regresi.

Lanjut ke Arsitektur Layanan atau langsung ke Autentikasi → JWT untuk memahami request chain API.