Docker permission denied /var/run/docker.sock 에러 5분 해결법

Docker permission denied /var/run/docker.sock 에러 5분 해결법

그 빨간 에러 문구, 또 만났나요?

서버에 접속해서 가볍게 docker ps 한 줄을 쳤는데 이런 메시지가 뜬 경험, 다들 있으실 겁니다.

permission denied while trying to connect to the Docker daemon socket at
unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.43/containers/json":
dial unix /var/run/docker.sock: connect: permission denied

그래서 결국 sudo docker ps로 임시 회피하고, CI 러너에서는 또 막히고... 이 글은 그 무한 반복을 끝내기 위한 것입니다. 에러 문구 → 원인 진단 → 복붙 명령어 순서로 5분 안에 영구 해결까지 끌고 가겠습니다.

왜 막히는가 — docker.sock 소켓 권한의 원리

먼저 범인을 직접 봅시다.

ls -l /var/run/docker.sock
# srw-rw---- 1 root docker 0 Jun 24 09:12 /var/run/docker.sock

이 출력을 분해하면 모든 게 설명됩니다.

• s : 일반 파일이 아니라 유닉스 소켓
• rw- (소유자 root) / rw- (그룹 docker) / --- (그 외) : 즉 root이거나 docker 그룹에 속한 유저만 읽고 쓸 수 있음
• 소유권 root:docker

Docker는 데몬(dockerd)이 root 권한으로 떠 있고, docker CLI는 사실 이 소켓에 명령을 써넣는 클라이언트일 뿐입니다.

[docker CLI] --(소켓에 write)--> /var/run/docker.sock --> [dockerd (root)]
                                  소유권: root:docker
                                  권한:   srw-rw----

그러니까 내 계정이 docker 그룹 멤버가 아니면 소켓에 쓸 권한이 없어서 permission denied가 나는 겁니다. 결론은 단순합니다. docker 그룹 멤버십이 핵심이에요.

원인별 5분 진단표

증상을 보고 자기 케이스를 먼저 특정하세요.

복붙 해결 명령어 모음

케이스 ① 그룹에 추가하기

# 현재 그룹 확인
id

# docker 그룹에 현재 유저 추가
sudo usermod -aG docker $USER

# 즉시 반영 (재로그인 대체)
newgrp docker

# 반영 확인 - docker가 보이면 성공
groups

가장 깔끔한 건 exit 후 SSH 재접속입니다. 새 셸이 갱신된 그룹 정보를 들고 시작하니까요.

케이스 ③ 소켓이 손상됐을 때

ls -l /var/run/docker.sock          # 상태 확인
sudo chown root:docker /var/run/docker.sock
sudo chmod 660 /var/run/docker.sock
sudo systemctl restart docker       # 데몬 재시작으로 소켓 재생성

케이스 ④ rootless docker

# rootless는 사용자 전용 소켓을 사용
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock
docker context use rootless

"usermod 했는데도 안 돼요" — 가장 흔한 함정

이게 진짜 많이 막히는 지점입니다. usermod -aG docker까지 했는데 여전히 permission denied가 난다면, 가장 먼저 의심할 원인은 현재 셸 세션이 옛날 그룹 정보를 그대로 들고 있기 때문입니다.

그룹 멤버십은 로그인 시점에 셸에 박히는 정보라서, 이미 떠 있는 셸은 자동으로 갱신되지 않아요. 다음 두 명령으로 직접 비교해 보세요.

id      # 현재 "셸 세션"에 적용된 그룹 → docker 없음
groups  # 마찬가지로 현 세션 기준

getent group docker   # 시스템 DB 기준 → 여기엔 내가 들어있음!

getent에는 있는데 id에 없다면 세션 미반영이 확정입니다. 해결은 셋 중 하나:

1. newgrp docker — 새 그룹으로 서브셸 진입 (즉시)
2. 완전 로그아웃 후 SSH 재접속 — 가장 확실
3. sudo systemctl restart docker 후 재접속 (소켓 문제까지 겸한 경우)

실무 팁: tmux/screen 세션 안에서 작업 중이라면 newgrp만으로 안 풀릴 때가 있습니다. 이땐 세션을 완전히 죽였다가 다시 attach해야 깔끔하게 반영됩니다. 저는 이걸 모르고 30분을 날린 적이 있어요.

