Docker를 처음 설치하고 나서 docker ps 같은 간단한 명령어를 실행했는데 이런 에러 메시지가 나타난 경험이 있으신가요?
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
정말 당황스럽죠. 분명히 Docker를 정상적으로 설치했는데 왜 이런 문제가 발생하는 걸까요? 이번 포스트서 Docker daemon socket 권한 에러가 발생하는 이유부터 단계별 해결방법까지 상세하게 알아보겠습니다.
1. 에러가 발생하는 이유 이해하기
Docker daemon socket 권한 에러를 해결하기 전에, 먼저 왜 이런 문제가 발생하는지 알아보는 것이 중요합니다.
Docker의 작동 원리
Docker는 클라이언트-서버 구조로 동작합니다. 우리가 터미널에서 입력하는 docker 명령어는 클라이언트이고, 실제로 컨테이너를 관리하는 것은 Docker daemon(dockerd)이라는 백그라운드 프로세스입니다.
이 둘 사이의 통신은 Unix 소켓을 통해 이루어지며, 기본적으로 /var/run/docker.sock 파일을 사용합니다.
권한 문제의 본질
문제는 바로 이 소켓 파일의 소유권과 권한에 있습니다. 기본적으로 이 파일은 다음과 같은 권한을 가지고 있습니다:
ls -l /var/run/docker.sock
srw-rw---- 1 root docker 0 Dec 15 10:30 /var/run/docker.sock
여기서 중요한 점은:
- 소유자:
root - 그룹:
docker - 권한: 소유자와 그룹 멤버만 읽기/쓰기 가능
즉, 일반 사용자는 이 소켓에 접근할 수 없어서 “permission denied” 에러가 발생하는 것입니다.
2. 가장 권장되는 해결방법: Docker 그룹에 사용자 추가
가장 안전하고 권장되는 해결방법은 현재 사용자를 docker 그룹에 추가하는 것입니다. 이 방법을 단계별로 살펴보겠습니다.
2-1. Docker 그룹 확인 및 생성
먼저 시스템에 docker 그룹이 있는지 확인해보세요:
getent group docker
만약 그룹이 존재하지 않는다면 다음 명령어로 생성할 수 있습니다:
sudo groupadd docker
2-2. 사용자를 Docker 그룹에 추가
다음 명령어로 현재 사용자를 docker 그룹에 추가합니다:
sudo usermod -aG docker $USER
여기서 $USER는 현재 로그인한 사용자명을 자동으로 가져오는 환경변수입니다. 만약 다른 사용자를 추가하고 싶다면 $USER 대신 해당 사용자명을 직접 입력하면 됩니다.
2-3. 세션 재시작
그룹 변경사항이 적용되려면 세션을 재시작해야 합니다. 다음 중 하나의 방법을 선택하세요:
방법 1: 로그아웃 후 다시 로그인 가장 확실한 방법입니다.
방법 2: newgrp 명령어 사용
newgrp docker
방법 3: su 명령어 사용
su - $USER
2-4. 설정 확인
설정이 올바르게 적용되었는지 확인해보세요:
groups
출력 결과에 docker가 포함되어 있어야 합니다.
이제 sudo 없이 Docker 명령어를 실행해보세요:
docker run hello-world
정상적으로 실행된다면 문제가 해결된 것입니다!
3. 임시 해결방법: sudo 사용하기
Docker 그룹 설정이 복잡하거나 일시적으로만 Docker를 사용해야 하는 경우에는 sudo를 사용할 수 있습니다.
sudo docker ps
sudo docker run hello-world
sudo docker images
하지만 이 방법은 몇 가지 단점이 있습니다:
- 매번 패스워드를 입력해야 함
- 루트 권한으로 실행되어 보안상 위험할 수 있음
- 스크립트 자동화에 적합하지 않음
따라서 임시 방편으로만 사용하고, 가능하면 Docker 그룹 설정을 권장합니다.
4. ~/.docker 디렉토리 권한 문제 해결
만약 이전에 sudo를 사용해서 Docker 명령어를 실행한 적이 있다면, ~/.docker 디렉토리의 권한이 잘못 설정되어 있을 수 있습니다.
문제 증상
다음과 같은 경고 메시지가 나타날 수 있습니다:
WARNING: Error loading config file: /home/user/.docker/config.json -
stat /home/user/.docker/config.json: permission denied
해결방법
다음 명령어로 권한을 수정하세요:
sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
sudo chmod g+rwx "$HOME/.docker" -R
또는 디렉토리를 완전히 삭제하고 다시 생성되도록 할 수도 있습니다:
sudo rm -rf ~/.docker
5. Docker 서비스 재시작으로 해결하기
때로는 Docker 서비스 자체에 문제가 있을 수 있습니다. 이런 경우 서비스를 재시작하면 해결될 수 있습니다.
systemd를 사용하는 시스템 (Ubuntu, CentOS 등)
sudo systemctl restart docker
sudo systemctl status docker
서비스 상태 확인에서 Active: active (running)이 표시되면 정상입니다.
Docker Desktop 사용자
Docker Desktop을 사용하고 있다면 애플리케이션을 완전히 종료한 후 다시 시작해보세요.
6. 소켓 파일 권한 직접 변경 (주의사항 포함)
인터넷에서 자주 볼 수 있는 방법 중 하나는 소켓 파일의 권한을 직접 변경하는 것입니다:
sudo chmod 666 /var/run/docker.sock
하지만 이 방법은 권장하지 않습니다. 이유는 다음과 같습니다:
보안상 위험
- 모든 사용자가 Docker daemon에 접근할 수 있게 됨
- Docker에 접근할 수 있다는 것은 사실상 루트 권한과 동일함
- 시스템 재부팅 시 권한이 원래대로 돌아감
더 안전한 대안
권한을 변경해야 한다면 최소한 다음과 같이 제한적으로 설정하세요:
sudo chmod 660 /var/run/docker.sock
하지만 여전히 Docker 그룹 방식이 더 안전하고 권장됩니다.
7. WSL (Windows Subsystem for Linux) 환경에서의 특별 고려사항
Windows에서 WSL을 사용해 Docker를 실행하는 경우, 몇 가지 추가 고려사항이 있습니다.
Docker Desktop과의 연동
Docker Desktop for Windows를 설치했다면, WSL 통합 설정을 확인하세요:
- Docker Desktop 설정 → Resources → WSL Integration
- 사용하고자 하는 WSL 배포판 활성화
WSL 전용 Docker 설치
WSL 내에서 직접 Docker를 설치한 경우, 일반적인 Linux 환경과 동일한 방법으로 해결할 수 있습니다.
8. 문제가 지속될 때의 추가 진단 방법
위의 방법들을 모두 시도해도 문제가 해결되지 않는다면, 다음 진단 단계를 따라해보세요.
8-1. Docker 설치 상태 확인
docker --version
docker-compose --version
8-2. Docker daemon 상태 확인
sudo systemctl status docker
8-3. 소켓 파일 존재 여부 확인
ls -la /var/run/docker.sock
8-4. 사용자 그룹 정보 상세 확인
id $USER
groups $USER
8-5. Docker 로그 확인
sudo journalctl -u docker.service --no-pager
Docker 권한 에러를 겪지 않으려면 다음 사항들을 기억해두세요:
Docker 설치 시 주의사항
- 공식 Docker 설치 가이드를 따라 설치
- 설치 후 즉시 사용자를 docker 그룹에 추가
- 설치 완료 후 재로그인 또는 세션 재시작
정기적인 점검
- Docker 버전 업데이트 후 권한 설정 확인
- 새로운 사용자 추가 시 docker 그룹 포함 여부 확인
- 시스템 업데이트 후 Docker 서비스 상태 점검
가장 중요한 것은 Docker 그룹에 사용자를 추가하는 방법을 기억하는 것입니다. 이 방법만 알고 있어도 대부분의 권한 문제는 해결할 수 있다는 것을 기억하세요! 🙂