docker.sock, permission denied, 도커 그룹 | sudo 없이 도커가 막히면?
docker.sock permission denied는 이미지가 없어서가 아니라 소켓이 docker 그룹에만 열려 현재 사용자가 빠져 있는 줄입니다. 데몬이 꺼진 문장과 구분하고, usermod -aG 뒤 재로그인, 맥은 Desktop 실행으로 나눕니다. Docker, 우분투, 한국 1인 개발자 기준. 2026년 9월 Docker 리눅스 post-install 문서.
도커 클라이언트가 하는 일은 소켓으로 데몬에게 말을 거는 것입니다. 리눅스 기본 소켓은 unix:///var/run/docker.sock입니다. 데몬이 없으면 Cannot connect to the Docker daemon ... Is the docker daemon running?이 납니다. 데몬은 있는데 이 사용자가 소켓을 못 열면 permission denied while trying to connect to the Docker daemon socket이 납니다. 이미지를 다시 받을 일이 아닙니다.
맥과 우분투가 여기서 갈립니다. 맥은 Docker Desktop 앱이 데몬을 띄웁니다. 메뉴 막대의 고래가 없으면 소켓 파일이 없고, 첫 문장이 납니다. 앱을 켜면 그룹 등록 없이 되는 경우가 많습니다. 우분투에 엔진만 설치한 VPS는 데몬이 systemctl로 살아 있어도, 로그인한 계정이 docker 그룹이 아니면 두 번째 문장이 납니다. 한국에서 싼 VPS에 넥스트를 컨테이너로 올리려다 설치 직후 이 줄에서 멈추는 경우가 많습니다.
프리즈마 바이너리가 알파인 이미지 안에 없는 오류와는 단계가 다릅니다. 컨테이너가 뜨기 전에 클라이언트가 데몬에 접속조차 못 한 상태입니다. 이미지 안의 엔진 파일은 Prisma OpenSSL 글에서 보면 됩니다.
daemon running 질문과 permission denied는 고치는 명령이 다르다. 자체 인포그래픽
리눅스에서는 그룹에 넣은 뒤 재로그인
usermod의 -a를 빼면 다른 그룹이 빠질 수 있습니다.
Docker 설치 후 문서는 사용자를 docker 그룹에 넣으라고 안내합니다. 소켓 소유는 보통 root:docker이고 모드는 0660이라, root와 그 그룹만 읽고 씁니다. 그룹에 없는 계정은 데몬이 명령을 보기 전에 운영체제가 소켓을 닫습니다.
확인할 것
정상
아니면
systemctl is-active docker
active
sudo systemctl start docker
ls -l /var/run/docker.sock
root docker, 0660 근처
그룹이 없으면 groupadd
groups
목록에 docker
usermod -aG 후 재로그인
docker run hello-world
인사 문장 후 종료
아직 옛 세션일 수 있음
명령은 문서 순서 그대로가 안전합니다. sudo groupadd docker는 그룹이 이미 있으면 안내만 하고 지나가도 됩니다. sudo usermod -aG docker $USER에서 -a는 추가입니다. -a 없이 -G만 쓰면 그 계정의 다른 보조 그룹이 교체될 수 있습니다. sudo 그룹까지 빠지면 다음 접속이 더 막힙니다.
그룹은 로그인 때 세션에 실립니다. usermod 직후의 같은 터미널은 아직 옛 목록입니다. 로그아웃 후 다시 들어오거나, 문서가 안내하는 newgrp docker로 새 셸을 열어야 groups에 docker가 보입니다. 가상 머신이면 재부팅이 필요한 경우도 있다고 같은 문서가 적습니다.
그룹에 넣기 전에 sudo docker를 여러 번 치면 ~/.docker가 root 소유로 생길 수 있습니다. 그 다음부터는 소켓은 열리는데 WARNING: Error loading config file: ... permission denied가 납니다. Docker 문서는 이 디렉터리를 지우거나, 소유를 현재 사용자로 바꾸라고 합니다. 지리면 그 안의 레지스트리 로그인 설정이 사라지니, 설정을 남길 거면 chown이 맞습니다.
소켓 자체에 chmod 777을 주는 방법은 문서 절차가 아닙니다. 데몬을 재시작하면 모드가 돌아가고, 그 사이 같은 호스트의 다른 계정과 작업이 도커를 쓸 수 있습니다. 도커 그룹은 사실상 호스트를 다룰 수 있는 권한에 가깝다고 설치 후 문서가 경고합니다. 신뢰하는 내 계정만 넣고, 공용 계정을 습관처럼 넣지 않으면 됩니다.
[ ] 문장이 daemon running인지 permission denied인지 골랐다
[ ] 리눅스면 소켓 소유와 groups를 봤다
[ ] usermod에 -aG를 붙였다
[ ] 로그아웃하거나 newgrp으로 세션을 갱신했다
[ ] hello-world가 sudo 없이 끝났다
usermod만으로는 현재 셸의 그룹 목록이 안 바뀐다. 자체 인포그래픽
맥에서는 앱이 데몬이다
맥의 첫 확인은 Docker Desktop이 켜져 있는지입니다.
Desktop이 꺼져 있으면 리눅스 그룹 명령을 칠 곳이 없습니다. 앱을 실행하고 고래가 안정된 뒤 docker info가 Server 항목을 보여 주면 데몬과 연결된 것입니다. 아직 Is the docker daemon running?이면 앱이 뜨는 중이거나, 소켓 경로가 예전 셸에 남아 있는 경우입니다. 터미널을 새로 열고 다시 치면 앱이 잡아 둔 경로를 탑니다.
맥에서 리눅스용 usermod를 따라 할 필요는 없습니다. 그 명령은 엔진을 리눅스에 직접 깐 서버용입니다. 국내 맥북으로 개발하고 배포만 우분투 VPS에 하는 구성이라면, 맥 오류는 앱 실행, 서버 오류는 그룹 등록으로 나누면 됩니다. 서버에서 컨테이너 포트가 이미 잡혀 EADDRINUSE가 나는 것은 소켓 권한 다음 단계입니다. 포트는 EADDRINUSE 글에서 프로세스를 찾으면 됩니다.
CI 러너에서만 같은 줄이 날 때
깃허브 호스티드 러너와 직접 깐 러너는 다릅니다.
GitHub Actions의 우분투 호스티드 러너는 도커를 쓰는 기본 이미지가 이미 데몬과 권한을 맞춰 둔 경우가 많습니다. 같은 워크플로가 내 VPS 셀프 호스티드 러너에서만 permission denied이면, 그 러너 계정이 docker 그룹에 없는 것입니다. 러너 사용자 이름으로 usermod -aG docker를 하고 러너 서비스를 재시작해야 세션이 갱신됩니다. 워크플로마다 chmod 777을 넣는 방식은 그 호스트를 열어 두므로 쓰지 않는 편이 맞습니다.
디스크 inode 감시 한도로 넥스트 dev가 멈추는 증상은 도커 소켓과 문장이 다릅니다. ENOSPC로 워처가 죽는 경우는 inotify 글을 보면 됩니다. 도커가 거절될 때는 이미지 빌드 로그보다 앞줄의 socket 문장을 먼저 읽으면 됩니다.
국내 VPS를 처음 열면 안내가 관리자 권한 예시만 보여 주는 경우가 많습니다. 그 다음 배포 스크립트는 일반 계정으로 돌면서 같은 줄에서 멈춥니다. 지금 터미널의 계정과 서비스가 쓰는 계정이 같은지부터 보세요. 설치는 관리자로 하고 실행은 다른 이름으로 하면 그룹이 설치한 쪽에만 남습니다. 사람 손으로 친 명령은 되는데 자동 실행만 거절되면 계정 이름이 다른 것입니다. 이미지 이름이나 태그를 고치기 전에 이 계정부터 맞추는 편이 빠릅니다. 그룹을 넣은 날 바로 배포가 실패하면, 서비스를 한 번 재시작해야 새 그룹이 프로세스에 실립니다.
소켓의 소유를 보기 전에, 지금 셸이 어느 이름인지를 먼저 적어둡니다. 안내를 그대로 복사해 관리자 이름에만 그룹을 넣고, 실제 배포는 다른 이름으로 하면 목록이 어긋납니다. 손으로 치는 계정과 자동으로 도는 계정이 둘 다 그룹에 있어야 같은 명령이 같이 통과합니다. 그룹을 넣은 직후 자동 실행만 실패하면 프로세스가 예전 자격으로 남아 있는 것이니, 그 서비스를 한 번 내렸다 올리면 새 자격이 적용됩니다. 저장소 주소나 이미지 이름을 의심하기 전에 이 두 이름을 맞추세요.
777은 해결이 아닙니다 | 소켓 모드를 모두에게 열면 데몬 재시작 때 되돌아가고, 그 전에도 같은 머신의 다른 사용자가 컨테이너로 호스트를 다룰 수 있습니다. 내 계정만 docker 그룹에 넣고 세션을 다시 여세요.
데몬은 살아 있고 소켓 권한만 없는 상태입니다. 현재 사용자를 docker 그룹에 usermod -aG로 넣은 뒤 로그아웃하거나 newgrp docker로 새 셸을 여세요. sudo가 되는 것은 root라서 소켓을 열 수 있다는 뜻입니다.
usermod를 했는데 groups에 docker가 없습니다.
그룹 목록은 로그인 때 읽어 옵니다. 같은 터미널은 옛 목록을 유지합니다. 터미널을 완전히 닫고 다시 접속하거나 newgrp docker를 실행한 뒤 groups를 다시 보세요.
-a 없이 -G만 치면 무슨 일이 나나요?
-G만 쓰면 보조 그룹 목록을 그 인자로 바꿀 수 있습니다. sudo나 wheel이 빠져 다음 관리 명령이 막힐 수 있습니다. 추가는 -aG로 적습니다.
맥북에서도 groupadd를 해야 하나요?
Docker Desktop을 쓰는 맥은 앱을 켜는 것으로 데몬이 붙습니다. groupadd와 usermod는 리눅스에 엔진을 직접 설치했을 때의 절차입니다. Is the docker daemon running이면 앱이 꺼진 쪽부터 보세요.
chmod 777로 소켓을 열어도 되나요?
문서 절차가 아니고, 데몬 재시작 때 모드가 돌아갑니다. 그 전에 같은 머신의 다른 사용자가 도커로 호스트를 다룰 수 있습니다. 내 계정만 그룹에 넣으세요.
hello-world는 되는데 내 이미지만 실패합니다.
소켓 권한은 이미 통과한 것입니다. 그 다음의 포트 충돌, 이미지 안의 바이너리, 빌드 로그를 봐야 합니다. permission denied 문장이 사라졌다면 그룹 문제는 끝난 상태입니다.
docker가 소켓에서 막히면 데몬이 꺼진 문장인지 권한 문장인지부터 보면 됩니다. 리눅스는 docker 그룹에 -aG로 넣고 세션을 다시 열고, 맥은 Desktop 앱을 켜면 됩니다. 소켓을 777로 열 필요는 없습니다. 관련 글: 알파인 엔진, 포트 점유, inotify.
