merica/docs/panduan_integrasi_existing_airflow.md

# 📘 Panduan Integrasi MERICA Standalone dengan Existing Apache Airflow

> **Navigasi Cepat**: [🏠 Pusat Dokumentasi](index.md) | [🏛️ Arsitektur Platform](architecture.md) | [📦 Panduan Deployment](deployment_guide.md) | [🎨 Panduan Pengguna Canvas](user_guide.md)

Dokumen panduan ini dirancang khusus bagi **Data Engineer, Platform Engineer, dan DevOps** yang ingin menginstal **MERICA secara mandiri (*standalone appliance*)** dan menghubungkannya ke kluster **Apache Airflow yang sudah ada (*existing enterprise cluster*)**.

---

## 🏛️ 1. Gambaran Umum Arsitektur

MERICA (*Managed Engine for Robust Ingestion & Cloud Airflow*) berfungsi sebagai **Visual Low-Code DAG Builder** berbasis web. MERICA tidak mengeksekusi pipeline berat secara langsung; tugas eksekusi, pemantauan, dan retry task sepenuhnya didelegasikan ke kluster Apache Airflow eksternal Anda.

```mermaid
flowchart LR
    subgraph STANDALONE ["MERICA Standalone Host (Port 14000)"]
        UI["ReactFlow Canvas UI"]
        API["FastAPI Backend Gateway"]
        PIPES["Mounted Pipelines SSOT\n(./pipelines/)"]
        UI --- API
        API <--> PIPES
    end

    subgraph AIRFLOW_HOST ["Existing Apache Airflow Cluster"]
        AF_WEBSERVER["Airflow Web UI / API\n(Port 14080 / Domain)"]
        AF_SCHEDULER["Airflow Scheduler & Workers"]
        AF_DAG_PROC["DAG Processor\n(AIP-66 Git DAG Bundles)"]
        AF_SCHEDULER --- AF_DAG_PROC
    end

    STANDALONE -.->|"Deploy DAG (Git / YAML)"| AIRFLOW_HOST
    API -.->|"Direct Link Out"| AF_WEBSERVER
```

---

## 🚀 2. Dua Metode Penyiapan Sisi Existing Airflow

Untuk dapat menjalankan pipeline modern yang dirancang di MERICA (termasuk dbt Medallion, deduplikasi DuckDB, dan Shift-Left Quality Gates), worker dan DAG processor Airflow Anda membutuhkan beberapa pustaka tambahan (seperti `astronomer-cosmos` dan `dbt-postgres`).

Pilih salah satu dari **2 Metode** berikut sesuai kebijakan infrastruktur Anda:

---

### METODE 1: Modifikasi Langsung Tanpa Build Ulang (*Zero-Build / Runtime Injection*)

> [!TIP]
> **Gunakan metode ini jika**: Anda ingin uji coba cepat, tidak memiliki akses untuk mem-build image di private registry, atau dilarang me-rebuild Dockerfile Airflow existing.

#### Opsi 1A: Injeksi Runtime Otomatis via `_PIP_ADDITIONAL_REQUIREMENTS` (Rekomendasi Persisten)
Image resmi Apache Airflow memiliki hook entrypoint otomatis. Pustaka akan terpasang setiap kali kontainer dinyalakan tanpa perlu build Dockerfile:
1. Buka berkas `.env` atau `docker-compose.yml` di server Airflow existing Anda.
2. Tambahkan variabel lingkungan ini pada service Airflow (`airflow-scheduler`, `airflow-dag-processor`, dan `airflow-worker`):
   ```yaml
   environment:
     _PIP_ADDITIONAL_REQUIREMENTS: "astronomer-cosmos==1.15.1 dbt-postgres==1.11.0 apache-airflow-providers-git==1.0.0 duckdb==1.1.3 pyiceberg[s3fs,pyarrow]==0.8.0"
   ```
3. Restart service Airflow:
   ```bash
   docker compose restart airflow-scheduler airflow-dag-processor
   ```

#### Opsi 1B: `docker exec` Langsung ke Kontainer (Aktif dalam 15 Detik Tanpa Restart)
Jika kontainer Airflow sedang running dalam jam kerja dan Anda dilarang me-restart kontainer:
```bash
# 1. Install di Scheduler (user airflow)
docker exec -u airflow <container_scheduler> pip install --no-cache-dir \
    astronomer-cosmos==1.15.1 dbt-postgres==1.11.0 apache-airflow-providers-git==1.0.0

# 2. Install di DAG Processor
docker exec -u airflow <container_dag_processor> pip install --no-cache-dir \
    astronomer-cosmos==1.15.1 dbt-postgres==1.11.0 apache-airflow-providers-git==1.0.0
```

