우분투에 Docker 설치하기 – 공식 방법으로 따라 하기

우분투에 Docker 설치하기 – 공식 방법으로 따라 하기

이제 본격적으로 내 홈서버에 Docker를 설치해보자.
Docker는 공식 문서에서도 설치 방법이 잘 정리되어 있고,
APT(우분투의 패키지 관리자)를 사용하면 쉽게 설치할 수 있다.

이 글에서는 2025년 기준 Ubuntu Server에서 Docker 설치하는 최신 방법을
비전문가도 따라 할 수 있도록 단계별로 설명한다.

📋 설치 전 체크리스트

설치를 시작하기 전에 확인해야 할 사항들:

시스템 요구사항

지원 Ubuntu 버전 확인

# 현재 우분투 버전 확인
lsb_release -a

지원 버전:

• Ubuntu 24.04 LTS (Noble)
• Ubuntu 22.04 LTS (Jammy) ⭐ 권장
• Ubuntu 20.04 LTS (Focal)

🔍 설치 방법 3가지 비교

Docker를 설치하는 방법은 크게 3가지가 있다:

결론: 공식 저장소 방식 추천! (이 글에서 다룰 방법)

🚀 Method 1: 공식 저장소로 설치 (권장)

📌 Step 0: 설치 전 시스템 업데이트

먼저 기본 시스템을 최신 상태로 만들어주자.

# 패키지 목록 업데이트
sudo apt update

# 설치된 패키지 업그레이드
sudo apt upgrade -y

# 재부팅 (커널 업데이트 시 필요)
sudo reboot

소요 시간: 5~10분

Step 1: 기존 Docker 제거 (있을 경우)

이전에 비공식 방법으로 설치한 Docker가 있다면 제거해야 한다.

# 기존 Docker 확인
docker --version

# 기존 Docker 및 관련 패키지 제거
sudo apt remove docker docker-engine docker.io containerd runc -y

# 설정 파일까지 완전 제거
sudo apt purge docker-ce docker-ce-cli containerd.io -y

# 의존성 정리
sudo apt autoremove -y

주의: 기존 컨테이너와 이미지는 /var/lib/docker에 남아있으므로 백업 필요 시 백업 후 진행

Step 2: 필수 의존성 패키지 설치

# HTTPS를 통한 저장소 접근 및 GPG 키 관리를 위한 패키지
sudo apt install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

각 패키지 역할:

• ca-certificates: HTTPS 연결에 필요한 인증서
• curl: 파일 다운로드 도구
• gnupg: GPG 키 관리 (패키지 서명 검증용)
• lsb-release: Ubuntu 버전 정보 확인

Step 3: Docker 공식 GPG 키 추가

Docker 패키지가 공식적으로 서명된 것인지 확인하기 위한 키를 추가한다.

# GPG 키 저장 디렉토리 생성
sudo install -m 0755 -d /etc/apt/keyrings

# Docker 공식 GPG 키 다운로드 및 등록
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

💡 GPG 키란?

패키지가 Docker 공식에서 배포한 것인지 확인하는 디지털 서명.
이 키가 없으면 악의적인 패키지가 설치될 수 있으므로 보안상 필수.

Step 4: Docker 공식 저장소 추가

# Docker 공식 APT 저장소 추가
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

명령어 설명:

• $(dpkg --print-architecture): 현재 시스템 아키텍처 (amd64, arm64 등)
• $(lsb_release -cs): Ubuntu 코드명 (jammy, focal 등)
• stable: 안정 버전 채널 (test, nightly도 있지만 비추천)

Step 5: 패키지 목록 업데이트

# 새로 추가된 Docker 저장소 반영
sudo apt update

이제 Docker 패키지가 설치 가능한 목록에 추가되었다.

Step 6: Docker 엔진 설치

# Docker 엔진 및 관련 구성요소 설치
sudo apt install -y \
    docker-ce \
    docker-ce-cli \
    containerd.io \
    docker-buildx-plugin \
    docker-compose-plugin

