Ubuntu에 Docker를 설치하는 방법: 완전 초보자 친화 가이드 (공식 방법)

1. 소개

Ubuntu에 개발 환경을 구축할 때 “당장은 Docker만 설치하자”는 상황이 점점 더 흔해지고 있습니다. 웹 애플리케이션, 배치 처리, 테스트 데이터베이스, 테스트 미들웨어… 이러한 것들을 매번 수동으로 설치한다면 환경 설정만으로도 엄청난 시간과 노력이 소모됩니다.

이때 컨테이너 가상화 기술 Docker가 매우 유용하게 활용됩니다. Docker를 사용하면 애플리케이션 자체뿐만 아니라 필요한 라이브러리와 설정까지 모두 “이미지” 형태로 관리할 수 있습니다. Ubuntu에 Docker가 설치되면 다음을 손쉽게 수행할 수 있습니다:

• 몇 분 안에 새로운 개발 환경을 시작
• 모든 팀원이 동일한 환경에서 동작을 재현하도록 보장
• 로컬에서 프로덕션과 유사한 환경을 손쉽게 재현

이러한 이점은 최소한의 노력으로 누릴 수 있습니다.

반면 Docker를 처음 사용하는 사람들에게는 다음과 같은 흔한 함정이 존재합니다:

• 실제로 올바른 설치 절차가 무엇인지 모름
• Ubuntu 기본 저장소와 Docker 공식 저장소의 차이를 이해하지 못함
• sudo 사용 시점을 혼동해 권한 오류가 발생함

“ubuntu install docker”와 같은 키워드로 검색하면 긴 명령어 시퀀스를 나열한 많은 글을 찾을 수 있지만, 대부분 왜 그 단계가 필요한지 혹은 완전한 설치가 어떤 모습인지에 대한 설명이 부족합니다.

1-1. 이 글의 목표

이 글은 Ubuntu에 Docker를 설치하고자 하는 독자를 대상으로 하며, 다음 핵심 내용을 다룹니다:

• 현재 가장 일반적인 Ubuntu용 Docker 설치 절차
• 공식 저장소를 이용한 보다 관리하기 쉬운 설치 방법
• sudo 없이 docker 명령을 실행하는 방법
• 설치 후 검증 및 필수 기본 명령
• Docker Compose와 같은 자주 사용하는 도구 소개

단순히 명령어를 나열하는 것이 아니라 각 단계가 왜 필요한지를 설명함으로써, 향후 환경을 보다 쉽게 유지·관리할 수 있도록 돕습니다.

1-2. 대상 독자 및 전제 조건

이 글은 다음과 같은 독자를 위해 작성되었습니다:

• 기본적인 Ubuntu 조작(터미널 열기, apt 명령 사용 등)을 이해하고 있음
• 처음으로 Docker를 시도하는 개발자 또는 엔지니어 지망생
• 기존 테스트 환경을 컨테이너로 이전하려는 경우

고급 Linux 관리 지식은 필요하지 않습니다. 터미널에 명령을 입력하는 데 익숙하기만 하면 이 가이드를 따라갈 수 있습니다.

1-3. 글 구성 및 읽는 방법

이 글은 다음 순서로 진행됩니다:

• 전제 조건 확인
• 설치 방법(공식 저장소 / 스크립트 기반)
• 권한 설정 및 검증
• Docker Compose 설치
• 트러블슈팅 및 다음 단계

전체를 처음부터 끝까지 읽어도 되고, 이미 Docker가 설치된 경우에는 “권한 설정”이나 “Compose” 섹션만 집중해서 읽어도 됩니다.

2. 전제 조건 및 준비 작업

Docker 자체 설치는 비교적 간단하지만, Ubuntu 버전이나 기존 환경에 따라 사전에 확인해야 할 사항이 몇 가지 있습니다. 이 섹션에서는 원활한 설치를 위해 필요한 전제 조건과 준비 작업을 정리합니다.

2-1. 지원되는 Ubuntu 버전

Docker는 다양한 Ubuntu 버전에서 동작하지만, 다음 LTS 릴리스가 가장 일반적으로 사용됩니다:

