Healthcheck Docker, Cara Membuat Container Restart Otomatis saat Unhealthy

Docker Engine 29.9.3 baru saja dirilis pada 3 November 2026 sebagai rilis keamanan yang memperbaiki empat celah keamanan, menurut catatan rilis resmi Docker. Di tengah pembaruan itu, satu kesalahpahaman lama masih banyak dipegang pemilik VPS: banyak yang mengira container yang diberi healthcheck akan restart sendiri begitu statusnya berubah menjadi unhealthy. Faktanya tidak begitu. Artikel panduan dari Cloudhim yang diperbarui 4 November 2026 menegaskan bahwa healthcheck Docker dan restart policy adalah dua sistem terpisah yang tidak saling berbicara. Container bisa berstatus unhealthy berjam-jam sementara proses utamanya tetap berjalan, dan Docker tidak akan menyentuhnya. Artikel ini menunjukkan cara menutup celah itu, dari menulis healthcheck yang benar sampai memasang Autoheal agar container yang tidak sehat benar-benar restart sendiri.

Kenapa Container Docker Bisa “Hidup” tapi Sebenarnya Mati

Container yang berjalan belum tentu melayani dengan benar. Aplikasi web bisa kehabisan koneksi database, worker antrean bisa macet, atau layanan bisa menjawab semua permintaan dengan galat 500, sementara proses utamanya tetap hidup. Dari sisi Docker, container itu masih running, jadi tidak ada alasan untuk me-restart-nya.

Pengujian yang didokumentasikan Matthew Wong pada Docker Engine 29.8.1 memperlihatkan hal ini dengan jelas. Sebuah container nginx dengan restart policy unless-stopped dan healthcheck yang gagal dibiarkan berjalan lebih dari satu menit. Hasilnya, statusnya berubah menjadi unhealthy setelah 13 kali pemeriksaan gagal berturut-turut, tetapi RestartCount tetap 0 dan container terus menjawab permintaan dengan kode 403. Inilah inti masalahnya: Docker tahu container kamu sakit, tetapi tidak melakukan apa-apa.

Bagi pemilik VPS yang menjalankan layanan sendirian, kondisi ini berbahaya karena tidak ada operator yang berjaga. Website bisa mati semalaman tanpa ada yang menyadarinya. Karena itu healthcheck Docker harus dipasangkan dengan mekanisme yang benar-benar bertindak saat status berubah menjadi unhealthy.

Cara Kerja Healthcheck Docker

Healthcheck Docker adalah perintah yang dijalankan Docker di dalam container secara berkala untuk menanyakan apakah aplikasi masih bekerja. Menurut referensi Dockerfile resmi Docker, perintah ini menghasilkan tiga status: starting saat container baru berjalan, healthy bila pemeriksaan lolos, dan unhealthy bila pemeriksaan gagal berulang kali.

Kode keluar perintah menentukan hasilnya. Kode 0 berarti sehat, kode 1 berarti tidak sehat, dan kode 2 dicadangkan sehingga jangan pernah kamu pakai. Empat pengaturan waktu mengendalikan perilakunya: interval mengatur jeda antar pemeriksaan, timeout mengatur batas tunggu tiap pemeriksaan, retries mengatur berapa kali gagal berturut-turut sebelum status berubah menjadi unhealthy, dan start_period memberi masa tenggang saat container baru start agar pemeriksaan yang gagal di awal tidak langsung dihitung.

Yang perlu kamu pahami, status kesehatan ini murni bersifat informasional bagi Docker daemon. Ia dipakai oleh depends_on dengan condition: service_healthy untuk menunda start layanan dependen, dan oleh docker compose up --wait untuk menunggu layanan siap. Namun setelah semua layanan berjalan, Compose tidak lagi mengawasi status kesehatan. Layanan dependen pun tetap berjalan meski dependensinya berubah menjadi unhealthy di tengah jalan.

Langkah 1: Menulis Healthcheck di Docker Compose

Langkah pertama adalah menambahkan blok healthcheck pada layanan yang ingin kamu awasi. Contoh berikut memakai nginx, dengan pemeriksaan sederhana memakai curl ke halaman utama.

services:
  web:
    image: nginx:latest
    restart: unless-stopped
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Perintah curl -f http://localhost/ mengembalikan kode keluar bukan nol bila server menjawab dengan galat HTTP, sehingga pemeriksaan gagal dengan benar. Interval 30 detik adalah titik awal yang aman untuk kebanyakan layanan web. Timeout 10 detik mencegah pemeriksaan yang menggantung menahan antrean, sedangkan retries 3 berarti container baru dinyatakan unhealthy setelah tiga kali gagal berturut-turut, atau sekitar 90 detik sejak masalah pertama muncul.

