KAL
Menu

Penyiapan lokal

Memasang Airflow secara lokal dengan pip, menjalankan layanannya, dan menelusuri UI untuk pertama kali.

Daftar isi

Topik ini membahas pemasangan Apache Airflow 3.x pada komputer lokal menggunakan pip, yaitu pengelola paket Python. Setelah Airflow terpasang, basis data metadata disiapkan, layanan utama dijalankan, dan tampilan antarmuka web diperkenalkan untuk pertama kalinya. Seluruh perintah dijalankan pada terminal dengan Python sebagai runtime. Setelah topik ini selesai, Airflow berjalan pada komputer lokal dan siap menerima berkas DAG pertama.

Folder kerja Airflow#

Airflow menyimpan seluruh berkas pentingnya di dalam satu folder yang ditentukan oleh variabel lingkungan (environment variable) AIRFLOW_HOME. Apabila variabel itu tidak diatur, folder default yang digunakan adalah ~/airflow. Di dalamnya terdapat airflow.cfg yang memuat konfigurasi efektif, yaitu nilai konfigurasi yang benar-benar digunakan Airflow. Berkas airflow.db menjadi basis data metadata SQLite pada pemasangan lokal, folder dags menampung berkas DAG, dan folder logs menyimpan log task. Mengatur AIRFLOW_HOME secara eksplisit menjaga folder kerja Airflow tetap terpisah dari berkas proyek lain.

Blok berikut menetapkan AIRFLOW_HOME ke folder /tmp/ra-penyiapan-lokal sekaligus memeriksa versi Python yang digunakan.

bash 
# tetapkan AIRFLOW_HOME ke folder khusus, lalu periksa versi Python
export AIRFLOW_HOME=/tmp/ra-penyiapan-lokal
python3 --version
text Keluaran 
Python 3.12.16

Airflow 3.3 diuji secara resmi pada Python 3.10 hingga 3.14, dan pemasangan lokal hanya membutuhkan SQLite tanpa layanan basis data tambahan. Kebutuhan memori Airflow masih wajar untuk komputer kerja biasa, meskipun dokumentasi merekomendasikan sekurang-kurangnya 4 GB. Komputer dengan memori sebesar itu cukup untuk mengikuti seluruh contoh pada jalur ini.

Memasang dengan pip#

Cara pemasangan yang direkomendasikan dokumentasi adalah pip dengan berkas constraint, yaitu daftar versi dependensi yang telah diuji bersama oleh tim Airflow untuk satu versi tertentu. Paket utamanya bernama apache-airflow, sedangkan integrasi tambahan disediakan oleh paket provider yang terpasang terpisah. Berkas constraint berada di branch khusus pada repository Apache Airflow dan dinamai menurut versi Airflow serta versi Python, misalnya constraints-3.3.2 dan constraints-3.12.txt untuk Python 3.12.

Perintah berikut memasang Apache Airflow 3.3.2 untuk Python 3.12. Prosesnya memakan waktu beberapa menit karena mengunduh Airflow beserta seluruh dependensinya yang terkunci oleh constraint.

bash 
# tidak-dijalankan
# pasang Apache Airflow 3.3.2 dengan berkas constraint untuk Python 3.12
pip install "apache-airflow==3.3.2" \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.3.2/constraints-3.12.txt"

Menyiapkan basis data metadata#

Setelah paket terpasang, basis data metadata perlu disiapkan sebelum layanan apa pun dijalankan. Perintah airflow db migrate membuat basis data apabila belum ada, lalu menerapkan seluruh migrasi skema, yaitu pembaruan struktur basis data, hingga versi saat ini.

bash 
# buat dan migrasi basis data metadata
# log migrasinya bertanda waktu, sehingga dialihkan agar tidak ditampilkan
airflow db migrate > /dev/null 2>&1

Pada pemasangan baru, perintah ini berjalan sekitar sepuluh detik dan berakhir tanpa kegagalan. Prosesnya menerapkan migrasi skema berurutan dari alembic, yaitu alat migrasi yang digunakan Airflow. Setelah perintah selesai, berkas airflow.db dan airflow.cfg muncul di dalam AIRFLOW_HOME, tanda bahwa basis data metadata sudah siap digunakan oleh scheduler, dag processor, dan API server. Perintah yang sama dijalankan ulang setelah peningkatan versi Airflow karena skema basis data mengikuti versi terbaru.

Memeriksa hasil pemasangan#

Dua perintah cepat memastikan instalasi berjalan dengan baik. Perintah pertama, airflow version, menampilkan versi Airflow yang terpasang.

bash 
# tampilkan versi Airflow yang terpasang
airflow version
text Keluaran 
3.3.2

Perintah kedua membaca satu nilai konfigurasi dari airflow.cfg, yaitu lokasi folder DAG.

bash 
# baca lokasi folder DAG yang efektif dari konfigurasi
airflow config get-value core dags_folder
text Keluaran 
/tmp/ra-penyiapan-lokal/dags

Nilai dags_folder menunjukkan folder tempat Airflow mencari berkas DAG, yaitu folder dags di dalam AIRFLOW_HOME yang ditetapkan sebelumnya. Seluruh DAG yang diletakkan di folder itu akan diparse oleh dag processor dan muncul di UI. Nilai konfigurasi lain dibaca dengan pola yang sama, yaitu airflow config get-value <bagian> <kunci>.

