180 lines
6.2 KiB
Markdown
180 lines
6.2 KiB
Markdown
# 📦 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)
|