merica-dlh/merica

Fork 0

Files

T

syahril 851be0cda7

feat(appliance): initial release of MERICA standalone appliance v1.0.0

2026-10-21 17:16:46 +07:00

6.2 KiB

Raw Blame History

📦 Panduan Deployment & Build Mandiri — MERICA

Navigasi Cepat: 🏠 Pusat Dokumentasi | 🏛️ Arsitektur Platform | 📘 Integrasi Airflow External | 🎨 Panduan Pengguna Canvas

Panduan resmi bagi DevOps, System Administrator, dan Data Platform Engineer untuk instalasi, konfigurasi, build image mandiri, dan pemeliharaan MERICA Appliance.

💻 1. Spesifikasi Sistem & Prasyarat

Kebutuhan sumber daya perangkat keras tergantung pada mode deployment yang dipilih:

Komponen	Mode 1: Standalone Appliance (Rekomendasi Produksi)	Mode 2: All-in-One Demo (dengan Airflow & DB Lokal)
Peran	Hanya menjalankan antarmuka Canvas & API Gateway MERICA (Port 14000). Eksekusi pipeline didelegasikan ke Airflow eksternal.	Menjalankan MERICA + Apache Airflow 3 + Postgres + Redis dalam satu host untuk demo mandiri.
CPU	1 vCPU (x86_64)	4 vCPU (x86_64)
RAM	512 MB (Penggunaan aktual hanya `\sim` 100 MB)	8 GB
Disk	2 GB SSD	30 GB SSD
Sistem Operasi	Linux Ubuntu 20.04/22.04/24.04 LTS, RHEL 8/9, Debian 11/12, Rocky Linux	Sama
Runtime	Docker Engine `\ge` 24.0, Docker Compose v2	Sama

⚡ 2. Instalasi Cepat (Quick Start Sekali Klik)

Opsi A: Menggunakan Skrip Otomatis `setup.sh` (Paling Cepat)

Paket rilis MERICA dilengkapi dengan skrip instalasi cerdas setup.sh:

# 1. Buka direktori rilis MERICA
cd release/merica

# 2. Jalankan skrip setup
bash ./setup.sh

Skrip setup.sh secara otomatis akan:

Memeriksa ketersediaan Docker Engine dan Docker Compose v2.
Memeriksa ketersediaan berkas .env (jika belum ada, otomatis menyalin dari .env.example).
Memastikan direktori starter pipelines (./pipelines/) siap dengan permission yang sesuai.
Menjalankan kontainer merica-appliance di latar belakang (docker compose up -d).
Melakukan polling health check ke endpoint http://localhost:14000/api/v1/health hingga layanan siap digunakan dalam waktu \le 5 detik.

Opsi B: Instalasi Manual via Docker Compose

# 1. Buka direktori kerja
cd release/merica

# 2. Salin template environment variable
cp .env.example .env

# 3. Sesuaikan alamat host Airflow existing pada .env
nano .env

# 4. Nyalakan kontainer appliance
docker compose up -d

# 5. Verifikasi status kontainer
docker compose ps

Setelah kontainer aktif:

MERICA Canvas Web: Buka http://localhost:14000
Kredensial Default: Username: admin | Password: admin

⚙️ 3. Konfigurasi Parameter `.env`

Berkas .env memegang seluruh konfigurasi konektivitas eksternal. Berikut adalah parameter utama yang perlu Anda sesuaikan:

# --- Konfigurasi Appliance MERICA ---
MERICA_IMAGE=registry.sicabe.com/merica:1.0.0
MERICA_PORT=14000
ENVIRONMENT=production

# --- Alamat Cluster Apache Airflow External ---
# Arahkan ke URL web UI / API server kluster Airflow 3 existing Anda:
AIRFLOW_WEB_URL=http://host.docker.internal:14080

# --- Koneksi MetaDB Eksternal (Lakehouse PostgreSQL) ---
# Digunakan untuk fitur Introspection skema tabel dan Safe 10-Row Data Preview:
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=14432
POSTGRES_DB=lakehouse_metadb
POSTGRES_USER=airflow
POSTGRES_PASSWORD=airflow

# --- Penyimpanan Pipeline SSOT (Pilih Salah Satu Mode) ---
# Mode 1 (Default): Mount starter pipelines lokal untuk menjamin Canvas langsung terisi (Anti-Blank Canvas):
PIPELINES_DIR=./pipelines

# Mode 2 (GitOps Enterprise): Arahkan ke repositori Git yang disinkronkan via Airflow AIP-66 Git DAG Bundles:
# GIT_PIPELINE_REPO_URL=https://repo.sicabe.com/merica-dlh/merica-pipelines.git
# GIT_PIPELINE_REPO_BRANCH=main
# GIT_PIPELINE_REPO_SUBDIR=dags

# --- Integrasi OpenMetadata Governance (Opsional) ---
OMD_SERVER_URL=http://host.docker.internal:14585
OMD_AUTH_TOKEN=

🏛️ 4. Pilihan Mode Deployment

Tersedia dua berkas Docker Compose sesuai kebutuhan Anda:

1. Standalone Appliance (`docker-compose.yml`) — Rekomendasi Produksi

Hanya menjalankan 1 kontainer merica-appliance (Port 14000). Semua komponen lain (Airflow, Database, S3) menggunakan layanan eksternal organisasi Anda.

docker compose up -d

2. All-in-One Appliance (`docker-compose.all-in-one.yml`) — Mode Demo / Evaluasi

Menjalankan MERICA bersamaan dengan Apache Airflow 3, PostgreSQL, dan Redis di dalam satu mesin untuk keperluan uji coba lokal tanpa server eksternal:

docker compose -f docker-compose.all-in-one.yml up -d

🔨 5. Opsi Mem-Build Image Mandiri (Self-Contained Build)

Jika kebijakan keamanan organisasi Anda mewajibkan build lokal dari sumber (misalnya untuk jaringan tertutup air-gapped):

# Jalankan build multi-stage Docker
docker build -t registry.sicabe.com/merica:1.0.0 .

Proses multi-stage build akan:

Mengompilasi kode React Vite frontend menjadi aset statis optimal menggunakan Node.js 20 Alpine.
Memasang dependensi Python backend FastAPI dan pustaka validasi pada basis Python 3.11-slim.
Mengonfigurasi Nginx dan Supervisord sehingga frontend dan backend berjalan aman dalam satu image ramping berukuran \sim 230 MB.

🔄 6. Prosedur Pemeliharaan & Pembaruan (Maintenance & Upgrade)

Memeriksa Log Aplikasi:

# Log gabungan (Nginx access log & FastAPI log)
docker compose logs -f merica

Memperbarui ke Versi Rilis Baru:

Ubah tag image pada berkas .env:

MERICA_IMAGE=registry.sicabe.com/merica:1.1.0

Jalankan pembaruan tanpa downtime lama:
```
docker compose pull merica
docker compose up -d --no-deps merica
```
(Docker akan melakukan in-place recreate dalam waktu \sim 2-3 detik).

Menghentikan Layanan:

# Menghentikan kontainer
docker compose down

# Menghentikan kontainer dan menghapus volume
docker compose down -v

🧭 Navigasi Dokumen Terkait

Pahami Rancang Bangun: 🏛️ Arsitektur Platform
Menyiapkan Sisi Airflow Existing: 📘 Panduan Integrasi Airflow External
Panduan Mendesain Pipeline di Canvas: 🎨 Panduan Pengguna Canvas
Kembali ke Indeks: 🏠 Pusat Dokumentasi

6.2 KiB Raw Blame History