Docker 설치와 첫 컨테이너 실행
설치 전에 선택할 것: Desktop인가 Engine인가
Docker를 사용하려면 먼저 내 컴퓨터에 Docker 실행 환경을 준비해야 한다. 여기서 가장 먼저 만나는 선택지가 Docker Desktop과 Docker Engine이다.
Docker Desktop은 Windows, macOS, Linux에서 사용할 수 있는 통합 설치 프로그램이다. Docker Engine, Docker CLI, Docker Compose 같은 개발에 필요한 구성 요소를 함께 제공하므로 처음 배우는 독자에게 가장 편하다.1 GUI 화면도 제공하지만, 이 책에서는 실무에서 자주 쓰는 터미널 명령어를 중심으로 진행한다.
Docker Engine은 컨테이너를 실제로 실행하는 핵심 엔진이다. Linux 서버에서는 Docker Desktop 없이 Docker Engine만 직접 설치하는 경우가 많다. Docker 공식 문서는 Ubuntu, Debian, Fedora, RHEL 등 배포판별 설치 안내를 제공하며, Linux에서는 Desktop을 설치할 수도 있고 Engine만 설치할 수도 있다.2
처음 학습한다면 다음 기준으로 고르면 된다.
Windows: Docker Desktop을 권장한다. 설치 전에 가상화 기능이 켜져 있는지, WSL 2 환경을 사용할 수 있는지 확인한다.
macOS: Docker Desktop을 권장한다. Intel Mac과 Apple Silicon Mac의 설치 파일이 다를 수 있으므로 내 칩에 맞는 버전을 받는다.
Linux 개인 PC: Docker Desktop 또는 Docker Engine 중 선택할 수 있다. GUI 관리가 필요하면 Desktop, 서버와 비슷한 환경을 원하면 Engine이 좋다.
Linux 서버: 보통 Docker Engine을 설치한다. 서버에는 GUI가 필요 없는 경우가 많기 때문이다.
설치를 마친 뒤에는 터미널을 새로 열고 다음 명령으로 Docker가 동작하는지 확인한다.
docker version클라이언트와 서버 정보가 함께 보이면 Docker CLI가 Docker Engine과 통신하고 있다는 뜻이다. Docker Desktop을 설치했다면 Docker Desktop 애플리케이션이 실행 중이어야 이 명령이 정상적으로 동작한다. Docker Compose도 함께 확인해 보자.
docker compose version이 책에서는 최신 Docker CLI 기준인 docker compose 명령을 사용한다. 예전 자료에서 보이는 docker-compose는 과거에 많이 쓰이던 별도 명령이다.
Linux에서 permission denied 오류가 난다면 현재 사용자가 Docker 데몬에 접근할 권한이 없을 수 있다. 이때는 우선 다음처럼 sudo를 붙여 확인할 수 있다.
sudo docker version매번 sudo를 붙이지 않도록 Docker 그룹에 사용자를 추가할 수도 있지만, 이 권한은 시스템 관리 권한에 가깝다. 개인 개발 환경인지, 공용 서버인지에 따라 신중히 적용해야 한다. Docker 그룹에 사용자를 추가했다면 보통 로그아웃 후 다시 로그인하거나 새 터미널 세션을 열어야 권한이 반영된다.
AI 생성 이미지
첫 컨테이너 실행하기: hello-world
설치가 끝났다면 가장 작은 실습부터 시작하자. Docker에는 설치 확인용 이미지인 hello-world가 있다.
docker run hello-world처음 실행하면 화면에 여러 줄의 메시지가 출력된다. 핵심 흐름은 다음과 같다.
내 컴퓨터에
hello-world이미지가 있는지 확인한다.없으면 Docker Hub에서 이미지를 내려받는다.
이미지로 컨테이너를 만든다.
컨테이너 안의 프로그램을 실행한다.
메시지를 출력한 뒤 컨테이너가 종료된다.
여기서 중요한 명령은 docker run이다. docker run은 단순히 실행만 하는 명령이 아니다. 필요한 이미지가 없으면 내려받고, 그 이미지로 컨테이너를 만들고, 컨테이너를 시작한다. 즉 다음 세 단계를 한 번에 처리한다.
이미지 준비 → 컨테이너 생성 → 컨테이너 실행「컨테이너와 Docker의 기본 개념 이해하기」에서 살펴본 Docker의 기본 흐름이 실제 명령 하나로 이어지는 것이다.
이제 실행 중인 컨테이너 목록을 확인해 보자.
docker ps아마 아무것도 보이지 않을 것이다. hello-world 컨테이너는 메시지를 출력하고 바로 종료되었기 때문이다. 종료된 컨테이너까지 보려면 -a 옵션을 붙인다.
docker ps -a출력에는 컨테이너 ID, 사용한 이미지, 실행한 명령, 생성 시간, 상태, 이름이 표시된다. STATUS에 Exited가 보이면 이미 종료된 컨테이너라는 뜻이다.
웹 서버 컨테이너 실행하기: nginx
이번에는 계속 실행되는 컨테이너를 만들어 보자. 웹 서버 이미지인 nginx를 사용한다.
docker run --name web -d nginx옵션을 하나씩 보자.
--name web: 컨테이너 이름을web으로 지정한다.-d: 컨테이너를 백그라운드에서 실행한다. 이를 detached mode라고 한다.nginx: 사용할 이미지 이름이다.
실행 후 컨테이너 ID처럼 보이는 긴 문자열이 출력된다. 이제 실행 중인 컨테이너를 확인한다.
docker ps이번에는 web 컨테이너가 목록에 보여야 한다. STATUS가 Up이면 실행 중이다.
컨테이너 로그도 확인할 수 있다.
docker logs web아직 웹 요청을 보내지 않았다면 로그가 많지 않을 수 있다. 괜찮다. 로그는 컨테이너 안에서 실행 중인 프로그램이 표준 출력이나 표준 에러로 남긴 내용을 보여준다. 실무에서는 애플리케이션 오류를 확인할 때 가장 먼저 보는 명령 중 하나다.
하지만 지금 상태에서는 브라우저에서 localhost 주소로 바로 접속할 수 없다. 컨테이너 안의 nginx는 80번 포트에서 기다리고 있지만, 내 컴퓨터의 포트와 연결하지 않았기 때문이다.
먼저 기존 컨테이너를 중지하고 삭제하자.
docker stop web
docker rm webdocker stop은 실행 중인 컨테이너를 멈춘다. docker rm은 멈춘 컨테이너를 삭제한다. 컨테이너를 삭제해도 원본 이미지인 nginx는 사라지지 않는다. 이미지는 컨테이너를 만들기 위한 재료이고, 컨테이너는 그 이미지로 만든 실행 인스턴스다.
포트 매핑으로 브라우저에서 접속하기
이제 포트 매핑을 사용해 nginx를 다시 실행한다.
docker run --name web -d -p 8080:80 nginx새로 추가된 옵션은 -p 8080:80이다. 의미는 다음과 같다.
내 컴퓨터의 8080번 포트 → 컨테이너의 80번 포트왼쪽은 호스트, 즉 내 컴퓨터의 포트다. 오른쪽은 컨테이너 내부 포트다. nginx는 컨테이너 안에서 80번 포트를 사용한다. 하지만 여러 컨테이너가 동시에 실행될 수 있으므로, 내 컴퓨터에서는 원하는 빈 포트를 골라 연결할 수 있다.
브라우저를 열고 다음 주소로 접속한다.
http://localhost:8080nginx 기본 화면이 보이면 성공이다. 만약 8080번 포트가 이미 사용 중이라는 오류가 난다면 호스트 쪽 포트를 바꾸면 된다. 예를 들어 -p 8081:80으로 실행했다면 브라우저에서는 http://localhost:8081로 접속한다.
이제 다시 로그를 확인해 보자.
docker logs web브라우저로 접속한 기록이 로그에 추가되었을 것이다. 이 작은 실습에서 Docker의 중요한 동작을 확인했다. 컨테이너 안의 웹 서버는 80번 포트에서 실행되지만, 우리는 포트 매핑을 통해 로컬 컴퓨터의 8080번 포트로 접근했다.
실무에서도 같은 원리를 자주 사용한다. 예를 들어 로컬 컴퓨터에서 웹 애플리케이션은 3000번, API 서버는 8080번, 데이터베이스는 5432번 포트로 연결해 개발 환경을 구성한다. 컨테이너마다 내부 포트는 정해져 있어도, 호스트 포트를 다르게 연결하면 충돌을 피할 수 있다.
컨테이너 상태 확인과 정리 흐름
Docker를 처음 사용할 때는 컨테이너를 실행한 뒤 그대로 두는 일이 많다. 그러면 같은 이름을 다시 쓰려고 할 때 오류가 난다.
Conflict. The container name "/web" is already in use이 메시지는 web이라는 이름의 컨테이너가 이미 있다는 뜻이다. 실행 중일 수도 있고, 종료된 상태로 남아 있을 수도 있다. 다음 순서로 확인하면 된다.
docker ps실행 중인 컨테이너만 확인한다.
docker ps -a종료된 컨테이너까지 모두 확인한다.
docker logs web컨테이너 로그를 확인한다.
docker stop web실행 중인 컨테이너를 중지한다.
docker rm web중지된 컨테이너를 삭제한다.
한 줄로 정리하고 싶다면 다음처럼 실행할 수도 있다.
docker stop web
docker rm web또는 실행 중인 컨테이너를 강제로 삭제할 수도 있다.
docker rm -f web다만 처음에는 stop과 rm을 나누어 사용하는 편이 좋다. 컨테이너를 멈추는 것과 삭제하는 것이 서로 다른 작업이라는 감각을 익힐 수 있기 때문이다.
마지막으로 현재 남아 있는 컨테이너를 확인한다.
docker ps -a필요 없는 hello-world 컨테이너도 삭제할 수 있다. 컨테이너 ID 전체를 입력할 필요는 없다. 앞의 몇 글자만으로 구분되면 된다.
docker rm 컨테이너ID이미지 목록은 다음 명령으로 확인한다.
docker images여기에는 hello-world와 nginx 이미지가 남아 있을 수 있다. 지금은 삭제하지 않아도 된다. 이후 장에서 이미지와 컨테이너의 생명주기를 더 자세히 다룰 것이다.
이번 장에서 익힌 기본 패턴
이번 장의 목표는 많은 명령어를 외우는 것이 아니다. Docker를 사용할 때 반복되는 기본 흐름을 손에 익히는 것이다.
docker run hello-world설치가 제대로 되었는지 확인했다.
docker run --name web -d -p 8080:80 nginx웹 서버 컨테이너를 백그라운드로 실행하고, 로컬 브라우저에서 접근할 수 있게 포트를 연결했다.
docker ps
docker logs web
docker stop web
docker rm web실행 상태를 확인하고, 로그를 보고, 중지하고, 삭제했다.
Docker는 처음에는 명령어가 낯설지만 흐름은 단순하다. 이미지를 준비하고, 컨테이너로 실행하고, 상태를 확인하고, 필요 없으면 정리한다. 다음 장에서는 이 흐름을 더 정확히 이해하기 위해 이미지와 컨테이너의 생명주기를 살펴본다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.