Start period 40 detik penting untuk aplikasi yang butuh waktu lama saat booting, misalnya aplikasi Java atau layanan yang memuat cache besar. Tanpa masa tenggang ini, container bisa dinyatakan unhealthy padahal ia hanya belum selesai start. Untuk layanan database, gunakan perintah bawaan alatnya, misalnya pg_isready -U postgres untuk PostgreSQL atau mysqladmin ping untuk MySQL dan MariaDB. Untuk aplikasi tanpa curl di dalam image, gunakan wget --spider atau periksa endpoint kesehatan bawaan aplikasi, misalnya /health atau /healthz.

Setelah menyimpan file, jalankan docker compose up -d lalu periksa statusnya dengan docker ps. Kolom status akan menampilkan (health: starting), lalu berubah menjadi (healthy) bila pemeriksaan lolos. Perintah docker inspect --format='{{json .State.Health}}' nama-container menampilkan riwayat lengkap pemeriksaan, termasuk log keluaran terakhir yang berguna saat debugging.

Langkah 2: Memahami Restart Policy dan Batasannya

Docker menyediakan empat restart policy: no, on-failure, always, dan unless-stopped. Menurut dokumentasi resmi Docker tentang menjalankan container secara otomatis, semua kebijakan ini hanya bereaksi terhadap proses utama container yang keluar. Tidak satu pun yang bereaksi terhadap status kesehatan.

Perbedaannya penting untuk dipilih dengan sadar. Policy on-failure hanya me-restart container bila proses keluar dengan kode bukan nol, sehingga cocok untuk layanan yang memang boleh berhenti total saat gagal. Policy unless-stopped me-restart container dalam hampir semua kondisi kecuali kamu menghentikannya sendiri, dan ini pilihan paling umum untuk layanan di VPS. Policy always mirip, tetapi container juga ikut start lagi setelah kamu menghentikannya secara manual lalu me-restart daemon Docker.

Namun sekali lagi, restart policy tidak menyelamatkan container yang prosesnya masih hidup tetapi aplikasinya sudah tidak merespons. Itulah alasan pengujian pada Docker Engine 29.8.1 tadi berakhir dengan RestartCount 0. Restart policy adalah jaring pengaman untuk proses yang mati, bukan untuk layanan yang macet. Untuk kasus kedua, kamu butuh pengawas eksternal, dan itulah langkah berikutnya.

Langkah 3: Memasang Autoheal agar Container Restart Otomatis saat Unhealthy

Untuk VPS tunggal, cara paling sederhana dan paling banyak dipakai adalah memasang container pendamping willfarrell/autoheal. Container kecil ini mengawasi event kesehatan Docker dan me-restart container yang berstatus unhealthy melalui Docker socket. Proyek ini tersedia di GitHub pada repositori willfarrell/docker-autoheal dan sudah lama dipakai komunitas self-hosting sebagai pelengkap standar Docker.

Tambahkan layanan autoheal ke file Compose yang sama, lalu beri label pada layanan yang ingin diawasi.

services:
  web:
    image: nginx:latest
    restart: unless-stopped
    labels:
      - "autoheal=true"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  autoheal:
    image: willfarrell/autoheal:latest
    container_name: autoheal
    restart: unless-stopped
    environment:
      - AUTOHEAL_CONTAINER_LABEL=autoheal
      - AUTOHEAL_INTERVAL=5
      - AUTOHEAL_START_PERIOD=30
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Variabel AUTOHEAL_CONTAINER_LABEL=autoheal berarti Autoheal hanya mengawasi container berlabel autoheal=true. Bila kamu ingin semua container ber-healthcheck diawasi tanpa memberi label satu per satu, ganti nilainya menjadi all. Variabel AUTOHEAL_INTERVAL=5 mengatur Autoheal memeriksa status setiap 5 detik, dan AUTOHEAL_START_PERIOD=30 memberi jeda 30 detik setelah sistem start sebelum pengawasan dimulai, supaya container yang baru naik tidak langsung di-restart.

Perlu dicatat bahwa memasang Autoheal berarti memberi satu container akses ke Docker socket di /var/run/docker.sock. Siapa pun yang menguasai container itu secara praktis menguasai daemon Docker di host. Karena itu jangan memasang Autoheal di server bersama yang tidak kamu kendalikan penuh, dan pastikan image yang dipakai berasal dari repositori resmi willfarrell/autoheal. Pembahasan risikonya ada di bagian keamanan di bawah.

Langkah 4: Mengatur depends_on agar Layanan Start dengan Urutan Benar