• Ubuntu 22.04 LTS (권장)
• Ubuntu 20.04 LTS
• Ubuntu 24.04 LTS (최신)

LTS(Long Term Support) 릴리스는 장기적인 안정성을 제공하므로 Docker 기반 개발 환경을 유지하는 데 최적입니다.

Non‑LTS 릴리스(예: 23.10)도 사용할 수 있지만, 실무 환경에서는 일반적으로 LTS 버전을 선호합니다.

2-2. 사전 설치된 Docker 패키지

Ubuntu의 기본 저장소에는 docker.io라는 패키지가 포함되어 있습니다. 그러나 이는 Docker Inc.에서 제공하는 공식 Docker 패키지가 아니며, 업데이트가 뒤처지는 경향이 있습니다. 따라서 공식 저장소에서 Docker를 설치하는 것이 강력히 권장됩니다.

먼저, 필요에 따라 기존 Docker 관련 패키지가 있는지 확인하고 제거하십시오:

sudo apt remove docker docker.io containerd runc

메시지에 설치된 것이 없다고 표시되면 별도의 조치가 필요하지 않습니다.

2-3. APT 업데이트 및 필수 패키지 설치

Docker 공식 저장소 추가하기 전에 APT를 업데이트하고 필요한 도구를 설치하십시오:

sudo apt update
sudo apt install -y ca-certificates curl gnupg

이 도구들은 Docker의 GPG 키와 저장소를 안전하게 추가하기 위해 필요합니다.

2-4. 관리자 권한 확인 (sudo)

Docker 설치에는 sudo 권한이 필요합니다. 계정에 sudo 접근 권한이 없으면 관리자 계으로 전환하거나 권한을 요청하십시오.

다음 명령어로 sudo 접근 권한을 확인할 수 있습니다:

sudo -v

비밀번호 입력을 요구하고 명령이 성공하면 진행할 준비가 된 것입니다.

2-5. 네트워크 연결 확인

Docker를 설치하려면 외부 저장소에 접근할 수 있어야 하므로 활성 인터넷 연결이 필수입니다. 기업이나 프록시 환경에서는 접근 제한으로 인해 GPG 키를 가져오지 못할 수 있습니다.

이러한 경우 프록시 설정이나 허용 목록 구성을 위해 네트워크 관리자에게 문의하십시오.

2-6. 설치 방법 선택

Docker를 설치하는 주요 방법은 세 가지가 있습니다:

1. 공식 Docker 저장소를 통한 설치 (권장)
2. get.docker.com 설치 스크립트 사용 (빠르고 간편)
3. Docker .deb 패키지를 수동으로 다운로드 및 설치 (특수한 경우)

이 문서는 주로 공식 저장소 방식에 초점을 맞추고 있으며, 이는 가장 일반적이고 유지 관리가 가장 쉬운 방법입니다.

3. Docker 설치

이제 Ubuntu에 Docker를 설치해 보겠습니다. 여러 설치 방법이 존재하지만, 이 가이드는 공식 Docker 저장소 방식에 중점을 두고 있으며, 이는 프로덕션 환경에서 가장 신뢰할 수 있고 널리 사용되는 방법입니다.

이 방법을 사용하면 apt upgrade를 통해 안정적인 업그레이드가 가능하므로 장기 사용에 이상적입니다.

3-1. 공식 Docker 저장소 추가 (권장)

먼저 Docker에서 제공하는 공식 GPG 키를 등록하고 Docker 저장소를 APT에 추가합니다.
이 구성을 올바르게 하면 Ubuntu 기본 저장소에서 오래된 docker.io 패키지를 실수로 설치하는 일을 방지할 수 있습니다.

3-1-1. GPG 키 등록

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

• /etc/apt/keyrings/는 Ubuntu 22.04 이후 버전에서 권장되는 키 저장 위치입니다
• --dearmor는 키를 바이너리 형식으로 변환합니다

이 단계는 APT가 공식 Docker 저장소를 신뢰하도록 합니다.

3-1-2. 저장소 추가

다음으로 Docker 저장소를 APT의 소스 목록에 추가합니다.

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

핵심 포인트:

