Docker Engine 설치

핵심 요약

Nginx, Node.js, MySQL, Redis 등의 프로그램을 Ubuntu에 각각 직접 설치하지 않고, 서로 분리된 컨테이너로 간편하고 동일하게 실행·관리하기 위해 Docker Engine을 설치합니다.

이 문서는 같은 네트워크에 있는 Windows 관리 PC에서 VS Code로 Linux 서버에 SSH 접속한 후, Linux 서버에 Docker Engine을 설치하고 기본 작동과 사용자 권한을 확인하는 과정을 설명합니다.

Docker Engine과 project-dev-server의 관계

project-dev-server 안에서는 컨테이너가 격리된 환경에서 실행됩니다. 외부에서 컨테이너의 서비스에 접속하려면 필요한 컨테이너 포트를 호스트 포트에 게시해야 합니다.

설치 목적과 예시 환경

아래 예시 환경을 사용하겠습니다.

실제 작업에서는 192.168.1.231을 자신의 Linux 서버 IP 주소로 바꾸어야 합니다.

—

1. 전체 연결 구조

Windows PC
   │
   │ VS Code Remote - SSH
   ▼
Linux 서버: 192.168.1.231
   │
   │ Docker Engine
   ▼
Nginx 컨테이너
   │
   │ Linux 서버의 8080번 포트로 공개
   ▼
Windows 웹 브라우저
http://192.168.1.231:8080

VS Code는 Windows에서 실행되지만, VS Code의 SSH 원격 터미널에서 입력하는 Linux 명령은 Windows가 아니라 Linux 서버에서 실행됩니다.

VS Code의 Remote – SSH 확장은 SSH 서버가 실행 중인 원격 컴퓨터에 연결하여 원격 파일과 터미널을 로컬 VS Code처럼 사용할 수 있게 합니다.

—

2. 시작하기 전에

다음 조건을 먼저 확인합니다.

• 지원되는 64비트 Ubuntu Server가 설치되어 있음
• 서버가 인터넷에 연결되어 있음
• sudo 명령을 실행할 수 있는 사용자 계정이 있음
• Windows 관리 PC에서 서버로 SSH 접속할 수 있음
• VS Code에서 project-dev-server에 연결하고 원격 터미널을 열 수 있음

네트워크와 SSH 접속을 준비하는 방법은 prepare-project-dev-server-on-local-network-ko에서, VS Code의 Remote – SSH 설정과 원격 터미널 사용법은 VS Code 환경에서 설명합니다.

터미널 프롬프트가 다음처럼 표시되면 이후 명령은 Linux 서버에서 실행됩니다.

apple2ne1@project-dev-server:~$

—

3. 검증 환경

이 문서는 다음 환경에서 Docker Engine 설치와 기본 작동을 확인한 기록을 기준으로 작성했습니다.

Docker 지원 여부를 확인하려면 다음 명령으로 운영체제 버전과 아키텍처를 확인한 뒤 Docker 공식 문서의 현재 지원 범위와 비교합니다.

lsb_release -a

uname -m

dpkg --print-architecture

—

4. 기존 Docker 관련 패키지 확인 및 제거

새로운 project-dev-server를 구축한 경우에는 필요하지 않을 수 있지만, Docker를 설치한 적이 있다면 Docker 공식 저장소를 이용하기 전에 충돌할 수 있는 기존 패키지를 제거합니다. Docker는 Ubuntu에서 공식 APT 저장소를 설정한 뒤 Docker Engine을 설치하는 방식을 권장합니다.

터미널 화면을 보기 좋게 확장한 후 다음 명령을 실행합니다.

이 명령은 Ubuntu 터미널에 전체를 한꺼번에 붙여 넣고 Enter를 누르면 됩니다. VS Code에서는 Ctrl+C와 Ctrl+V를 사용하여 복사하고 붙여 넣을 수 있습니다.

for pkg in docker.io docker-doc docker-compose docker-compose-v2 docker-buildx podman-docker containerd runc; do
    sudo apt-get remove -y "$pkg"
done

아래에 보이는 한 줄로 실행해도 됩니다.

for pkg in docker.io docker-doc docker-compose docker-compose-v2 docker-buildx podman-docker containerd runc; do sudo apt-get remove -y "$pkg"; done

명령의 의미

지정된 패키지를 하나씩 확인하며 제거하는 반복문입니다.

• for pkg in ... : 패키지 이름을 하나씩 pkg에 넣습니다.
• do ... done : 각 패키지마다 내부 명령을 실행합니다.
• sudo apt-get remove : 해당 패키지를 제거합니다.
• -y : 확인 질문에 자동으로 Yes라고 답합니다.
• "$pkg" : 현재 처리 중인 패키지 이름입니다.

예를 들어 내부적으로 다음 명령들을 차례로 실행합니다.

sudo apt-get remove -y docker.io
sudo apt-get remove -y docker-doc
sudo apt-get remove -y docker-compose

나머지 패키지도 같은 방식으로 처리합니다.

일부 패키지가 설치되어 있지 않으면 다음과 비슷한 메시지가 나올 수 있지만 오류가 아닙니다.