Healthcheck Docker juga berguna saat layanan saling bergantung. Tanpa pengaturan urutan, aplikasi web bisa start sebelum database siap menerima koneksi, lalu crash dan mengandalkan restart policy untuk mencoba lagi. Pola yang lebih rapi adalah menunda start aplikasi sampai database benar-benar sehat.

services:
  db:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=rahasia
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  app:
    image: aplikasi-kamu:latest
    depends_on:
      db:
        condition: service_healthy

Dengan condition: service_healthy, Compose menunggu pemeriksaan kesehatan database lolos sebelum menjalankan container aplikasi. Perlu diingat, mekanisme ini hanya bekerja saat start awal. Setelah semua layanan berjalan, Compose tidak mengawasi lagi, dan aplikasi akan tetap berjalan bila database berubah menjadi unhealthy. Jadi depends_on menyelesaikan masalah urutan start, bukan masalah pemulihan saat layanan macet di tengah jalan. Untuk pemulihan, tetap dibutuhkan Autoheal dari langkah sebelumnya.

Perintah docker compose up --wait juga memanfaatkan status sehat ini. Perintah tersebut menunggu semua layanan mencapai status running atau healthy, lalu keluar dengan galat bila ada layanan yang berubah menjadi unhealthy sebelum batas waktu. Opsi --wait-timeout mengatur batas waktu penantian itu. Perintah ini berguna di skrip deployment dan CI/CD agar proses deploy gagal secara eksplisit bila layanan tidak sehat, bukan diam-diam dianggap berhasil.

Langkah 5: Menguji, Container Unhealthy Benar-Benar Restart

Pengaturan yang tidak pernah diuji sama dengan tidak ada pengaturan. Uji rangkaiannya dengan cara yang aman di server staging atau di luar jam sibuk. Pertama, pastikan semua container sehat dengan docker ps dan catat RestartCount awal lewat docker inspect --format='{{.RestartCount}}' nama-container.

Kedua, buat layanan gagal dengan sengaja. Cara paling mudah adalah menghentikan proses di dalam container tanpa mematikan containernya, misalnya dengan mengeksekusi perintah yang membuat aplikasi berhenti merespons, atau untuk pengujian cepat, ubah sementara healthcheck menjadi perintah yang selalu gagal seperti test: ["CMD", "false"] lalu jalankan docker compose up -d lagi. Dalam waktu sekitar 90 detik, status container akan berubah menjadi unhealthy.

Ketiga, amati log Autoheal dengan docker logs autoheal -f. Kamu akan melihat pesan bahwa container yang tidak sehat terdeteksi dan sedang di-restart. Periksa ulang RestartCount, dan pastikan angkanya bertambah. Terakhir, kembalikan healthcheck ke perintah yang benar, jalankan docker compose up -d sekali lagi, dan pastikan status kembali menjadi healthy. Bila container tidak di-restart, periksa tiga hal: label autoheal sudah terpasang, variabel AUTOHEAL_CONTAINER_LABEL sudah cocok dengan labelmu, dan volume Docker socket sudah ter-mount dengan benar.

Alternatif Autoheal, Cron dan Systemd Timer

Bila kamu enggan memasang container tambahan yang memegang Docker socket, ada alternatif yang lebih sederhana. Cron job yang berjalan setiap dua menit dapat me-restart semua container yang berstatus unhealthy dengan satu baris perintah yang didokumentasikan di panduan Docker sendiri.

*/2 * * * * docker ps --filter health=unhealthy --format "{{.Names}}" | xargs -r docker restart

Perintah ini memakai filter health=unhealthy dari Docker, lalu me-restart setiap nama container yang muncul. Opsi -r pada xargs memastikan tidak ada perintah restart yang dijalankan bila daftarnya kosong. Alternatif yang lebih rapi di sistem modern adalah systemd timer, yang memberi kamu logging lewat journal dan kontrol dependensi terhadap layanan Docker. Timer systemd juga lebih mudah diuji dengan systemctl list-timers dan journalctl -u nama-service.

Untuk skala yang lebih besar, Docker Swarm adalah pengecualian dari aturan ini. Dalam mode Swarm, task yang gagal healthcheck akan dihentikan dan diganti oleh orchestrator secara bawaan. Kubernetes pun memiliki liveness probe dengan perilaku serupa. Namun untuk satu VPS dengan Compose biasa, Autoheal, cron, atau systemd timer adalah tiga pilihan yang masuk akal, dan Autoheal adalah yang paling otomatis di antara ketiganya.