Menjalankan layanan#

Airflow 3.x terdiri atas beberapa layanan jangka panjang yang dijalankan sebagai proses terpisah. API server menyajikan UI dan REST API, scheduler menjadwalkan task, dag processor mem-parse berkas DAG, dan triggerer menangani task deferrable. Tiap layanan dijalankan pada terminal tersendiri karena perintahnya berjalan terus di latar depan.

bash 
# tidak-dijalankan
# layankan UI dan REST API pada port 8080, di terminal pertama
airflow api-server --port 8080
bash 
# tidak-dijalankan
# jalankan tiap layanan berikut pada terminal tersendiri
airflow scheduler
airflow dag-processor
airflow triggerer

Setelah API server berjalan, antarmuka web dapat dibuka pada alamat http://localhost:8080. Untuk percobaan cepat tanpa mengelola empat terminal, perintah airflow standalone menginisialisasi basis data, membuat akun admin, dan menjalankan seluruh komponen sekaligus. Kata sandi akun admin dibuat acak dan disimpan pada berkas simple_auth_manager_passwords.json.generated di dalam AIRFLOW_HOME. Mode standalone ditujukan untuk pengembangan lokal dan bukan untuk produksi.

bash 
# tidak-dijalankan
# alternatif cepat untuk percobaan lokal, menjalankan semua komponen sekaligus
airflow standalone

Alternatif lain adalah Docker Compose. Dokumentasi resmi menyediakan berkas docker-compose.yaml yang menjalankan seluruh komponen dalam kontainer terpisah beserta PostgreSQL, sehingga tidak ada layanan yang dipasang langsung di host. Pendekatan ini lebih berat pada tahap awal tetapi lebih dekat dengan bentuk pemasangan produksi.

Tur pertama antarmuka web#

Dengan API server berjalan pada http://localhost:8080, halaman awal menampilkan indikator kesehatan komponen seperti basis data, scheduler, triggerer, dan dag processor beserta ringkasan aktivitas terbaru. Navigasi utama UI terdiri atas tiga bagian, yaitu Dags, Assets, dan Admin. Seluruh tampilan yang dibahas pada bagian ini muncul setelah salah satu mode pemasangan pada bagian sebelumnya dijalankan.

Halaman Dags berisi daftar seluruh DAG yang dikenal Airflow beserta jadwalnya, status dag run terakhir, dan graf kecil dag run terkini. Tombol pause pada setiap baris menghentikan atau mengaktifkan penjadwalan sebuah DAG tanpa menghapus definisinya. Membuka salah satu DAG memunculkan tampilan Grid, yaitu matriks dengan baris task dan kolom dag run, serta tab Graph yang menggambar graf dependensinya. Mengeklik sel task membuka riwayat percobaan dan log task tersebut, tempat pertama yang diperiksa ketika sebuah task gagal.

Halaman Assets berfungsi sebagai katalog aset data yang diproduksi atau dikonsumsi task, lengkap dengan graf produsen dan konsumennya. Bagian Admin menghimpun pengaturan tingkat sistem seperti Variables untuk konfigurasi kunci-nilai, Connections untuk kredensial layanan luar, Pools untuk pembatasan kapasitas, Providers untuk daftar paket provider yang terpasang, serta Config untuk membaca konfigurasi efektif. Semua pengaturan pada bagian ini berlaku lintas DAG sehingga cocok untuk konfigurasi lingkungan secara keseluruhan.

Kesalahan umum#

Kesalahan berikut paling sering muncul pada pemasangan lokal pertama.

  • Memasang tanpa constraint. Resolusi dependensi pip dapat berjalan sangat lama dan berakhir dengan konflik versi. Perbaikannya adalah mengulang instalasi dengan opsi --constraint sebagaimana contoh pada bagian Memasang dengan pip.
  • Menjalankan airflow db init dari tutorial lama Airflow 2.x. Perintah ini sudah dihapus pada Airflow 3.x sehingga terminal menampilkan error pilihan tidak valid. Gunakan airflow db migrate.
  • DAG tidak muncul di UI. Penyebab yang umum adalah berkas yang tidak berada di folder yang ditunjukkan oleh dags_folder atau berkas yang gagal diparse karena kesalahan sintaks. Periksa lokasi folder dengan airflow config get-value core dags_folder, lalu baca log dag processor.

Ringkasan#

  • AIRFLOW_HOME menampung konfigurasi, basis data metadata, folder dags, dan log, serta diatur sebelum perintah Airflow lainnya dijalankan.
  • Instalasi resmi menggunakan pip dengan berkas constraint agar versi dependensi terkunci pada kombinasi yang telah diuji.
  • Perintah airflow db migrate menyiapkan basis data metadata, sedangkan layanan utama dijalankan melalui airflow api-server, airflow scheduler, airflow dag-processor, dan airflow triggerer.
  • UI pada http://localhost:8080 menyediakan halaman Dags, tampilan Grid dan Graph, log task, Assets, dan Admin.

Referensi#