Package 'docker-doc' is not installed, so not removed

이 명령은 Ubuntu 저장소에서 설치했을 가능성이 있는 기존 또는 충돌 가능한 Docker 관련 패키지를 정리한 후 공식 Docker를 설치할 때 주로 사용합니다. 기존 Docker 컨테이너와 이미지 데이터가 중요하다면 먼저 백업하는 것이 안전합니다.

—

5. Docker 공식 저장소 등록

5.1 패키지 목록 업데이트

APT 패키지는 Ubuntu에서 프로그램을 쉽게 설치하고 관리할 수 있도록 묶어 놓은 소프트웨어 설치 꾸러미입니다. 먼저 APT를 이용하여 저장소의 패키지 목록을 업데이트합니다.

sudo apt update

APT의 역할

APT는 Advanced Package Tool의 약자로 다음 작업을 담당합니다.

• 프로그램 검색과 설치
• 프로그램 업데이트
• 프로그램 삭제
• 필요한 의존성 패키지 자동 설치
• 패키지 간 충돌 확인
• 설정된 저장소에서 패키지 내려받기

5.2 인증서 모음과 curl 설치

ca-certificates는 HTTPS로 Docker의 APT 저장소에 연결할 때 서버 인증서를 검증하는 데 사용합니다. 이 단계에서 APT는 Docker 이미지가 아니라 저장소 메타데이터와 설치 패키지를 가져옵니다.

sudo apt install -y ca-certificates curl

• ca-certificates: HTTPS 인증서 확인에 사용
• curl: 인터넷에서 파일을 가져오는 명령

5.3 Docker 공식 GPG 키 저장 폴더 생성

Docker 공식 서명 키를 저장할 폴더를 만듭니다.

sudo install -m 0755 -d /etc/apt/keyrings

5.4 Docker 공식 GPG 키 내려받기

이 키는 내려받은 Docker 패키지가 다음 조건을 충족하는지 확인하는 데 사용됩니다.

• Docker 공식 저장소에서 제공된 것인지
• 전송 중 변조되지 않았는지

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

키 파일을 모든 사용자가 읽을 수 있도록 설정합니다.

sudo chmod a+r /etc/apt/keyrings/docker.asc

5.5 Docker 저장소 추가

Docker 저장소는 Docker Engine을 설치하고 업데이트하는 데 필요한 패키지를 보관하고 배포하는 인터넷 서버입니다.

Ubuntu가 Docker 프로그램을 내려받는 공식 공급처라고 이해하면 됩니다.

Ubuntu 서버
→ Docker 공식 저장소에 접속
→ Docker 패키지 내려받기
→ Docker Engine 설치

아래 명령을 그대로 한 번에 실행합니다.

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

저장소 정보를 다시 읽습니다.

sudo apt update

위 설치 흐름은 Docker가 제공하는 Ubuntu용 공식 Docker Engine 설치 절차를 기준으로 합니다.

—

6. Docker Engine 설치

다음 패키지를 설치합니다.

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

각 패키지의 역할은 다음과 같습니다.

Docker Engine에서는 Docker 데몬이 이미지, 컨테이너, 네트워크, 볼륨 등의 Docker 객체를 생성하고 관리합니다.

—

Docker 설치 시 오류가 발생했을 때

아래와 같은 오류는 저장소가 올바르게 등록되지 않아 패키지를 찾지 못했을 때 주로 나타납니다.

저장소 설정 파일이 있는지 확인합니다.

ls -l /etc/apt/sources.list.d/docker.sources

다음 메시지가 나오면 저장소가 등록되지 않은 것이므로 5. Docker 공식 저장소 등록부터 다시 진행합니다.

No such file or directory

—

7. Docker 서비스 상태 확인

다음 명령을 실행합니다.

sudo systemctl status docker

정상 상태에서는 다음 표시가 나옵니다.

Active: active (running)

상태 화면에서 빠져나오려면 다음 키를 누릅니다.

q

간단하게 확인하려면 다음 명령도 사용할 수 있습니다.

systemctl is-active docker

정상 결과:

active

Docker가 실행되지 않는다면 다음 명령을 실행합니다.

sudo systemctl start docker

Ubuntu와 Debian에서는 Docker 서비스가 기본적으로 부팅 시 시작하도록 설정됩니다. 다음 명령으로 활성화 여부를 먼저 확인합니다.

systemctl is-enabled docker

정상 예시:

enabled

결과가 disabled라면 Docker와 containerd 서비스를 활성화합니다.

sudo systemctl enable docker.service
sudo systemctl enable containerd.service

—

8. Docker 설치 버전 확인

sudo docker --version

Docker version 29.6.2, build dfc4efb

Docker Compose도 확인합니다.

sudo docker compose version

Docker Compose version v5.3.1

—

9. Docker 기본 작동 테스트

Docker 공식 테스트 이미지를 실행합니다.

sudo docker run hello-world