Pilihan mana pun yang kamu ambil, pasangkan dengan pemantauan dari luar. Healthcheck dan Autoheal memulihkan layanan, tetapi keduanya tidak bisa memberitahumu bahwa pemulihan sedang terjadi berulang kali. Di sinilah pemantauan eksternal berperan. Artikel kami tentang Install Uptime Kuma di VPS Ubuntu dengan Docker, Monitor Website Kamu 24 Jam menunjukkan cara memasang pemantau yang mengirim notifikasi begitu layananmu down, sehingga kamu tahu bila sebuah container di-restart sepuluh kali dalam semalam dan perlu diperbaiki akar masalahnya.

Risiko Keamanan Docker Socket dan Cara Menguranginya

Memasang Docker socket ke dalam container adalah keputusan keamanan yang serius dan perlu kamu pahami sebelum melakukannya. Socket tersebut memberi akses penuh ke daemon Docker, yang setara dengan akses root di host. Dokumentasi proyek OpenProject yang memakai pola yang sama menegaskan bahwa container dengan akses socket dapat menjalankan operasi restart dan memperoleh akses tulis ke daemon, sehingga image pihak ketiga yang memakainya harus benar-benar dipercaya.

Beberapa langkah dapat mengurangi risikonya. Pertama, pin versi image Autoheal ke tag spesifik, misalnya willfarrell/autoheal:1.2.0, bukan latest, supaya pembaruan image tidak terjadi diam-diam. Kedua, batasi label yang diawasi hanya pada container yang memang perlu, jangan memakai AUTOHEAL_CONTAINER_LABEL=all bila tidak diperlukan. Ketiga, jangan mengekspos Docker socket lewat jaringan dan jangan menjalankan Autoheal di host yang juga dipakai pengguna lain.

Bila risiko socket tetap terasa terlalu besar, pilih alternatif cron atau systemd timer dari bagian sebelumnya. Skrip yang berjalan langsung di host tidak memerlukan container tambahan yang memegang socket, dan perintahnya dapat kamu audit baris demi baris. Prinsipnya sama seperti pengamanan VPS pada umumnya: setiap komponen tambahan adalah permukaan serangan baru, jadi pasang hanya yang kamu pahami dan butuhkan.

Kesalahan Umum saat Memasang Healthcheck

Kesalahan pertama adalah menganggap healthcheck sama dengan restart otomatis. Seperti yang sudah dibuktikan pengujian pada Docker Engine 29.8.1, container unhealthy tidak akan di-restart tanpa pengawas eksternal. Healthcheck tanpa Autoheal atau cron hanyalah monitor, bukan perbaikan.

Kesalahan kedua adalah memakai perintah pemeriksaan yang tidak pernah gagal. Healthcheck yang selalu mengembalikan kode 0, misalnya memeriksa keberadaan file yang selalu ada, tidak memberi informasi apa pun. Uji healthcheck-mu dengan membuat layanan gagal secara sengaja, seperti pada langkah pengujian di atas.

Kesalahan ketiga adalah start period yang terlalu pendek. Aplikasi yang butuh 60 detik untuk siap tetapi diberi start period 10 detik akan dinyatakan unhealthy berulang kali dan di-restart terus-menerus sebelum sempat berjalan. Gejalanya adalah container yang restart tanpa henti, dan solusinya adalah menaikkan start period atau menurunkan interval pemeriksaan.

Kesalahan keempat adalah lupa memasang alat pemeriksaan di dalam image. Perintah curl tidak tersedia di semua image, terutama image minimal berbasis Alpine atau distroless. Periksa dulu dengan docker exec nama-container which curl, dan bila tidak ada, gunakan wget atau periksa endpoint kesehatan dengan alat yang tersedia di image tersebut.

Kesalahan kelima adalah mengabaikan log. Saat container dinyatakan unhealthy, Docker menyimpan keluaran pemeriksaan terakhir. Perintah docker inspect pada bagian Health menampilkan log tersebut, dan membacanya hampir selalu lebih cepat daripada menebak-nebak penyebabnya.

Kesimpulan: Healthcheck Docker dan Restart Otomatis

Healthcheck Docker memberi tahu kamu bahwa container bermasalah, tetapi tidak memperbaikinya. Restart policy hanya bereaksi saat proses utama keluar, bukan saat status berubah menjadi unhealthy. Untuk menutup celah ini di satu VPS, rangkai tiga hal: tulis healthcheck yang benar-benar menguji layananmu, pasang Autoheal atau cron job untuk container restart otomatis saat unhealthy, dan atur depends_on dengan condition service_healthy agar layanan start dengan urutan yang benar. Uji seluruh rangkaian dengan membuat layanan gagal secara sengaja, dan pasangkan dengan pemantauan eksternal seperti Uptime Kuma agar kamu tahu bila container yang sama di-restart berulang kali. Restart otomatis adalah pereda, bukan obat. Bila sebuah container jatuh berulang kali, perbaiki akar masalahnya, jangan hanya mempercepat restart-nya.