#### Verifikasi Keberhasilan Instalasi:
```bash
docker exec <container_scheduler> python -c "import cosmos; print('✅ Cosmos Version:', cosmos.__version__)"
```

#### Bagaimana Menghubungkan DAGs & Custom Operators Tanpa Build Ulang?
Seluruh operator custom (`helpers/duckdb_operator.py`, `helpers/dbt_trino_operator.py`, `helpers/ge_lakehouse_operator.py`, dll.) serta `dag_factory.py` **tidak perlu dibake ke image Airflow**.
Cukup sambungkan folder `dags/` ke Airflow Anda:
* **Via AIP-66 Git DAG Bundles (Airflow 3)**: Airflow otomatis meng-clone dari repositori `merica-pipelines.git`.
* **Via Shared Volume Mount**: Mount direktori `dags/` ke `/opt/airflow/dags` di kontainer Airflow.

---

### METODE 2: Build Ulang Image Resmi (*Official Baked Image*)

> [!IMPORTANT]
> **Gunakan metode ini jika**: Server produksi organisasi Anda berada di jaringan terisolasi (*air-gapped / tanpa akses internet luar*) atau standar DevOps mewajibkan seluruh dependensi paten di dalam image registry resmi.

#### 1. Buat Dockerfile Airflow Resmi
Buat berkas `Dockerfile.airflow` untuk registry organisasi Anda:

```dockerfile
FROM registry.sicabe.com/airflow:3.3.2-om203-ol

LABEL maintainer="BPKP Data Lakehouse Team <dlh@bpkp.go.id>"
LABEL description="Official Airflow 3 Engine Image with Baked MERICA Operators & Cosmos"
LABEL version="3.3.2-merica-v1.1"

USER airflow

# Instalasi dependensi engine MERICA langsung ke layer image
RUN pip install --no-cache-dir \
    astronomer-cosmos==1.15.1 \
    dbt-postgres==1.11.0 \
    apache-airflow-providers-git==1.0.0 \
    duckdb==1.1.3 \
    pyiceberg[s3fs,pyarrow]==0.8.0 \
    pyarrow==17.0.0 \
    s3fs==2024.9.0 \
    fsspec==2024.9.0 \
    dlt[duckdb,filesystem]==1.6.1

# Validasi kompilasi paket di dalam image
RUN python -c "import cosmos; import duckdb; import pyiceberg; print('✅ All MERICA Dependencies Baked!')"
```

#### 2. Build dan Push ke Private Registry
```bash
docker build -t registry.sicabe.com/airflow:3.3.2-merica-v1.1 -f Dockerfile.airflow .
docker push registry.sicabe.com/airflow:3.3.2-merica-v1.1
```

#### 3. Terapkan Image Baru di Kluster Airflow
Ubah tag image pada deployment Airflow:
```yaml
image: registry.sicabe.com/airflow:3.3.2-merica-v1.1
```
Lalu deploy ulang kontainer (`docker compose up -d` atau `kubectl rollout restart deployment airflow`).

---

## 🎨 3. Starter Seed Pipelines (Jaminan Daftar DAGs Langsung Tersedia)

### Kenapa Fitur Ini Ada?
MERICA adalah backend *stateless file-based*. Jika kontainer berdiri sendiri tanpa mount volume, sistem akan membaca folder kosong sehingga daftar pipeline di halaman web akan kosong (*blank*), yang sering kali menimbulkan kebingungan bagi pengguna baru.

### Cara Kerja Starter Seed Pipelines:
Di dalam paket rilis `release/merica/`, disediakan direktori `./pipelines/`:
* `pipelines/configs/`: Menyimpan spesifikasi YAML Airflow (`e2e_modernized_ingestion_flow.yaml`, `e2e_medallion_permits_flow.yaml`, `e2e_orders_master_medallion_flow.yaml`).
* `pipelines/metadata/`: Menyimpan data visual layout node & edge ReactFlow (`*.json`).
* `pipelines/dbt/`: Menyimpan model SQL dbt Medallion.

Saat kontainer `merica` dijalankan via `docker compose up -d`, direktori `./pipelines` ini otomatis di-mount ke `/app/merica-pipelines`. Begitu browser dibuka di `http://localhost:14000`, **3 pipeline data lakehouse modern langsung muncul secara visual** dan siap dieksplorasi atau diduplikasi!