설치되는 구성요소:

소요 시간: 3~5분

Step 7: Docker 서비스 시작 및 확인

# Docker 서비스 상태 확인
sudo systemctl status docker

# 만약 실행 중이 아니라면 시작
sudo systemctl start docker

# 부팅 시 자동 시작 설정
sudo systemctl enable docker

정상 출력 예시:

● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2025-11-03 10:30:15 KST; 2min ago
       Docs: https://docs.docker.com
   Main PID: 12345 (dockerd)
      Tasks: 8
     Memory: 45.2M
        CPU: 250ms
     CGroup: /system.slice/docker.service
             └─12345 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

✅ “active (running)” 상태면 설치 성공!

Step 8: Docker 버전 확인

# Docker 버전 확인
docker --version

# 상세 정보 확인
docker version

# Docker Compose 버전 확인
docker compose version

출력 예시:

Docker version 24.0.7, build afdd53b
Docker Compose version v2.23.0

Step 9: sudo 없이 Docker 사용하기 (권장)

기본적으로 Docker 명령어는 sudo 권한이 필요하다.
매번 sudo를 입력하는 게 번거롭다면, 현재 사용자를 Docker 그룹에 추가하자.

# 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# 그룹 변경 즉시 적용 (재로그인 대신)
newgrp docker

# 확인
groups

출력에 “docker”가 포함되어 있으면 성공!

⚠️ 보안 주의사항:

docker 그룹에 속한 사용자는 사실상 루트 권한을 가지는 것과 같습니다.
신뢰할 수 있는 사용자만 추가하세요.

Step 10: Hello World 테스트

Docker가 정상 작동하는지 확인해보자.

# Hello World 컨테이너 실행
docker run hello-world

정상 출력:

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
719385e32844: Pull complete 
Digest: sha256:...
Status: Downloaded newer image for hello-world:latest

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

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image.
 4. The Docker daemon streamed that output to the Docker client.

✅ 이 메시지가 보이면 설치 완료!

⚙️ Method 2: Snap으로 간편 설치 (대안)

복잡한 과정이 부담된다면 Snap으로 설치할 수도 있다.
단, 공식 저장소 방식보다 제약이 있을 수 있다.

# Snap으로 Docker 설치
sudo snap install docker

# 확인
docker --version

Snap 방식의 단점:

• 일부 기능 제한 (특히 네트워크 관련)
• docker-compose가 별도 설치 필요
• 파일 접근 권한 제약

💡 권장: 공식 저장소 방식 사용

🔧 설치 후 필수 설정

1. Docker 데이터 디렉토리 확인

# Docker가 데이터를 저장하는 위치
docker info | grep "Docker Root Dir"

기본 위치: /var/lib/docker

저장공간이 부족하면 이 디렉토리를 다른 곳으로 옮길 수 있다.

2. Docker 로그 설정 (로그 파일 크기 제한)

Docker 컨테이너는 기본적으로 로그를 무제한 저장하므로,
디스크가 꽉 차는 것을 방지하기 위해 로그 크기를 제한해야 한다.

# Docker 데몬 설정 파일 생성/편집
sudo nano /etc/docker/daemon.json

아래 내용 추가:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

의미:

• 각 컨테이너 로그 파일 최대 10MB
• 최대 3개 파일 유지 (총 30MB)

# 저장 후 Docker 재시작
sudo systemctl restart docker

# 확인
docker info | grep "Logging Driver"

3. Docker Compose 실행 권한 확인

# Docker Compose V2 (플러그인 방식)
docker compose version

# 만약 명령어가 없다면 재설치
sudo apt install docker-compose-plugin -y

💡 참고: 예전 docker-compose (하이픈)는 V1이고,
새로운 docker compose (띄어쓰기)는 V2입니다. V2 사용 권장!

🧪 설치 확인 – 실전 테스트

테스트 1: Nginx 웹서버 실행