• $(. /etc/os-release && echo $VERSION_CODENAME)는 올바른 Ubuntu 코드네임(예: jammy 또는 focal)을 자동으로 삽입합니다
• 안정적인(stable) 저장소만 추가됩니다

3-1-3. 저장소 정보 업데이트

저장소를 추가한 후 APT 인덱스를 업데이트합니다.

sudo apt update

이 시점에서 docker-ce(Docker Engine)가 설치 가능한 패키지로 표시되어야 합니다.

3-2. Docker Engine 설치

이제 주요 Docker 패키지를 설치합니다.

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

패키지 역할:

• docker-ce : Docker 엔진 코어
• docker-ce-cli : Docker 명령줄 인터페이스
• containerd.io : Docker에서 사용하는 핵심 컨테이너 런타임
• docker-buildx-plugin : 다중 플랫폼 빌드와 같은 고급 빌드 기능
• docker-compose-plugin : Docker Compose V2 (docker compose 명령)

설치가 완료되면 Docker 데몬이 자동으로 시작됩니다.

3-3. 설치 확인

다음 명령으로 Docker 런타임 상태를 확인합니다:

sudo systemctl status docker

active (running) 이 표시되면 Docker가 정상적으로 동작하고 있는 것입니다.

상태 화면을 종료하려면 q 를 누르세요.

3-4. 선택 사항: 편의를 위한 스크립트 기반 설치

Docker는 올인원 설치 스크립트도 제공합니다.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

장점:

• 명령 수가 적고 빠르게 설정 가능
• 간단하거나 일시적인 환경에 적합

단점:

• 버전 관리가 어려움
• 운영 환경이나 장기 사용에서는 권장되지 않음

초보자에게는 편리하지만, 이 문서는 유지 보수를 중시하므로 공식 저장소 방식을 중심으로 설명합니다.

3-5. 최신 Ubuntu 릴리스에 대한 참고 사항 (예: 24.04)

주요 Ubuntu 릴리스 직후에는 Docker 공식 저장소가 아직 새 버전을 완전히 지원하지 않을 수 있습니다.
이 경우 다음 항목을 확인하세요:

• GPG 키 위치와 형식이 현재 사양과 일치하는지
• VERSION_CODENAME 이 공식적으로 지원되는지
• apt update 수행 시 서명 오류가 발생하지 않는지

지원이 지연될 경우, 임시 방편으로 get.docker.com 스크립트를 사용하는 것이 실용적일 수 있습니다.

4. 사용자 권한 및 sudo 없이 Docker 실행하기

Docker를 설치한 뒤 바로 docker 명령을 사용하고 싶을 수 있습니다. 그러나 기본적으로 모든 명령 앞에 sudo 를 붙여야 합니다.

이 동작은 보안상의 이유로 의도된 것이지만, 일상적인 개발이나 학습에는 불편합니다. 이를 해결하려면 사용자를 docker 그룹에 추가하면 sudo 없이 Docker 명령을 실행할 수 있습니다.

4-1. sudo 없이 실행하는 것이 중요한 이유

Ubuntu에서는 Docker 데몬(dockerd)이 루트 권한으로 실행됩니다.
따라서 docker 명령으로 컨테이너를 생성하거나 삭제하려면 일반적으로 루트 접근 권한이 필요합니다.

이를 처리하기 위해 docker 그룹이 존재합니다.

• 이 그룹에 속한 사용자는 Docker 데몬에 직접 접근할 수 있습니다
• docker run 과 같은 명령을 sudo 없이 실행 가능
• 개발 환경에서는 거의 필수적인 설정입니다

docker 그룹은 사실상 루트에 가까운 권한을 부여하므로, 공유 환경에서는 주의가 필요합니다.
(개인 데스크톱이나 WSL2에서는 보통 문제가 되지 않습니다.)

4-2. 현재 사용자에게 docker 그룹 추가하기

현재 로그인한 사용자를 docker 그룹에 추가합니다:

sudo usermod -aG docker $USER

-aG 옵션은 그룹에 추가한다는 의미이며, 사용자를 기존 그룹에 그대로 유지하면서 docker 그룹에 포함시킵니다.

