merica/docs/deployment_guide.md

# 📦 Panduan Deployment & Build Mandiri — MERICA

> **Navigasi Cepat**: [🏠 Pusat Dokumentasi](index.md) | [🏛️ Arsitektur Platform](architecture.md) | [📘 Integrasi Airflow External](panduan_integrasi_existing_airflow.md) | [🎨 Panduan Pengguna Canvas](user_guide.md)

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`:

```bash
# 1. Buka direktori rilis MERICA
cd release/merica

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

Skrip `setup.sh` secara otomatis akan:
1. Memeriksa ketersediaan Docker Engine dan Docker Compose v2.
2. Memeriksa ketersediaan berkas `.env` (jika belum ada, otomatis menyalin dari `.env.example`).
3. Memastikan direktori starter pipelines (`./pipelines/`) siap dengan permission yang sesuai.
4. Menjalankan kontainer `merica-appliance` di latar belakang (`docker compose up -d`).
5. 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

```bash
# 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`](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:

```bash
# --- 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 daftar pipeline langsung terisi:
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.
```bash
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:
```bash
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*):

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

Proses multi-stage build akan:
1. Mengompilasi kode React Vite frontend menjadi aset statis optimal menggunakan Node.js 20 Alpine.
2. Memasang dependensi Python backend FastAPI dan pustaka validasi pada basis Python 3.11-slim.
3. 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:
```bash
# Log gabungan (Nginx access log & FastAPI log)
docker compose logs -f merica
```

### Memperbarui ke Versi Rilis Baru:
1. Ubah tag image pada berkas `.env`:
   ```bash
   MERICA_IMAGE=registry.sicabe.com/merica:1.1.0
   ```
2. Jalankan pembaruan tanpa downtime lama:
   ```bash
   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:
```bash
# Menghentikan kontainer
docker compose down

# Menghentikan kontainer dan menghapus volume
docker compose down -v
```

---

## 🧭 Navigasi Dokumen Terkait

* Pahami Rancang Bangun: [🏛️ Arsitektur Platform](architecture.md)
* Menyiapkan Sisi Airflow Existing: [📘 Panduan Integrasi Airflow External](panduan_integrasi_existing_airflow.md)
* Panduan Mendesain Pipeline di Canvas: [🎨 Panduan Pengguna Canvas](user_guide.md)
* Kembali ke Indeks: [🏠 Pusat Dokumentasi](index.md)