Docker 이미지 만들기 정리
스프링부트 같은 애플리케이션을 컨테이너로 띄우려면 결국 이미지 → 컨테이너 흐름으로 가야 한다.
여기서는 Docker 이미지 개념부터 Dockerfile, 빌드, 실행, Docker Hub 푸시까지 한 번에 정리한다.
1. Docker 이미지 개념
1-1. Docker 이미지란?
-
모든 컨테이너는 이미지를 바탕으로 실행된다.
-
이때 이미지는 컨테이너가 사용할 파일 시스템 스냅샷이라고 보면 된다.
- OS 레벨(예:
ubuntu,openjdk) - 애플리케이션 바이너리(JAR 등)
- 각종 설정 파일
- OS 레벨(예:
도커는 이미 준비된 베이스 이미지(ubuntu, openjdk 등)와
다양한 애플리케이션 이미지를 제공하고,
그 위에 커스텀 레이어를 쌓아서 나만의 이미지를 만들 수 있다.
1-2. 커스텀 이미지
커스텀 이미지를 만들면:
- 특정 애플리케이션이 실행 가능한 환경을 한 번에 패키징하고
- 어디서든
docker run만으로 똑같은 환경에서 실행할 수 있다.
결국 “내 애플리케이션을 언제 어디서나 똑같이 돌릴 수 있게 만들기 위한 단위”가 Docker 이미지다.
2. Dockerfile 핵심 명령어
Dockerfile 은 이미지를 만드는 레시피다.
주요 명령어만 간단히 정리하면:
| 명령어 | 설명 |
|---|---|
FROM | 베이스 이미지 지정. FROM openjdk:17-jdk-alpine 같은 형태 |
MAINTAINER | 이미지 관리자 정보. 빌드에 영향 없어서 보통 잘 안 씀 |
COPY | 로컬 파일/디렉터리를 이미지 내부로 복사. URL 안 됨, 압축 해제 안 함 |
ADD | COPY + 상대 경로, URL 사용 가능, 압축 파일이면 자동으로 풀어서 추가 |
RUN | 이미지 빌드 과정에서 실행할 명령어. 패키지 설치, 빌드 등 |
CMD | 컨테이너가 실행될 때 기본으로 실행할 명령. 여러 개 써도 마지막 것만 유효 |
ENTRYPOINT | 컨테이너 실행 시 무조건 실행할 명령. docker run 인자는 ENTRYPOINT 뒤에 붙는다 |
WORKDIR | 이후 COPY, RUN, CMD 등이 실행될 기본 작업 디렉터리 |
EXPOSE | 컨테이너에서 사용할 포트 번호를 명시 (실제 포트 연결은 -p 옵션으로) |
ENV | 환경 변수 설정. ENV SPRING_PROFILES_ACTIVE=prod 같은 식으로 사용 |
VOLUME | 호스트와 연결할 데이터 볼륨 정의. 컨테이너 외부에 데이터 보존할 때 사용 |
-
CMDvsENTRYPOINT요약CMD: 기본 실행 명령 + 기본 인자 (run 시 전달된 인자에 의해 덮어쓰기 쉬움)ENTRYPOINT: 항상 실행할 명령을 고정하고, run 인자는 그 뒤에 붙이는 느낌
3. Spring Boot 예제로 이미지 만들 준비
간단한 REST API 프로젝트를 예로 들면:
-
스프링부트 프로젝트 빌드
- Gradle / Maven 으로 JAR 빌드
build/libs/*.jar또는target/*.jar위치에 JAR 생성
-
프로젝트 루트에 Dockerfile 생성
- 프로젝트 최상위 폴더에
Dockerfile파일 생성 - 확장자 없이
Dockerfile이라는 이름 그대로 둬야 한다
- 프로젝트 최상위 폴더에
-
Windows에서 확장자 없는 Dockerfile 만들기
-
메모장/VS Code 등으로 내용 작성
-
저장할 때:
- 파일 형식: “모든 파일”
- 파일 이름:
"Dockerfile"처럼 따옴표 포함해서 저장
-
4. Docker 이미지 빌드하기 (docker build)
프로젝트와 Dockerfile 준비가 끝났다면 이미지로 빌드한다.
4-1. 기본 빌드 명령
docker build -t {이미지이름}:{태그} {Dockerfile 위치}
# 예시 1: 절대 경로 지정
docker build -t catohgiraffers/springbootdocker D:\docker_example
# 예시 2: Dockerfile이 있는 폴더에서 실행
docker build -t catohgiraffers/springbootdocker .-t:계정/이미지이름:태그형식으로 설정
태그를 생략하면 자동으로latest사용- 이미지 이름은 소문자만 쓰는 게 좋다 (관례 + 일부 제한)
4-2. 자주 쓰는 build 옵션
| 옵션 | 설명 |
|---|---|
--no-cache | 캐시를 사용하지 않고 매번 처음부터 빌드 |
--rm | 빌드 성공 시 임시 컨테이너 자동 삭제 (기본값) |
--force-rm | 빌드 실패 시에도 임시 컨테이너 삭제 |
-q | 빌드 로그 최소화 (조용히 빌드) |
빌드할 때 Dockerfile이 있는 디렉터리의 서브 디렉터리까지 전부 빌드 컨텍스트에 포함된다.
불필요한 파일이 너무 많으면 빌드가 느려지고 이미지도 커지니까.dockerignore로 꼭 걸러주는 게 좋다.
5. 빌드한 이미지 실행하기 (docker run)
이미지 빌드 후 실제로 컨테이너로 띄워보자.
5-1. 기본 실행 예시
docker run -p {호스트포트}:{컨테이너포트} -d {이미지이름}:{태그}
# 예시
docker run -p 60080:8080 -d catohgiraffers/springbootdocker:latest-
-p 60080:8080- 호스트
60080→ 컨테이너8080으로 포트 포워딩
- 호스트
-
-d: 백그라운드(detached) 실행
브라우저에서:
http://localhost:60080같은 식으로 접속하면 컨테이너 안에서 동작 중인 Spring Boot 앱에 도달한다.
5-2. 자주 쓰는 docker run 옵션 정리
| 옵션 | 설명 |
|---|---|
-d | 백그라운드 실행 (데몬 모드) |
-p | 포트 포워딩 (호스트:컨테이너) |
--name | 컨테이너 이름 지정 |
-it | 터미널을 인터랙티브 모드로 연결 (-i + -t) |
--rm | 컨테이너 종료 시 자동 삭제 |
-v | 호스트 디렉터리 ↔ 컨테이너 디렉터리 볼륨 마운트 |
-e | 환경 변수 설정 (-e SPRING_PROFILES_ACTIVE=prod) |
그 외 GPU, 보안 옵션 등은 필요할 때 공식 문서에서 추가로 확인하는 게 낫다.
5-3. 포트 충돌 에러 처리
컨테이너 실행 시 이런 에러가 나올 수 있다:
bind: address already in use
이 경우 해당 포트를 이미 쓰고 있는 프로세스를 찾아서 종료해줘야 한다.
# 포트 사용 중인 프로세스 찾기 (예: 60080 포트)
netstat -ano | findstr 60080
# 찾은 PID에 대해 프로세스 종료
taskkill /f /pid 8480그 다음 다시 docker run -p 60080:8080 ... 으로 실행하면 된다.
6. Docker Hub로 이미지 푸시하기
이미지를 만들고 나면 Docker Hub 같은 레지스트리에 올려두고,
다른 서버에서 docker pull 해서 재사용할 수 있다.
6-1. Docker Hub 로그인
docker login- Docker Hub 계정의 username / password 입력
6-2. 이미지 푸시
docker push {이미지이름}:{태그}
# 예시
docker push catohgiraffers/springbootdocker:latest이미지이름앞부분의 계정명은 Docker Hub username 과 일치해야 한다.
6-3. Docker Hub에서 확인
- https://hub.docker.com 접속
- 자신의 리포지토리에 들어가서 push 한 이미지가 잘 올라갔는지 확인
마무리 요약
- Docker 이미지는 컨테이너가 사용할 파일 시스템 + 실행 환경 패키지
- Dockerfile 로 이미지 빌드 레시피를 작성하고
docker build로 이미지 생성 docker run으로 포트 매핑 등 옵션을 주어 컨테이너 실행docker push로 이미지를 Docker Hub 에 올려두면, 어디서든docker pull로 똑같은 환경을 가져와서 실행할 수 있다.