sudo docker run hello-world: `hello-world` 컨테이너 실행
→ Docker 데몬에 연결
→ 로컬 서버에 `hello-world` 이미지가 없으면 이미지 내려받기
→ 내려받은 `hello-world` 이미지로 컨테이너 생성
→ 생성한 컨테이너 내부의 코드 실행
→ 터미널에 `Hello from Docker!` 메시지 출력

처음 실행하면 서버에 이미지가 없으므로 Docker Hub에서 이미지를 내려받습니다.

정상적으로 실행되면 다음 문구가 포함됩니다.

Hello from Docker!

이 결과가 나오면 다음 과정이 모두 정상이라는 의미입니다.

• Docker CLI가 Docker 데몬과 통신함
• Docker Hub에서 이미지를 내려받음
• 이미지로 컨테이너를 생성하고 실행함
• 컨테이너의 출력이 터미널에 전달됨

—

10. sudo 없이 Docker 사용하기와 권한 오류 해결

현재 상태에서는 Docker 명령 앞에 sudo를 붙여야 합니다.

sudo 없이 Docker 명령을 실행할 때 다음과 같은 Docker 데몬 소켓 권한 오류가 발생할 수 있습니다.

permission denied while trying to connect to the Docker daemon socket

sudo docker ps

현재 사용자를 docker 그룹에 추가하면 sudo 없이 사용할 수 있습니다.

sudo usermod -aG docker apple2ne1

Docker 공식 문서도 Linux에서 Docker를 일반 사용자로 실행하려면 사용자를 docker 그룹에 추가하는 방법을 안내합니다. 다만 docker 그룹은 사실상 높은 시스템 권한을 제공하므로 신뢰할 수 있는 사용자만 추가해야 합니다.

그룹 변경 사항은 현재 로그인 세션에 즉시 적용되지 않을 수 있습니다.

실제 계정 정보에 기록된 그룹 확인

getent group docker

docker:x:983:apple2ne1

결과를 보면 apple2ne1 사용자는 docker 그룹에 정상적으로 추가되었습니다. 하지만 현재 groups 결과에는 아직 docker가 없습니다. 다음 중 한 가지 방법을 사용합니다.

방법 1: 현재 터미널에서 바로 적용

newgrp docker

groups

결과를 보면 현재 사용자 apple2ne1이 docker 그룹에 포함되어 있습니다.

방법 2: 로그아웃한 뒤 다시 로그인

계정 설정에는 아래 명령으로 등록을 확인했지만, 현재 로그인 세션에는 아직 새 권한이 반영되지 않은 상태입니다.

getent group docker

docker:x:983:apple2ne1

VS Code의 모든 원격 터미널에서 로그아웃한 뒤 원격 연결을 종료하고 다시 연결합니다. 다시 로그인하면 사용자의 그룹 정보가 새로 평가됩니다.

그룹 권한이 계속 반영되지 않는 일부 가상 머신이나 원격 개발 환경에서는 마지막 방법으로 서버를 재시작할 수 있습니다.

sudo reboot

그런 다음 Linux 서버에 다시 연결합니다.

재접속 후 확인합니다.

groups

결과에 docker가 포함되어야 합니다.

apple2ne1 adm cdrom sudo dip plugdev users lxd docker

이제 다음 명령이 sudo 없이 실행되어야 합니다.

docker ps

권한 오류가 발생한다면 이번 작업에서는 계속 다음처럼 sudo를 붙여도 됩니다.

sudo docker ps

—

다음 글

Docker Nginx 컨테이너

다음 글에서 다룰 내용:

• nginx:alpine 이미지로 nginx-web 컨테이너를 백그라운드에서 실행하고 재시작 정책을 설정합니다.
• -p 8080:80 포트 게시를 사용해 호스트의 8080번 포트를 Nginx 컨테이너의 80번 포트에 연결합니다.
• docker ps, curl과 Windows 웹 브라우저를 사용해 컨테이너 상태와 Nginx 접속 결과를 확인합니다.
• Docker의 포트 공개 범위와 UFW 상태를 점검하고, 같은 네트워크에서 접속할 수 있는 조건을 확인합니다.
• Nginx 컨테이너의 로그를 확인하고 중지, 시작, 재시작과 삭제 명령을 실습합니다.
• 사용자 HTML 파일이 있는 호스트 폴더를 Nginx 컨테이너에 바인드 마운트하여 웹페이지를 표시합니다.
• 컨테이너 이름 중복, 포트 충돌과 Connection refused 등 자주 발생하는 오류의 확인 순서를 익힙니다.

참고 자료 및 출처

• Install Docker Engine on Ubuntu
• 지원되는 Ubuntu 환경, 충돌 패키지 제거, 공식 APT 저장소 등록, Docker Engine 설치와 hello-world 실행 절차를 확인했습니다.
• 확인 날짜: 2026-08-07
• Linux post-installation steps for Docker Engine
• docker 그룹의 권한 위험, 사용자 그룹 추가, 재로그인과 newgrp docker 적용 방법을 확인했습니다.
• 확인 날짜: 2026-08-07

—

관련 문서

• prepare-project-dev-server-on-local-network-ko
• VS Code 환경
• Docker Nginx Container
• Docker Nginx Compose