4-3. 변경 사항 적용하기

그룹 멤버십 변경은 로그아웃 후 다시 로그인해야 적용됩니다.

즉시 적용하려면 다음 명령을 실행할 수도 있습니다:

newgrp docker

이 명령은 docker 그룹 권한이 적용된 새로운 셸 세션을 시작합니다.

4-4. sudo 없이 실행되는지 확인하기

이제 sudo 없이 Docker를 테스트합니다:

docker run hello-world

성공적인 출력 예시:

• Hello from Docker!
• 이미지가 다운로드되고 메시지가 표시됩니다

오류가 발생한다면 다음을 확인하세요:

• 그룹 멤버십을 변경한 뒤 로그아웃·로그인했는가?
• /usr/bin/docker 가 사용되고 있는가?
• Docker 데몬이 실행 중인지 (systemctl status docker) 확인

4-5. 보안 고려 사항 (중요)

docker 그룹은 사실상 루트와 동등한 강력한 권한을 제공합니다.

• 임의 파일 읽기
• 호스트 디렉터리를 컨테이너에 마운트
• 네트워크 작업 수행
• Docker 소켓을 통한 시스템 수준 제어

공유 시스템에서는 이 점을 충분히 인식하고 사용하시기 바랍니다.

이 내용은 개인 시스템에서는 허용될 수 있지만, 공유 서버에서는 사용자 관리가 매우 중요합니다.

이러한 경우 rootless Docker를 고려할 수 있으며, 이는 이후 섹션에서 다룹니다.

5. 시작 및 동작 검증

Docker 설치와 권한 설정이 완료되면, 다음 단계는 Docker가 정상적으로 동작하는지 확인하는 것입니다.
이 섹션에서는 Docker 서비스 상태를 확인하고 실제로 컨테이너를 실행하는 방법을 설명합니다.

5-1. Docker 데몬 상태 확인

먼저 Docker가 백그라운드에서 정상적으로 실행되고 있는지 확인합니다.

sudo systemctl status docker

주요 상태 지표:

• active (running) → 정상적으로 운영 중
• inactive → 실행 중이 아님 (수동으로 시작해야 함)
• failed → 설정 또는 의존성 오류

상태가 inactive 또는 failed인 경우, 다음 명령으로 Docker를 시작합니다:

sudo systemctl start docker

OS 부팅 시 Docker가 자동으로 시작되도록 하려면:

sudo systemctl enable docker

5-2. hello-world 컨테이너로 동작 검증

Docker 설치를 검증하는 가장 일반적인 방법은 공식 hello‑world 이미지를 실행하는 것입니다.

docker run hello-world

이 명령은 다음 작업을 수행합니다:

1. 로컬에 이미지가 없으면 Docker Hub에서 다운로드
2. 이미지로부터 컨테이너를 시작
3. 테스트 메시지를 표시하고 종료

성공하면 다음과 유사한 출력이 나타납니다:

Hello from Docker!
This message shows that your installation appears to be working correctly.

이 메시지가 표시되면 Docker가 설치되고 정상적으로 동작하고 있는 것입니다.

5-3. 기본 Docker 명령 사용해 보기

기본 동작이 확인되면, 자주 사용하는 Docker 명령들을 몇 가지 시도해 봅니다.

5-3-1. Docker 이미지 목록 보기

docker images

이 명령은 로컬에 다운로드된 이미지 목록을 표시합니다. hello-world가 나타나면 모든 것이 정상적으로 작동하고 있는 것입니다.

5-3-2. 실행 중인 컨테이너 확인

docker ps

이 명령은 현재 실행 중인 컨테이너를 나열합니다.
(hello-world 컨테이너는 즉시 종료되므로 보통은 나타나지 않습니다.)

중지된 컨테이너도 함께 표시하려면:

docker ps -a

5-3-3. 공식 이미지 예제 실행

간단한 Nginx 웹 서버를 실행해 보려면:

docker run -d -p 8080:80 nginx

• -d → 백그라운드에서 실행
• -p → 호스트 포트 8080을 컨테이너 포트 80에 매핑

브라우저에서 http://localhost:8080을 열면 기본 Nginx 페이지가 표시됩니다.