데몬이 꺼져 있거나 docker 그룹이 없을 때, 그리고 WSL2

권한 문제처럼 보여도 데몬 자체가 안 떠 있는 경우가 있습니다. 이때는 문구가 Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?으로 달라지니 먼저 구분하세요.

systemctl status docker        # active (running)인지 확인
sudo systemctl start docker    # 꺼져 있으면 시작
sudo systemctl enable docker   # 부팅 시 자동 시작
getent group docker            # docker 그룹이 있는지 확인
sudo groupadd docker           # 그룹이 없을 때만 (이미 있으면 "already exists"가 나고 무시해도 됨)

WSL2는 구성에 따라 해결 지점이 다릅니다. Docker 공식 문서: Linux 설치 후 설정

WSL2에서는 셸을 새로 열어도 같은 인스턴스가 계속 살아 있어서 그룹 변경이 반영되지 않는 경우가 있습니다. 이때 wsl --shutdown이 재로그인 역할을 합니다.

임시 우회 vs 영구 해결 vs rootless

환경별 주의점 (CI/CD)

• GitHub Actions: 공식 ubuntu 러너는 이미 권한이 잡혀 있어 그냥 됩니다. self-hosted 러너는 러너 실행 유저를 sudo usermod -aG docker <runner-user> 후 러너 서비스를 재시작해야 합니다.
• GitLab Runner: DinD(docker:dind) 대신 호스트 소켓을 마운트(-v /var/run/docker.sock:...)하는 경우, 컨테이너 내부 유저 GID가 호스트 docker 그룹 GID와 맞아야 합니다.
• 트렌드: 요즘은 CI에서 DinD의 보안·성능 부담 때문에 BuildKit / socket 마운트 방식이 늘고 있습니다. Docker Desktop 라이선스 이슈로 Podman·colima 대안도 활발히 쓰이고요.

결론: 영구 해결 체크리스트 + 보안 경고

□ id 에 docker 그룹이 보이는가
□ ls -l /var/run/docker.sock 이 srw-rw---- root docker 인가
□ usermod 후 재로그인(또는 newgrp)으로 세션 갱신했는가
□ sudo 없이 docker ps 가 동작하는가

마지막으로 단호하게 짚고 갑니다. docker 그룹 멤버는 컨테이너에 호스트 루트 파일시스템(-v /:/host)을 마운트해 사실상 root 권한을 탈취할 수 있습니다. 즉 docker 그룹 = root입니다.

따라서 공유 서버나 프로덕션에서는 무분별한 그룹 추가를 피하고, rootless docker나 sudo + 감사 로깅 정책을 권장합니다. 개인 개발 서버라면 그룹 추가가 가장 편하지만, 그 의미는 알고 쓰세요.

한 줄 요약: 막히면 id로 그룹 확인 → 없으면 usermod -aG docker $USER → 재로그인 → docker ps. 즐겨찾기 해두면 다음에 또 헤매지 않습니다.

참고: 공식 문서

이 글에서 다루는 동작·설정·에러의 1차 출처는 다음 공식 문서입니다. 버전별 옵션과 정확한 동작은 여기서 확인하세요.

• Docker 공식 문서

자주 묻는 질문 (FAQ)

Q. usermod 했는데도 계속 permission denied가 떠요. A. 현재 셸 세션에 옛 그룹 정보가 남아서입니다. getent group docker엔 있는데 id엔 없다면 세션 미반영입니다. newgrp docker 또는 SSH 완전 재접속으로 해결됩니다.

Q. sudo 없이 쓰는 게 보안상 괜찮나요? A. docker 그룹은 사실상 root와 동급 권한입니다. 개인 서버는 무방하지만, 공유·프로덕션 서버에서는 rootless docker나 sudo 감사 정책을 권장합니다.

Q. WSL/Mac에서도 같은 명령으로 해결되나요? A. 아니요. Docker Desktop은 별도 백엔드를 쓰므로 그룹 문제와 무관한 경우가 많습니다. Desktop 설정과 WSL integration 활성화 여부를 먼저 확인하세요.