### Cara Mengganti Starter Pipelines dengan Git Organisasi Anda (Opsi GitOps SSOT):
Jika tim Anda menggunakan pendekatan GitOps di mana MERICA dan Airflow 3 tersinkronisasi langsung ke repositori Git yang sama (`merica-pipelines.git`):
1. Clone repositori Git di samping folder `release/merica`:
   ```bash
   git clone https://repo.sicabe.com/merica-dlh/merica-pipelines.git ../merica-pipelines
   ```
2. Pada berkas `.env`, aktifkan variabel yang sudah disediakan di template (cukup buka tanda komentar):
   ```bash
   # Ganti dari ./pipelines ke path clone repositori Git Anda:
   PIPELINES_DIR=../merica-pipelines
   ```
3. Parameter referensi Git DAG Bundle di sisi Airflow 3 (`AIP-66`):
   ```bash
   GIT_PIPELINE_BUNDLE_NAME=merica-pipeline
   GIT_PIPELINE_REPO_URL=https://repo.sicabe.com/merica-dlh/merica-pipelines.git
   GIT_PIPELINE_REPO_BRANCH=main
   GIT_PIPELINE_REPO_SUBDIR=dags
   AIRFLOW_DAG_BUNDLE_REFRESH_INTERVAL=30
   ```
4. Restart MERICA: `docker compose up -d`. Seluruh pipeline tim Anda akan langsung tersinkronkan secara *hot-reload*!

---

## ⚡ 4. Panduan Operasional Cepat (Runbook 3 Menit)

### Langkah 1: Siapkan Konfigurasi Lingkungan
```bash
cd release/merica
cp .env.example .env
```
Sesuaikan parameter `AIRFLOW_WEB_URL` dan `POSTGRES_HOST` mengarah ke alamat server Airflow & Database Anda.

### Langkah 2: Jalankan Script Setup Sekali Klik
```bash
bash ./setup.sh
```