FAQ

Apakah healthcheck Docker membuat container restart otomatis saat unhealthy?

Tidak. Healthcheck Docker hanya mengubah status container menjadi unhealthy. Restart policy Docker hanya bereaksi saat proses utama container keluar, bukan saat status kesehatan berubah. Untuk restart otomatis, kamu butuh Autoheal, cron job, atau Docker Swarm.

Apa perbedaan restart policy always dan unless-stopped?

Keduanya me-restart container hampir di semua kondisi. Perbedaannya, policy always juga me-restart container setelah daemon Docker ikut restart meskipun kamu menghentikannya secara manual sebelumnya, sedangkan unless-stopped menghormati perintah stop manual kamu.

Apakah Autoheal aman dipakai di VPS produksi?

Autoheal aman dipakai bila kamu memahami risikonya. Container ini membutuhkan akses ke Docker socket, yang setara dengan akses root di host. Pin versi image ke tag spesifik, batasi label yang diawasi, dan jangan memakainya di server bersama yang tidak kamu kendalikan penuh.

Berapa interval healthcheck yang ideal?

Interval 30 detik dengan timeout 10 detik dan retries 3 adalah titik awal yang aman untuk kebanyakan layanan web. Untuk layanan yang lambat merespons, naikkan interval dan start period. Untuk layanan kritis yang butuh deteksi cepat, interval 10 detik dengan retries 5 adalah kombinasi yang masih wajar.

Apakah Docker Swarm me-restart container unhealthy secara otomatis?

Ya. Dalam mode Swarm, task yang gagal healthcheck akan dihentikan dan diganti oleh orchestrator secara bawaan. Perilaku ini tidak berlaku pada Docker Compose biasa, yang membutuhkan Autoheal atau pengawas eksternal.

Referensi: catatan rilis Docker Engine 29 (docs.docker.com, 3 November 2026); Cloudhim, “Docker Won’t Restart an “Unhealthy” Container: Here’s What Actually Will” (4 November 2026); Matthew Wong, “Docker Healthcheck Tutorial: Health States and Restart Policies” (pengujian pada Docker Engine 29.8.1); dokumentasi Dockerfile dan restart policy Docker; repositori GitHub willfarrell/docker-autoheal; panduan auto-healing Docker oleh gntech (22 Mei 2026). Artikel ini juga merujuk pada panduan internal kami tentang rotasi log Docker agar disk VPS kamu tidak penuh diam-diam.

Suka Menulis

You might also like
Install Uptime Kuma di VPS Ubuntu dengan Docker, Monitor Website Kamu 24 Jam

Install Uptime Kuma di VPS Ubuntu dengan Docker, Monitor Website Kamu 24 Jam

Agar Disk VPS Tidak Penuh Diam-Diam, Atur Rotasi Log Docker Sekarang

Agar Disk VPS Tidak Penuh Diam-Diam, Atur Rotasi Log Docker Sekarang

Apa Itu Microcloud? Mengenal Canonical Microcloud Untuk Solusi Private Cloud

Apa Itu Microcloud? Mengenal Canonical Microcloud Untuk Solusi Private Cloud

Apa itu Openstack?  Penjelasan Lengkap Openstack untuk Pemula

Apa itu Openstack? Penjelasan Lengkap Openstack untuk Pemula

Apa Itu Ceph? Panduan Lengkap Ceph Storage Cluster untuk Pemula

Apa Itu Ceph? Panduan Lengkap Ceph Storage Cluster untuk Pemula

Apa itu Kubernetes ? Penjelasan Lengkap Kubernetes

Apa itu Kubernetes ? Penjelasan Lengkap Kubernetes

Pesan dengan Border Radius

Informasi


Saya bisa membantu instalasi Server seperti: LAMP atau LEMP Stack, Control Panel VPS, Instalasi WebApp, Mail Server, atau sekedar tanya tutorial di web ini. Untuk itu, silahkan hubungi saya melalui kontak yang telah tersedia.

OrangeVPS VPS Murah
Most Populer
Cara Install Armbian Linux 25.05.0 di STB HG680P
Review dan Bencmark STB HG680P Armbian Linux 24.11
Cara Mengaktifkan WiFi di Armbian STB HG680P
Apa Itu Armbian ? Penjelasan Lengkap Armbian Linux Ubuntu Debian Based
Firmware Armbian STB | WiFi On, GUI, & Support RAM 4GB