본문으로 건너뛰기

Docker 관련 문제

Docker 환경에서 발생하는 문제와 해결 방법입니다.

컨테이너 시작 실패​

포트 충돌​

증상:

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

해결 방법:

  1. 사용 중인 포트 확인

    # Linux/Mac
    lsof -i :8080

    # 또는
    netstat -tlnp | grep 8080

  2. 다른 포트 사용

    # .env에서 포트 변경
    APP_PORT=8081

  3. 충돌 프로세스 종료

    kill -9 $(lsof -t -i:8080)

이미지 빌드 실패​

증상:

failed to solve: failed to compute cache key: failed to calculate checksum

해결 방법:

  1. Docker 캐시 정리

    docker builder prune

  2. 빌드 캐시 없이 재빌드

    docker compose build --no-cache

  3. 시스템 정리

    docker system prune -a

컨테이너가 바로 종료됨​

증상:

Container myapp-web exited with code 1

원인 파악:

# 로그 확인
docker logs myapp-web

# 마지막 종료 상태 확인
docker inspect myapp-web --format='{{.State.ExitCode}}'

일반적인 원인:

Exit Code원인해결 방법
0정상 종료서비스 설정 확인
1애플리케이션 오류로그 확인
137OOM (메모리 부족)메모리 제한 증가
139Segmentation fault이미지 재빌드

네트워크 문제​

컨테이너 간 통신 실패​

증상:

cURL error 7: Failed to connect to postgres port 5432: Connection refused

확인 및 해결:

  1. 네트워크 확인

    docker network ls
    docker network inspect myapp-network

  2. 컨테이너가 같은 네트워크에 있는지 확인

    docker inspect myapp-web --format='{{json .NetworkSettings.Networks}}'

  3. 서비스 이름으로 접근

    # .env에서
    DB_HOST=postgres      # 컨테이너 이름 사용 (localhost 아님)
    REDIS_HOST=redis      # 컨테이너 이름 사용

DNS 해석 실패​

증상:

Could not resolve host: postgres

해결 방법:

  1. DNS 설정 확인

    # docker-compose.yml
    services:
      web:
        dns:
          - 8.8.8.8
          - 8.8.4.4

  2. hosts 파일에 직접 추가 (임시 방법)

    services:
      web:
        extra_hosts:
          - "postgres:172.18.0.2"

외부 접속 불가​

증상:

  • localhost에서는 접속되지만 외부에서 안 됨

확인 사항:

# docker-compose.yml
services:
  nginx:
    ports:
      - "0.0.0.0:8080:80"  # 모든 인터페이스에서 수신
      # - "127.0.0.1:8080:80"  # localhost만 (이 경우 외부 접속 불가)

방화벽 확인:

# Ubuntu
sudo ufw status
sudo ufw allow 8080

# CentOS
sudo firewall-cmd --list-ports
sudo firewall-cmd --add-port=8080/tcp --permanent

볼륨/권한 문제​

Permission Denied​

증상:

mkdir: cannot create directory '/var/www/html/storage': Permission denied

해결 방법:

  1. 호스트에서 권한 설정

    sudo chown -R 1000:1000 ./storage ./bootstrap/cache
    chmod -R 775 ./storage ./bootstrap/cache

  2. Docker 컨테이너 내 사용자 확인

    docker exec myapp-web id
    # uid=1000(www-data) gid=1000(www-data)

  3. Dockerfile에서 사용자 설정

    RUN chown -R www-data:www-data /var/www/html
    USER www-data

볼륨 마운트 실패​

증상:

Error response from daemon: invalid mount config: invalid mount path

확인 사항:

# docker-compose.yml
volumes:
  - ./storage:/var/www/html/storage    # 상대 경로
  - /absolute/path:/var/www/html/data  # 절대 경로

Windows 경로 문제:

# Windows에서는 다음 형식 사용
volumes:
  - //c/Users/name/project:/var/www/html

pgAdmin 권한 오류​

증상:

FATAL: role "pgadmin" does not exist

해결 방법:

# pgAdmin은 UID 5050으로 실행됨
sudo chown -R 5050:5050 ./data/pgadmin

# Makefile로 자동 처리
make up NAME=_devtools/pgadmin

리소스 문제​

메모리 부족 (OOM)​

증상:

Killed
Container exited with code 137

해결 방법:

  1. Docker 메모리 제한 확인

    docker stats

  2. 메모리 제한 설정

    # docker-compose.yml
    services:
      web:
        deploy:
          resources:
            limits:
              memory: 1G
            reservations:
              memory: 512M

  3. Docker Desktop 설정 (Mac/Windows)

    • Settings → Resources → Memory 증가

디스크 공간 부족​

증상:

no space left on device

해결 방법:

# 사용하지 않는 리소스 정리
docker system prune -a

# 볼륨도 정리 (데이터 손실 주의!)
docker volume prune

# 디스크 사용량 확인
docker system df

이미지/빌드 문제​

캐시로 인한 변경 미적용​

증상:

  • 코드 변경했는데 반영 안 됨

해결 방법:

# 캐시 없이 빌드
docker compose build --no-cache

# 또는 특정 서비스만
docker compose build --no-cache web

Multi-platform 빌드 오류​

증상:

ERROR: no matching manifest for linux/arm64/v8

해결 방법:

# platform 지정
docker compose build --platform linux/amd64

# 또는 docker-compose.yml에서
services:
  web:
    platform: linux/amd64

로그/디버깅​

컨테이너 로그 확인​

# 실시간 로그
docker logs -f myapp-web

# 최근 100줄
docker logs --tail 100 myapp-web

# 특정 시간 이후
docker logs --since 1h myapp-web

컨테이너 내부 접속​

# bash 접속
docker exec -it myapp-web bash

# root로 접속
docker exec -it -u root myapp-web bash

컨테이너 상태 상세 확인​

docker inspect myapp-web
docker inspect myapp-web --format='{{json .State}}'

Docker Compose 명령어​

기본 명령어​

# 시작
docker compose up -d

# 중지
docker compose down

# 재시작
docker compose restart

# 상태 확인
docker compose ps

트러블슈팅 명령어​

# 설정 확인 (문법 검증)
docker compose config

# 서비스 재생성
docker compose up -d --force-recreate

# 특정 서비스만 재시작
docker compose restart web

# 로그 통합 확인
docker compose logs -f

빠른 복구 절차​

완전 초기화 (데이터 유지)​

docker compose down
docker compose up -d --build

완전 초기화 (데이터 포함)​

주의

볼륨 삭제 시 데이터가 모두 삭제됩니다!

docker compose down -v
docker compose up -d --build

관련 문서​