Ada momen yang bikin developer langsung deg-degan: buka laptop, ada error production, terus otak mendadak kosong.
Artikel ini ngebahas kenapa runbook kecil bisa jadi penyelamat buat developer solo, freelancer, atau tim kecil yang belum punya sistem operasi serapi perusahaan besar. Runbook di sini bukan dokumen tebal yang cuma dibaca pas onboarding. Maksudnya adalah catatan langkah kerja yang jelas: cek apa dulu, command apa yang aman, siapa/apa yang harus dilihat, dan kapan harus rollback.
Kalau lu sering ngurus website, aplikasi client, server pribadi, Ghost CMS, Cloudflare Tunnel, deployment frontend, atau automation kecil, runbook bikin proses debugging lebih tenang. Bukan karena semua masalah langsung selesai, tapi karena lu nggak mulai dari panik.
Apa itu runbook?
Runbook adalah panduan langkah demi langkah untuk menjalankan atau memulihkan suatu sistem. Isinya biasanya prosedur operasional: cara cek status service, cara restart aman, cara rollback, cara membaca log, sampai kapan sebuah masalah harus dianggap incident.
Di dunia Site Reliability Engineering, incident response bukan cuma soal orang jago ngoprek. Google SRE menekankan pentingnya struktur saat incident: ada pembagian peran, komunikasi jelas, dan fokus mengembalikan layanan secepat mungkin tanpa bikin kerusakan baru. Buat developer individu, versi kecilnya bisa jauh lebih sederhana: satu file Markdown berisi checklist yang bisa lu ikuti saat kepala lagi panas.
Ini yang sering kelupaan: kemampuan teknis lu pas tenang dan kemampuan teknis lu pas panik itu beda. Runbook menjembatani dua kondisi itu.
Kenapa developer kecil juga butuh runbook?
Banyak developer mikir runbook cuma buat tim SRE, perusahaan enterprise, atau layanan yang traffic-nya jutaan user. Padahal masalah operasional nggak nunggu skala besar.
Website portfolio down tetap bikin reputasi turun. Landing page client error tetap bikin chat masuk tengah malam. Blog pribadi yang dipakai buat personal branding tetap terasa rugi kalau gagal dibuka pas lagi ada orang ngecek profil lu.
Atlassian menjelaskan incident management sebagai proses untuk merespons, memperbaiki, dan belajar dari gangguan layanan. Microsoft juga membahas incident response sebagai rangkaian persiapan, deteksi, analisis, containment, eradication, dan recovery. Walau konteksnya sering security atau organisasi besar, pola dasarnya tetap relevan buat builder kecil: siapkan langkah sebelum masalah kejadian.
Menurut gua, inilah bedanya developer yang cuma bisa bikin fitur dan developer yang mulai matang sebagai operator. Operator bukan berarti nggak pernah error. Operator tahu cara bergerak saat error.
Runbook bukan dokumentasi sempurna
Masalah terbesar dokumentasi biasanya bukan kurang niat, tapi standar yang terlalu tinggi. Banyak orang keburu bayangin wiki rapi, diagram lengkap, semua endpoint dijelaskan, semua SOP formal. Akhirnya nggak mulai.
Runbook yang berguna justru boleh jelek dulu. Yang penting bisa dipakai saat keadaan lagi kacau.
Format paling sederhana:
- Nama masalah: Ghost CMS nggak bisa dibuka dari domain utama.
- Gejala: Cloudflare Tunnel return 502 atau origin refused.
- Cek pertama: status container Ghost dan cloudflared.
- Command aman: command read-only buat lihat log dan port.
- Langkah recovery: restart service tertentu, bukan reboot semua mesin.
- Rollback: langkah balik kalau perubahan terakhir bikin rusak.
- Catatan setelah selesai: penyebab, durasi, dan pencegahan.
Kalau satu halaman ini menyelamatkan lu dari restart random, dokumen itu sudah punya nilai.
Contoh runbook kecil untuk developer
Misalnya lu punya personal website di Ghost CMS, ditaruh di Docker, lalu dibuka publik lewat Cloudflare Tunnel. Saat website down, jangan langsung utak-atik DNS. Banyak kasus masalahnya ada di origin: container mati, port salah, database belum siap, atau tunnel nggak bisa reach service lokal.
Runbook kecilnya bisa seperti ini:
Masalah: rafli.dev tidak bisa diakses
1. Cek public response
- Buka domain dari browser
- Catat status: 502, 503, timeout, atau redirect loop
2. Cek origin di server
- docker ps
- docker logs --tail=120 ghost
- docker logs --tail=120 cloudflared
3. Cek port lokal
- curl -H "Host: rafli.dev" -H "X-Forwarded-Proto: https" http://127.0.0.1:2368/
4. Kalau Ghost mati
- cek log database dulu
- restart container Ghost hanya kalau penyebabnya jelas
5. Setelah pulih
- tulis penyebab
- tulis command yang benar-benar membantu
- tambahkan pencegahan kecilIni bukan format sakral. Intinya: runbook memaksa lu membedakan antara cek fakta dan nebak solusi.
Bagian penting yang wajib ada
Kalau lu mau mulai hari ini, nggak perlu bikin 20 runbook. Mulai dari tiga kejadian yang paling mahal kalau rusak: website down, deploy gagal, dan data/storage bermasalah.
Setiap runbook minimal punya bagian ini:
- Gejala yang terlihat
Contoh: halaman 502, login gagal, upload file stuck, webhook nggak masuk. - Impact
Siapa yang kena: lu sendiri, client, user, pembaca, atau proses internal. - Cek read-only
Command yang aman karena cuma membaca status/log, bukan mengubah sistem. - Langkah recovery
Urutan tindakan dari risiko paling rendah ke paling tinggi. - Batas eskalasi
Kapan harus rollback, restore backup, atau berhenti eksperimen. - Catatan post-incident
Apa penyebabnya, apa yang diperbaiki, dan apa pencegahan berikutnya.
Bagian “cek read-only” menurut gua paling penting. Saat panik, tangan biasanya gatal buat langsung restart, reinstall, atau hapus cache. Padahal sering kali log sudah ngasih petunjuk. Runbook bikin lu baca dulu, baru bertindak.
Runbook juga bagus buat kerja bareng AI agent
Ini bagian yang makin relevan sekarang. Kalau lu pakai AI coding assistant atau AI agent, runbook bisa jadi konteks yang jauh lebih berguna daripada prompt panjang dadakan.
AI agent bisa bantu baca log, menyusun hipotesis, atau membuat patch. Tapi kalau repo dan sistem lu nggak punya batas aman, agent bisa gampang kebablasan: restart service yang salah, edit file yang nggak perlu, atau fokus ke gejala yang kelihatan paling keras.
Dengan runbook, lu bisa kasih instruksi lebih presisi:
- “Ikuti runbook ini dulu, jangan ubah file sebelum ada root cause.”
- “Jalankan hanya command read-only di tahap awal.”
- “Kalau sudah tiga hipotesis gagal, berhenti dan laporkan bukti.”
- “Kalau perlu rollback, pakai langkah yang tertulis di bagian recovery.”
GitHub Actions docs juga menunjukkan pola yang mirip di sisi automation: workflow ditulis sebagai file yang eksplisit, bisa dibaca, bisa diulang, dan bisa diperiksa. Runbook adalah versi manusia dari itu. Bedanya, runbook membantu lu mengambil keputusan saat automation belum cukup.
Cara mulai dalam 30 menit
Kalau lu belum punya runbook sama sekali, pakai langkah ini:
- Pilih satu sistem yang paling sering bikin waswas.
Misalnya website pribadi, app client, API kecil, atau pipeline deploy. - Tulis tiga gejala paling umum.
Contoh: domain down, deploy gagal, upload error. - Kumpulkan command cek status yang aman.
Prioritaskan log, health check, status container, status workflow, dan konfigurasi yang bisa dibaca. - Tulis urutan tindakan dari risiko rendah.
Cek dulu, restart service spesifik, rollback, baru tindakan besar. - Setelah masalah berikutnya terjadi, update runbook.
Jangan tunggu dokumen sempurna. Runbook tumbuh dari kejadian nyata.
Simpan di tempat yang gampang dibuka. Bisa di Obsidian, repo private, folder server, atau docs project. Yang penting saat butuh, lu nggak nyari dari nol.
Takeaway buat developer yang lagi bangun personal brand
Personal branding developer nggak cuma dibangun dari showcase fitur keren. Trust juga kebentuk dari cara lu menunjukkan proses: gimana lu debug, gimana lu menjaga sistem, gimana lu belajar dari incident kecil.
Runbook adalah bukti kecil bahwa lu bukan cuma “bisa bikin”, tapi juga mulai mikir soal menjaga. Buat audience teknis, ini jauh lebih kuat daripada klaim “gua detail-oriented”. Tunjukkan checklist, tunjukkan before-after, tunjukkan cara kerja.
Kalau artikel ini mau dipecah jadi carousel, angle-nya simpel: “Developer yang siap error lebih keliatan senior daripada developer yang cuma siap demo.”
FAQ singkat
Apakah runbook harus formal?
Nggak. Untuk solo developer atau tim kecil, runbook boleh berupa file Markdown sederhana. Yang penting langkahnya jelas dan bisa dipakai saat kondisi tegang.
Runbook beda apa dengan postmortem?
Runbook dipakai sebelum dan saat masalah terjadi. Postmortem ditulis setelah masalah selesai untuk belajar dari kejadian itu. Dua-duanya saling melengkapi.
Apakah semua masalah perlu runbook?
Nggak. Mulai dari masalah yang impact-nya tinggi atau sering kejadian. Kalau semuanya didokumentasikan sekaligus, biasanya malah berhenti di tengah jalan.
Apakah AI agent bisa menggantikan runbook?
Belum tentu. AI agent bisa bantu eksekusi dan analisis, tapi runbook memberi batas aman, konteks sistem, dan urutan kerja yang sesuai kondisi lu.