5-4. 컨테이너 중지 및 삭제

다음 명령으로 실행 중인 컨테이너를 중지할 수 있습니다:

docker stop <container-id>

컨테이너를 삭제하려면:

docker rm <container-id>

사용되지 않는 이미지를 삭제하려면:

docker rmi <image-id>

종속 관계는 컨테이너 → 이미지 → 볼륨 순으로 이루어지므로, 삭제 시 순서를 주의하세요.

5-5. 오류의 일반적인 원인

● 권한 오류

Got permission denied while trying to connect to the Docker daemon socket
→ 사용자가 docker 그룹에 추가되지 않음

● Docker 데몬이 실행 중이 아님

Cannot connect to the Docker daemon at unix:///var/run/docker.sock
→ systemctl start docker 로 Docker를 시작

● 이미지 다운로드를 방해하는 네트워크 문제

→ 프록시 설정, DNS 구성 또는 네트워크 제한을 확인

● 오래된 docker.io 패키지가 아직 설치되어 있음

→ 해당 패키지를 완전히 제거하고 공식 저장소에서 Docker를 재설치

6. Docker Compose 설치 및 사용

대규모 Docker 환경에서 작업할 때 필수적인 도구가 Docker Compose입니다.
현대 웹 애플리케이션은 데이터베이스, 캐시, 워커, 웹 서버 등 여러 구성 요소로 이루어지는 경우가 많습니다. docker run 명령으로 각각을 개별 관리하면 금방 비효율적이 됩니다.

Docker Compose를 사용하면 여러 컨테이너 구성을 하나의 파일에 정의하고 함께 관리할 수 있어, 실제 개발 현장에서 가장 많이 사용되는 도구 중 하나가 됩니다.

6-1. Docker Compose V2 설치 확인

공식 저장소에서 Docker를 설치하면 Docker Compose가 플러그인으로 자동 설치됩니다.

다음 명령으로 설치 여부를 확인하세요:

docker compose version

정상적으로 설치되었다면 다음과 유사한 출력이 표시됩니다:

Docker Compose version v2.x.x

docker: 'compose' is not a docker command와 같은 오류가 나타나면 플러그인을 수동으로 설치합니다:

sudo apt install docker-compose-plugin

6-2. Docker Compose의 장점

Docker Compose의 주요 장점은 다음과 같습니다:

• 다중 컨테이너를 통합 관리 (시작, 중지, 재시작)
• 코드로서의 설정 으로 재현 가능한 환경 보장
• 애플리케이션, API, 데이터베이스 설정을 손쉽게 공유
• docker compose up 하나만으로 개발 환경을 실행

이 덕분에 Docker Compose는 애플리케이션 개발에 거의 필수에 가깝습니다.

6-3. Compose 설정 파일의 기본 구조

Docker Compose는 docker-compose.yml(또는 compose.yaml) 파일을 사용해 서비스를 정의합니다.
가장 간단한 예시로 Nginx를 실행하는 설정을 만들어 보세요.

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

파일이 있는 디렉터리에서 다음 명령을 실행합니다:

docker compose up -d

Nginx가 백그라운드에서 시작됩니다. 브라우저에서 http://localhost:8080에 접속해 확인하세요.

6-4. 예시: 다중 컨테이너 설정 (웹 + 데이터베이스)

Compose의 진정한 힘은 여러 컨테이너를 동시에 관리할 때 드러납니다.
예를 들어 웹 애플리케이션과 MySQL을 함께 실행하려면 다음과 같이 설정합니다:

services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: example
    volumes:
      - db-data:/var/lib/mysql

volumes:
  db-data:

설명:

• depends_on 은 데이터베이스가 애플리케이션보다 먼저 시작되도록 보장
• volumes 는 데이터베이스 데이터를 영구 보관
• 하나의 YAML 파일 안에서 여러 서비스를 관리

개발 환경에서 매우 실용적인 패턴입니다.

6-5. 자주 사용하는 Docker Compose 명령어

다음 명령어들을 기억해 두면 유용합니다:

Compose를 사용하면 동일한 환경을 반복적으로 재현할 수 있어 팀 개발에 최적입니다.

