Docker Container Tidak Bisa Start: Panduan Debug Lengkap

Docker Container Tidak Bisa Start: Panduan Debug Lengkap

Container yang tidak mau start adalah salah satu frustrasi paling umum saat belajar Docker. Error message-nya sering tidak jelas, dan tidak tahu harus mulai debug dari mana. Artikel ini adalah panduan sistematis untuk mendiagnosis dan memperbaiki container yang bermasalah.

---

1. Langkah Pertama: Baca Log dengan Benar

# Lihat status semua container (termasuk yang sudah stop/exit)
docker ps -a

# Output contoh:
# CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS                     NAMES
# a1b2c3d4e5f6   myapp     "node"    1 min     Exited (1) 30 seconds ago  myapp_1

# Lihat log container yang gagal
docker logs myapp_1

# Lihat log dengan timestamp
docker logs --timestamps myapp_1

# Lihat log real-time (follow)
docker logs -f myapp_1

# Lihat hanya 50 baris terakhir
docker logs --tail 50 myapp_1

---

2. Error Paling Umum dan Cara Fixnya

Error 1: Port Already in Use

# Error:
# Error response from daemon: driver failed programming external connectivity:
# Bind for 0.0.0.0:3000 failed: port is already allocated

# Cari proses yang pakai port tersebut
lsof -i :3000
# atau
sudo ss -tulpn | grep :3000

# Kill proses yang menggunakan port
kill -9 [PID]

# Atau ganti port mapping di docker run / docker-compose
# docker run -p 3001:3000 myapp  (host:container)

# docker-compose.yml
ports:
  - "3001:3000"  # Ganti 3001 ke port yang tersedia

Error 2: Container Langsung Exit (Exit Code 1)

# Container start tapi langsung mati
# Cek log untuk tahu penyebabnya
docker logs myapp_1

# Penyebab umum:
# 1. Environment variable yang dibutuhkan tidak ada
#    Error: "DATABASE_URL is required"
#    Fix: pastikan semua env var terdefinisi

# 2. File atau direktori tidak ditemukan
#    Error: "cannot find module '/app/index.js'"
#    Fix: cek WORKDIR dan COPY di Dockerfile

# 3. Permission denied
#    Error: "permission denied: /app/data"
#    Fix: tambahkan RUN chmod di Dockerfile atau gunakan user yang tepat

# Debug: jalankan container secara interaktif
docker run -it --entrypoint /bin/sh myapp
# Sekarang kamu bisa explore filesystem container secara manual

Error 3: Image Not Found

# Error:
# Unable to find image 'myapp:latest' locally
# Error response from daemon: pull access denied

# Solusi 1: Build image dulu
docker build -t myapp:latest .

# Solusi 2: Cek nama image yang tersedia
docker images

# Solusi 3: Jika dari registry private, login dulu
docker login registry.example.com
docker pull registry.example.com/myapp:latest

Error 4: Network Issues antar Container

# Container tidak bisa konek ke container lain
# Error: "connect ECONNREFUSED 127.0.0.1:5432"

# Masalah: menggunakan localhost/127.0.0.1 untuk konek ke container lain
# Di Docker, setiap container punya network namespace sendiri

# ❌ Salah — localhost di dalam container = container itu sendiri
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# ✅ Benar — gunakan nama service dari docker-compose
DATABASE_URL=postgresql://user:pass@postgres:5432/db

# Cek network yang dipakai container
docker network ls
docker network inspect bridge

# Cek apakah container ada di network yang sama
docker inspect myapp_1 | grep -A 20 "Networks"

Error 5: Volume Mount Permission Denied

# Error:
# mkdir: cannot create directory '/app/data': Permission denied

# Solusi 1: Tambahkan permission di Dockerfile
RUN mkdir -p /app/data && chmod 777 /app/data

# Solusi 2: Jalankan sebagai root (tidak disarankan untuk production)
docker run --user root myapp

# Solusi 3: Sesuaikan ownership
docker run -v $(pwd)/data:/app/data --user $(id -u):$(id -g) myapp

# Solusi 4: Untuk named volume, init dengan container sementara
docker run --rm -v myapp_data:/data alpine chmod 777 /data

Error 6: Out of Memory (OOMKilled)

# Container di-kill karena kehabisan memory
# docker ps -a menunjukkan: Exited (137)
# docker inspect menunjukkan: "OOMKilled": true

# Cek memory usage
docker stats

# Solusi 1: Tambah memory limit
docker run -m 512m myapp
# atau di docker-compose:
deploy:
  resources:
    limits:
      memory: 512M

# Solusi 2: Optimasi aplikasi (cari memory leak)
# Solusi 3: Tambah swap
docker run -m 512m --memory-swap 1g myapp

---

3. Debug docker-compose yang Bermasalah

# Lihat log semua service sekaligus
docker-compose logs

# Lihat log service tertentu
docker-compose logs postgres
docker-compose logs -f app  # follow mode

# Cek status semua service
docker-compose ps

# Restart service tertentu
docker-compose restart app

# Rebuild image dan restart (setelah ubah Dockerfile)
docker-compose up --build app

# Stop semua dan hapus container + network (tapi bukan volume)
docker-compose down

# Stop dan hapus semua termasuk volume (HATI-HATI: data hilang!)
docker-compose down -v

# Validasi syntax docker-compose.yml
docker-compose config

---

4. Toolkit Debug Docker

# Masuk ke dalam container yang sedang running
docker exec -it myapp_1 /bin/bash
# atau jika tidak ada bash:
docker exec -it myapp_1 /bin/sh

# Inspect detail container (network, volume, env, dll)
docker inspect myapp_1

# Lihat resource usage real-time
docker stats

# Lihat proses di dalam container
docker top myapp_1

# Copy file dari/ke container
docker cp myapp_1:/app/logs/error.log ./error.log
docker cp ./config.json myapp_1:/app/config.json

# Lihat perubahan filesystem sejak container start
docker diff myapp_1

---

5. Checklist Sebelum Deploy Container

Cek	Perintah
Image berhasil di-build tanpa error?	docker build -t myapp .
Semua env var terdefinisi?	Cek .env file atau environment: di compose
Port tidak bentrok dengan service lain?	lsof -i :[port]
Volume path benar dan ada permission?	ls -la [path]
Container bisa konek ke database?	docker exec -it app ping postgres
Health check pass?	docker inspect --format='{{.State.Health}}' myapp

---

Kesimpulan

Hampir semua masalah Docker bisa didiagnosis dengan tiga perintah: docker ps -a untuk lihat status, docker logs untuk lihat error, dan docker exec -it ... /bin/sh untuk masuk ke dalam container dan investigasi langsung. Dengan pendekatan sistematis ini, tidak ada container error yang tidak bisa di-debug.