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

8.8 KiB

Raw Blame History

📘 Panduan Integrasi MERICA Standalone dengan Existing Apache Airflow

Navigasi Cepat: 🏠 Pusat Dokumentasi | 🏛️ Arsitektur Platform | 📦 Panduan Deployment | 🎨 Panduan Pengguna Canvas

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.

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:

Buka berkas .env atau docker-compose.yml di server Airflow existing Anda.

Tambahkan variabel lingkungan ini pada service Airflow (airflow-scheduler, airflow-dag-processor, dan airflow-worker):

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"

Restart service Airflow:

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:

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

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:

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

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:

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. Fitur "Anti-Blank Canvas" (Jaminan DAGs List Langsung Muncul)

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

Clone repositori Git di samping folder release/merica:

git clone https://repo.sicabe.com/merica-dlh/merica-pipelines.git ../merica-pipelines

Pada berkas .env, aktifkan variabel yang sudah disediakan di template (cukup buka tanda komentar):
```
# Ganti dari ./pipelines ke path clone repositori Git Anda:
PIPELINES_DIR=../merica-pipelines
```

Parameter referensi Git DAG Bundle di sisi Airflow 3 (AIP-66):

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

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

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 ./setup.sh

Langkah 3: Buka Antarmuka MERICA

Akses antarmuka web di browser:

URL: http://localhost:14000
Username: admin
Password: admin

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

🧭 Navigasi Dokumen Terkait

Pahami Rancang Bangun: 🏛️ Arsitektur Platform
Cara Install Appliance: 📦 Panduan Deployment & Build
Panduan Mendesain Pipeline di Canvas: 🎨 Panduan Pengguna Canvas
Kembali ke Indeks: 🏠 Pusat Dokumentasi

8.8 KiB Raw Blame History