6-6. 개발에서 Compose를 권장하는 사용 사례

• 한 번의 명령으로 로컬 환경 설정
• 프로덕션에 가까운 환경에서 테스트
• 데이터베이스, 캐시, 메시지 큐 등 복합 서비스 실행
• 볼륨을 이용한 데이터 영구화
• .env 환경 변수를 통한 설정 관리
• 복잡한 마이크로서비스 아키텍처 지원

Docker와 Compose에 익숙해지면 환경 설정 시간이 크게 단축되어 개발 효율이 크게 향상됩니다.

7. 보안 및 운영 고려사항

Docker는 매우 강력하고 편리한 도구이지만 “컨테이너화”된 것이 곧 “보안”을 의미하지는 않습니다.
Ubuntu에서 Docker를 일상적으로 사용할 때 알아두어야 할 중요한 보안 및 운영 포인트가 몇 가지 있습니다.

이 섹션에서는 초보자도 이해하기 쉬운 방식으로 Docker를 안전하고 안정적으로 운영하기 위한 필수 지식을 정리합니다.

7-1. docker 그룹은 “실질적인 루트” 권한을 가짐

앞서 설정한 docker 그룹은 실제로 매우 강력한 권한을 부여합니다.
docker 그룹에 속한 사용자는 Docker 소켓을 통해 호스트 OS를 조작할 수 있으며, 이는 사실상 루트 수준의 접근 권한과 동일합니다.

● 주의해야 할 핵심 포인트

• 공유 서버에 임의의 사용자를 docker 그룹에 추가하지 말 것
• “sudo 없이 사용 가능”이라는 편리함만 보고 위험성을 간과하지 말 것
• 보안 정책이 엄격한 조직에서는 관리자 승인이 필요할 수 있음

이 문제는 개인 Ubuntu 머신이나 개발용 PC에서는 거의 발생하지 않지만, 운영 서버에서는 신중한 판단이 필요합니다.

7-2. Rootless Docker 고려하기 (고급 옵션)

Docker는 rootless mode 라는 기능을 제공하며,
Docker 데몬을 루트가 아닌 일반 사용자 계정으로 실행할 수 있게 합니다.

장점:

• 호스트 OS 권한 위험을 크게 감소시킴
• 보안 요구사항이 엄격한 환경에서 Docker 사용을 보다 안전하게 함

단점:

• 일부 네트워킹 기능이 제한됨
• 초보자에게는 설정이 더 복잡함
• 동작이 표준 Docker와 다를 수 있음

Rootless mode는 대부분의 개발 사용 사례에 필수는 아니지만, 기업 환경이나 규정 준수 중심의 환경에서는 유용한 옵션이 될 수 있습니다.

7-3. 사용되지 않는 이미지와 컨테이너 정리하기

시간이 지나면서 Docker는 눈치채지 못한 채 많은 디스크 공간을 차지할 수 있습니다.
사용되지 않는 컨테이너, 이미지, 볼륨이 쌓여 100GB를 쉽게 초과할 수 있습니다.

● 사용되지 않는 리소스를 제거하는 명령어

사용되지 않는 이미지 제거

docker image prune

컨테이너와 네트워크를 함께 제거

docker system prune

강제 정리 (주의해서 사용)

docker system prune -a

-a 옵션은 모든 사용되지 않은 이미지를 제거하므로 신중히 사용하십시오.

7-4. 프로덕션에서 “latest” 태그 사용 금지

nginx:latest 와 같은 태그는 개발 단계에서는 편리하지만, 프로덕션에서는 권장되지 않습니다.

이유:

• latest 뒤에 있는 정확한 버전이 보장되지 않음
• 예상치 못한 업데이트가 런타임 오류를 일으킬 수 있음
• 재현 가능성이 떨어져 안정적인 배포가 어려워짐

권장 방법: 버전을 명시적으로 고정하기

예시:

image: nginx:1.25

명시적 버전 관리가 프로덕션 환경의 기본 규칙입니다.

7-5. Dockerfile에서 공식 베이스 이미지 사용하기

Dockerfile을 만들 때는 다음 지침을 따르세요:

