Fly.toml adalah file konfigurasi utama berbasis format TOML yang digunakan oleh platform cloud Fly.io untuk mendefinisikan bagaimana sebuah aplikasi di-deploy, dijalankan, diskalakan, dan dikelola di dalam infrastruktur mereka. File ini bertindak sebagai cetak biru (blueprint) bagi mesin CLI flyctl saat melakukan proses build Docker image, pengaturan port jaringan, penentuan alokasi memori, hingga manajemen volume penyimpanan persisten.
Tanpa file ini, Fly.io tidak akan mengenali bagaimana cara menjalankan kode sumber Anda, terutama untuk aplikasi kustom yang tidak menggunakan deteksi buildpack otomatis secara standar. Pemahaman mendalam mengenai struktur fly.toml sangat krusial bagi para pengembang perangkat lunak agar aplikasi dapat berjalan stabil, efisien, dan minim kendala saat masuk ke lingkungan produksi.
Struktur Dasar dan Atribut Utama Fly.toml
Sebuah file fly.toml standar terdiri dari beberapa blok konfigurasi utama yang masing-masing mengatur aspek spesifik dari aplikasi Anda. Blok pertama dan yang paling wajib ada adalah deklarasi nama aplikasi dan organisasi pemiliknya. Nama aplikasi dalam file ini harus sama persis dengan yang telah didaftarkan melalui perintah fly apps create di terminal.
Selain identitas aplikasi, blok konfigurasi juga mengatur mesin dasar atau VM (Virtual Machine) yang akan digunakan untuk menjalankan aplikasi. Pengembang dapat menentukan wilayah server (region) default tempat aplikasi pertama kali diluncurkan, serta batasan memori dan jenis CPU yang disesuaikan dengan kebutuhan performa aplikasi web, API server, maupun worker background.
| Blok Konfigurasi | Fungsi Utama | Contoh Penggunaan |
|---|---|---|
[app] | Menentukan nama unik aplikasi dan organisasi. | app = "my-awesome-app" |
[build] | Pengaturan proses pembuatan image (Dockerfile atau Buildpacks). | dockerfile = "Dockerfile" |
[http_service] | Konfigurasi routing HTTP, port internal, dan auto-stop/start. | internal_port = 8080 |
[env] | Penyimpanan variabel lingkungan non-rahasia. | PORT = "8080" |
Konfigurasi Proses Build dan Deployment
Blok [build] di dalam fly.toml memberikan fleksibilitas penuh bagi pengembang untuk menentukan metode kompilasi aplikasi. Anda bisa mengarahkan sistem Fly.io untuk membaca Dockerfile kustom yang terletak di direktori root, atau membiarkan sistem mendeteksi secara otomatis bahasa pemrograman yang digunakan seperti Node.js, Python, Go, Ruby, atau PHP menggunakan Cloud Native Buildpacks.
Di dalam bagian ini, argumen build (build args) juga dapat disematkan untuk meneruskan variabel selama proses kompilasi image berlangsung. Pengaturan ini sangat membantu ketika aplikasi membutuhkan dependensi privat atau konfigurasi khusus pada saat image Docker sedang dirakit sebelum di-push ke registry internal Fly.io.
Pengaturan Layanan HTTP dan Jaringan
Pengaturan lalu lintas jaringan masuk (inbound traffic) dikelola melalui blok [http_service] atau [services]. Pada bagian ini, pengembang mendefinisikan port internal tempat aplikasi Anda mendengarkan koneksi (misalnya port 3000 atau 8080) dan memetakannya ke port eksternal standar 80 serta 443 yang disediakan oleh load balancer global Fly.io.
Selain port, blok jaringan ini juga mengatur fitur modern seperti auto-stop dan auto-start mesin untuk menghemat biaya operasional, serta konfigurasi pemeriksaan kesehatan (health checks). Pemeriksaan kesehatan memastikan bahwa router Fly.io hanya mengirimkan trafik pengguna ke instance VM yang benar-benar siap menerima permintaan setelah proses booting selesai.
Manajemen Variabel Lingkungan dan Secrets
Variabel lingkungan (environment variables) di dalam fly.toml dibagi menjadi dua kategori utama, yakni variabel publik yang didefinisikan langsung pada blok [env] dan variabel rahasia (secrets) seperti API keys atau kredensial database yang harus dikelola melalui perintah terpisah di CLI.
Menyimpan data sensitif secara langsung di dalam file fly.toml sangat tidak disarankan karena file ini biasanya ikut di-commit ke dalam sistem kontrol versi seperti Git. Pengembang wajib menggunakan perintah fly secrets set agar data sensitif tersebut dienkripsi secara aman dan hanya dapat diakses oleh instance aplikasi yang sedang berjalan di server.
Tips Praktis dan Troubleshooting Fly.toml
Saat menyusun fly.toml untuk pertama kalinya, kesalahan sintaks TOML sering kali menjadi penyebab utama gagalnya proses deployment. Pastikan selalu menggunakan tanda kutip yang benar untuk tipe data string dan perhatikan indentasi blok agar hierarki pengaturan tidak keliru terbaca oleh parser sistem.
Sebelum melakukan deployment ke server produksi, jalankan selalu perintah fly config validate di terminal lokal Anda. Perintah ini berfungsi mendeteksi dini adanya kesalahan penulisan parameter atau nilai konfigurasi yang tidak didukung oleh versi CLI terbaru, sehingga meminimalkan risiko kegagalan saat proses fly deploy sedang berjalan.