### Langkah 3: Buka Antarmuka MERICA
Akses antarmuka web di browser:
* **URL**: [`http://localhost:14000`](http://localhost:14000)
* **Username**: `admin`
* **Password**: `admin`

Daftar DAGs Anda akan langsung tampil secara visual dan siap digunakan!

---

## 🏢 5. Studi Kasus Implementasi Nyata (Real-World Deployment Walkthrough)

Bagian ini menyajikan contoh implementasi nyata ketika Anda menghubungkan MERICA ke server produksi yang telah menjalankan Apache Airflow dan stack data dengan port kustom (non-standar).

### Skenario Lapangan:
Sebuah server telah menjalankan kluster Airflow dan infrastruktur data dengan kondisi:
* **Kontainer Airflow**: `sicabe-airflow-scheduler`, `sicabe-airflow-webserver` (Port Host `12082:8080`), dan `sicabe-airflow-dag-processor` sudah berstatus `Up 7 days` (tidak boleh restart lama).
* **Penyimpanan Objek MinIO S3**: Port Host `8443`.
* **Katalog IAM Keycloak**: Port Host `12080`.
* **PostgreSQL MetaDB Shared**: Berjalan pada host dengan port standar atau custom.

```mermaid
flowchart LR
    subgraph MERICA_CONTAINER ["MERICA Standalone (Port 14000)"]
        UI["Web UI Canvas\n(Port 14000)"]
        BE["FastAPI Engine\n(127.0.0.1:8000)"]
        UI --- BE
    end

    subgraph EXISTING_STACK ["Existing Data Stack (Server SiCABE / Enterprise)"]
        AF_WEB["Airflow Webserver\n(Port Host :12082)"]
        AF_SCHED["Airflow Scheduler\n(Injected Libs)"]
        AF_PROC["DAG Processor\n(Injected Libs)"]
        S3["MinIO S3\n(Port Host :8443)"]
        PG["PostgreSQL MetaDB\n(Port :5432 / Custom)"]
    end

    BE -->|REST API :12082| AF_WEB
    BE -->|Introspection & Safe Preview| PG
    BE -->|Storage Connection| S3
    AF_SCHED -.->|Eksekusi Task Ingestion| S3
```

---

### Langkah Praktis Penerapan di Server:

#### 1. Inspeksi Kontainer & Port Aktif
Periksa nama kontainer Airflow dan pemetaan port host di server Anda:
```bash
docker ps --filter "name=airflow" --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"
```
*Catat nama kontainer scheduler dan dag processor serta port host webserver (misal: `0.0.0.0:12082->8080/tcp`).*

#### 2. Injeksi Pustaka Engine ke Kontainer Berjalan (Tanpa Restart)
Gunakan `docker exec` untuk memasang pustaka yang belum ada (`astronomer-cosmos` dan `dlt`) langsung ke worker/scheduler tanpa mematikan layanan. *(Catatan: Pustaka `apache-airflow-providers-git`, `dbt-postgres`, `duckdb`, `pyiceberg`, dan `sling` sudah tersedia bawaan (*built-in*) di image resmi)*:
```bash
# Injeksi ke Scheduler
docker exec -u airflow <nama_kontainer_scheduler> python -m pip install --no-cache-dir \
  astronomer-cosmos==1.15.1 dlt[duckdb,filesystem]==1.6.1

# Injeksi ke DAG Processor
docker exec -u airflow <nama_kontainer_dag_processor> python -m pip install --no-cache-dir \
  astronomer-cosmos==1.15.1 dlt[duckdb,filesystem]==1.6.1

# Injeksi ke Webserver (Konsistensi UI)
docker exec -u airflow <nama_kontainer_webserver> python -m pip install --no-cache-dir \
  astronomer-cosmos==1.15.1 dlt[duckdb,filesystem]==1.6.1

# Verifikasi instalasi berhasil
docker exec <nama_kontainer_scheduler> python -c "import cosmos, duckdb, pyiceberg; print('✅ Airflow Engine Ready!')"
```

#### 3. Penanganan Komunikasi Jaringan (Docker Networking)
Tentukan bagaimana kontainer MERICA berkomunikasi dengan layanan existing:
* **Kasus A — Satu Mesin (Single-Host)**:
  Gunakan `host.docker.internal` (didukung di Linux via `extra_hosts` pada compose) atau gunakan IP gateway Docker host (umumnya `172.17.0.1`).
* **Kasus B — Beda Server (Multi-Node)**:
  Ganti `host.docker.internal` dengan IP private / LAN server Airflow Anda (contoh: `http://192.168.10.50:12082`).
* **Kasus C — Shared Docker Network**:
  Jika ingin menggunakan nama kontainer langsung (contoh: `http://sicabe-airflow-webserver:8080`), hubungkan kontainer MERICA ke network yang sama dengan Airflow melalui `docker-compose.yml`:
  ```yaml
  networks:
    default:
      name: sicabe_default
      external: true
  ```

#### 4. Contoh Konfigurasi `.env` Riil yang Teruji
Di direktori `/opt/merica`, buat berkas `.env` dengan konfigurasi seperti berikut:

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

# --- External Airflow Cluster (Port Kustom 12082) ---
AIRFLOW_WEB_URL=http://host.docker.internal:12082
AIRFLOW_API_URL=http://host.docker.internal:12082
AIRFLOW_USERNAME=admin
AIRFLOW_PASSWORD=1310cc9a318f75cf

# --- PostgreSQL MetaDB (Introspection & Preview) ---
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=5432
POSTGRES_DB=airflow
POSTGRES_USER=airflow
POSTGRES_PASSWORD=a7bda1593a75d0ff0a8e51002c62c1f3

# --- External MinIO S3 (Port Kustom 8443) ---
S3_ENDPOINT_URL=http://host.docker.internal:8443
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=942a43b2a0e371545dfa0bff75381d49

# --- Pipeline Storage SSOT ---
PIPELINES_DIR=./pipelines
```

#### 5. Eksekusi & Validasi Konektivitas
1. Nyalakan kontainer MERICA:
   ```bash
   bash ./setup.sh
   # atau: docker compose up -d
   ```
2. Uji endpoint kesehatan:
   ```bash
   curl -s http://localhost:14000/api/v1/health | jq .
   ```
3. Akses antarmuka web MERICA di browser: `http://<ip-server>:14000`.
4. Anda dapat langsung menguji fitur **Database Introspection & Safe Preview** yang terhubung ke PostgreSQL, serta melihat tautan langsung ke Airflow Webserver di port `12082`.

---

## 🧭 Navigasi Dokumen Terkait

* Pahami Rancang Bangun: [🏛️ Arsitektur Platform](architecture.md)
* Cara Install Appliance: [📦 Panduan Deployment & Build](deployment_guide.md)
* Panduan Mendesain Pipeline di Canvas: [🎨 Panduan Pengguna Canvas](user_guide.md)
* Kembali ke Indeks: [🏠 Pusat Dokumentasi](index.md)