• 공식 이미지(라이브러리 이미지)를 우선 사용
• 알 수 없거나 신뢰할 수 없는 작성자가 만든 이미지는 피함
• Alpine과 같은 경량 OS 이미지를 사용할 경우, 취약점 지원 상태를 확인

신뢰할 수 없는 이미지는 악성코드를 포함할 수 있습니다.
개발 환경에서도 가능한 한 사용을 피하십시오.

7-6. 네트워크 및 포트 노출에 주의하기

컨테이너가 호스트 OS에 포트를 노출하면, 시스템 외부에서 접근이 가능해질 수 있습니다.

예방 조치:

• 불필요한 -p 80:80 매핑을 피함
• 로컬에서만 사용할 경우 -p 127.0.0.1:8080:80 와 같이 localhost에 바인딩
• UFW와 같은 방화벽 설정과 결합
• 프로덕션에서는 보안을 강화하기 위해 Nginx와 같은 리버스 프록시 사용

포트 관리는 VPS나 클라우드 기반 Ubuntu 서버에서 특히 중요합니다.

7-7. 장애 발생 시 로그 관리

Docker 로그는 다음 명령어로 확인할 수 있습니다:

docker logs <container-name>

대량의 로그는 디스크 공간을 빠르게 소모하므로, 로그 드라이버와 로그 회전 설정을 고려하십시오.

8. 일반적인 문제와 트러블슈팅

Docker는 강력한 도구이지만, Ubuntu 환경에서는 환경 차이나 설정 오류로 인해 예상치 못한 오류가 발생할 수 있습니다.
이 섹션에서는 초급부터 중급 수준까지 흔히 겪는 문제와 해결책을 정리합니다.

8-1. Docker Daemon에 연결할 수 없음

● 오류 메시지

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

● 원인 및 해결책

1. Docker daemon이 실행 중이 아님 : sudo systemctl start docker
2. docker 그룹 변경이 적용되지 않음 : 로그아웃 후 다시 로그인하거나 newgrp docker 실행
3. /var/run/docker.sock 권한 문제 : 사용자가 docker 그룹에 포함되어 있는지 확인

8-2. Permission Denied 오류

● 전형적인 오류

Got permission denied while trying to connect to the Docker daemon socket

● 해결책

원인은 거의 항상 docker 그룹 설정이 누락된 경우입니다.

sudo usermod -aG docker $USER

그 후 로그아웃하고 다시 로그인하십시오.

8-3. APT 저장소를 추가할 때 발생하는 GPG 오류

● 오류 예시

NO_PUBKEY XXXXXXXX

또는

The following signatures couldn't be verified

● 원인 및 해결 방법

• GPG 키가 올바르게 등록되지 않음
• 네트워크 제한으로 curl이 실패함

키를 다시 등록하려면:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
 | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

그런 다음 sudo apt update를 다시 실행합니다.

8-4. 포트 바인딩 충돌

● 오류 예시

Bind for 0.0.0.0:80 failed: port is already allocated.

● 원인

• 호스트에서 다른 프로세스가 이미 해당 포트를 사용 중
• 다른 Docker 컨테이너가 동일한 포트를 사용 중

● 해결 방법

포트를 사용 중인 프로세스를 확인합니다:

sudo lsof -i -P -n | grep :80

실행 중인 컨테이너를 확인합니다:

docker ps

포트 매핑을 변경합니다:

-p 8080:80

8-5. 이미지 다운로드 실패

● 일반적인 원인

• 네트워크 제한 (기업 환경)
• DNS 설정 문제
• Docker Hub 접근 차단

● 해결 방법

• DNS 서버 변경 (예: 1.1.1.1 또는 8.8.8.8)
• 프록시 설정 확인
• 환경에 따라 VPN 사용

8-6. 디스크 공간 부족 오류

● 일반적인 메시지

no space left on device

● 해결 방법

사용하지 않는 리소스를 제거합니다:

docker system prune -a

이미지, 컨테이너 및 볼륨을 검토합니다:

docker images
docker ps -a
docker volume ls

디스크 공간 부족은 가장 흔한 Docker 운영 문제 중 하나입니다.