# Nginx 컨테이너 실행
docker run -d -p 8080:80 --name test-nginx nginx

# 실행 확인
docker ps

# 브라우저 또는 curl로 확인
curl http://localhost:8080

성공 시: “Welcome to nginx!” HTML 출력

# 테스트 후 삭제
docker stop test-nginx
docker rm test-nginx

테스트 2: Docker Compose 테스트

# 테스트 디렉토리 생성
mkdir ~/docker-test && cd ~/docker-test

# docker-compose.yml 파일 생성
cat > docker-compose.yml << EOF
version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
EOF

# 실행
docker compose up -d

# 확인
docker compose ps
curl http://localhost:8080

# 정리
docker compose down
cd ~ && rm -rf docker-test

✅ 모두 정상 작동하면 설치 완벽!

🚨 설치 중 자주 발생하는 문제 해결

문제 1: GPG 키 다운로드 실패

증상:

curl: (7) Failed to connect to download.docker.com

해결:

• ✅ 인터넷 연결 확인: ping 8.8.8.8
• ✅ DNS 문제: sudo nano /etc/resolv.conf → nameserver 8.8.8.8 추가
• ✅ 방화벽 확인: sudo ufw status

문제 2: "Permission denied" 에러

증상:

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

해결:

# 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# 재로그인 또는
newgrp docker

문제 3: Docker 서비스가 시작 안 됨

증상:

Job for docker.service failed

해결:

# 로그 확인
sudo journalctl -xeu docker.service

# containerd 재시작
sudo systemctl restart containerd
sudo systemctl restart docker

# 여전히 안 되면 재설치
sudo apt purge docker-ce docker-ce-cli containerd.io -y
# 위의 설치 과정 다시 진행

문제 4: 기존 Docker와 충돌

증상:

docker: command not found (but docker.io is installed)

해결:

# Ubuntu 기본 저장소의 docker.io 제거
sudo apt remove docker.io -y

# 공식 Docker 재설치
sudo apt install docker-ce docker-ce-cli -y

문제 5: "Cannot connect to Docker daemon"

해결:

# Docker 소켓 권한 확인
ls -l /var/run/docker.sock

# 권한 수정 (임시)
sudo chmod 666 /var/run/docker.sock

# 근본 해결: 사용자 그룹 추가
sudo usermod -aG docker $USER
newgrp docker

🧹 Docker 완전 제거 방법

나중에 Docker를 완전히 제거하고 싶다면:

# Docker 패키지 제거
sudo apt purge docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin -y

# 설정 파일 및 데이터 삭제
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
sudo rm -rf /etc/docker

# 저장소 제거
sudo rm /etc/apt/sources.list.d/docker.list
sudo rm /etc/apt/keyrings/docker.gpg

# 의존성 정리
sudo apt autoremove -y
sudo apt autoclean

# 확인
docker --version  # command not found 출력되면 완전 제거됨

📝 정리하며

이번 글에서는 Docker를 우분투 서버에 공식적으로 설치하는 방법을 정리했다.

핵심 요약

• 공식 저장소 방식이 가장 안정적이고 권장됨
• 10단계 과정: 업데이트 → 의존성 → GPG 키 → 저장소 → 설치 → 확인
• sudo 없이 사용하려면 사용자를 docker 그룹에 추가
• hello-world 및 Nginx 테스트로 정상 동작 확인
• 로그 크기 제한 설정으로 디스크 보호

설치 후 다음 단계

1. ✅ Docker 설치 완료
2. → Docker Compose로 워드프레스 설치 (다음 글)
3. → 도메인 연결 및 HTTPS 설정
4. → 백업 자동화

다음 글에서는 Docker Compose를 사용해서 워드프레스와 MySQL을 한 번에 설치하고,
실제로 접속 가능한 웹사이트를 만드는 실습을 진행한다.

이제 정말 서버를 '운영'하기 시작하는 단계다. 🚀