본문으로 건너뛰기

커스텀 Nginx·Apache·Tomcat 이미지

Docker Hub의 공식 이미지는 범용성을 위해 최소한의 설정만 포함합니다. 실제 서비스에서는 자체 설정 파일, 애플리케이션 코드, 보안 강화 옵션을 포함한 커스텀 이미지를 만들어야 합니다. Dockerfile로 이미지를 코드화하면 환경 재현이 보장되고, CI/CD 파이프라인과 자연스럽게 통합됩니다.

Dockerfile 기본 원칙​

커스텀 이미지 작성 전에 핵심 원칙을 이해합니다.

원칙설명
베이스 이미지 고정nginx:alpine 대신 nginx:1.25-alpine처럼 구체적 버전 지정
alpine 기반 선호일반 이미지 대비 크기 60~80% 절감, 공격 표면 최소화
레이어 최소화RUN 명령을 &&로 체이닝하여 레이어 수 감소
비루트 사용자USER 지시어로 root 외 사용자로 실행
.dockerignore빌드 컨텍스트에서 불필요한 파일 제외

.dockerignore 설정​

빌드 컨텍스트에 포함할 파일을 제한하여 빌드 속도와 보안을 개선합니다.

# .dockerignore

# 버전 관리
.git/
.gitignore

# 빌드 산출물 (Java/Maven)
target/
*.class

# 빌드 산출물 (Node.js)
node_modules/
dist/
build/

# 환경 변수 및 비밀 (절대 이미지에 포함 금지)
.env
.env.*
*.key
*.pem

# 로그 파일
*.log
logs/

# IDE 설정
.idea/
.vscode/
*.iml

# OS 파일
.DS_Store
Thumbs.db

# 문서
*.md
docs/

Nginx 커스텀 이미지​

Dockerfile​

# nginx/Dockerfile

# 베이스: nginx:alpine (경량, 약 7MB)
FROM nginx:1.25-alpine

# 메타데이터
LABEL maintainer="devteam@example.com"
LABEL version="1.0"
LABEL description="Custom Nginx reverse proxy image"

# 기본 설정 파일 제거 후 커스텀 설정 복사
RUN rm /etc/nginx/conf.d/default.conf

# 커스텀 nginx.conf 복사
COPY nginx.conf /etc/nginx/nginx.conf

# 가상 호스트 설정 복사
COPY conf.d/ /etc/nginx/conf.d/

# 정적 파일 복사 (빌드된 프론트엔드 포함 시)
COPY --chown=nginx:nginx static/ /usr/share/nginx/html/static/

# SSL 인증서 디렉터리 생성 (볼륨 마운트 위치)
RUN mkdir -p /etc/nginx/ssl

# 로그 디렉터리 권한 설정
RUN chown -R nginx:nginx /var/log/nginx \
    && chmod 755 /var/log/nginx

# nginx 설정 검증
RUN nginx -t

# 비루트 사용자로 실행 (프로세스 포트 1024 이상만 사용 가능)
# nginx는 master(root) + worker(nginx) 구조로 운영됨
USER nginx

EXPOSE 80 443

# 헬스체크
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost/health || exit 1

CMD ["nginx", "-g", "daemon off;"]

nginx.conf 예시 (COPY 대상)​

# nginx.conf
user  nginx;
worker_processes  auto;                    # CPU 코어 수에 맞게 자동 설정
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
    use epoll;                             # Linux 고성능 I/O
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # 로그 포맷 (JSON 형식으로 변경하면 로그 수집 용이)
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;
    gzip  on;
    gzip_types text/plain text/css application/json application/javascript;

    include /etc/nginx/conf.d/*.conf;
}

Tomcat 커스텀 이미지​

Dockerfile (WAR 배포 방식)​

# tomcat/Dockerfile

FROM tomcat:10.1-jdk17-temurin-alpine

LABEL maintainer="devteam@example.com"

# 기본 웹앱 제거 (ROOT, examples, docs 등)
RUN rm -rf /usr/local/tomcat/webapps/*

# server.xml 커스텀 (커넥터 설정, 포트 변경 등)
COPY server.xml /usr/local/tomcat/conf/server.xml

# context.xml 복사 (DB 커넥션 풀 JNDI 설정 등)
COPY context.xml /usr/local/tomcat/conf/context.xml

# WAR 파일 복사 (빌드된 결과물)
COPY target/myapp.war /usr/local/tomcat/webapps/ROOT.war

# JVM 메모리 설정 및 GC 튜닝
ENV JAVA_OPTS="-server \
    -Xms512m \
    -Xmx1024m \
    -XX:+UseG1GC \
    -XX:MaxGCPauseMillis=200 \
    -XX:+UseContainerSupport \
    -Djava.security.egd=file:/dev/./urandom \
    -Dfile.encoding=UTF-8 \
    -Duser.timezone=Asia/Seoul"

# catalina.sh 환경 변수 설정
ENV CATALINA_OPTS="-Dspring.profiles.active=prod"

# 로그 디렉터리
VOLUME /usr/local/tomcat/logs

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=60s \
  CMD curl -f http://localhost:8080/ || exit 1

CMD ["catalina.sh", "run"]

Spring Boot 멀티 스테이지 빌드​

멀티 스테이지 빌드는 빌드 환경(JDK + Maven/Gradle)과 실행 환경(JRE)을 분리하여 최종 이미지 크기를 획기적으로 줄입니다.

Maven 기반 멀티 스테이지 빌드​

# Dockerfile

# ══════════════════════════════════════════════════════
# 스테이지 1: 빌드 (Maven + JDK)
# ══════════════════════════════════════════════════════
FROM maven:3.9-eclipse-temurin-17-alpine AS builder

WORKDIR /build

# 의존성 캐싱 최적화: pom.xml 먼저 복사하여 소스 변경 시 재다운로드 방지
COPY pom.xml .
COPY .mvn/ .mvn/
RUN mvn dependency:go-offline -B    # 의존성 미리 다운로드

# 소스 코드 복사 및 빌드
COPY src/ src/
RUN mvn package -DskipTests -B \
    && mv target/*.jar target/app.jar

# ══════════════════════════════════════════════════════
# 스테이지 2: JRE 레이어 분리 (jlink 활용)
# ══════════════════════════════════════════════════════
FROM eclipse-temurin:17-jdk-alpine AS runtime-builder

COPY --from=builder /build/target/app.jar app.jar

# Spring Boot 레이어드 JAR 분리 (레이어 캐싱 최적화)
RUN java -Djarmode=layertools -jar app.jar extract

# ══════════════════════════════════════════════════════
# 스테이지 3: 실행 이미지 (JRE만 포함)
# ══════════════════════════════════════════════════════
FROM eclipse-temurin:17-jre-alpine

# 보안: 비루트 사용자 생성
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app

# Spring Boot 레이어드 JAR 복사 (변경이 드문 레이어 먼저)
COPY --from=runtime-builder --chown=appuser:appgroup dependencies/ ./
COPY --from=runtime-builder --chown=appuser:appgroup spring-boot-loader/ ./
COPY --from=runtime-builder --chown=appuser:appgroup snapshot-dependencies/ ./
COPY --from=runtime-builder --chown=appuser:appgroup application/ ./

# 로그 디렉터리 생성
RUN mkdir -p /app/logs && chown -R appuser:appgroup /app/logs

# 비루트 사용자로 실행
USER appuser

# JVM 옵션
ENV JAVA_OPTS="-XX:+UseContainerSupport \
    -XX:MaxRAMPercentage=75.0 \
    -XX:+UseG1GC \
    -Dfile.encoding=UTF-8 \
    -Duser.timezone=Asia/Seoul"

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=90s \
  CMD wget -qO- http://localhost:8080/actuator/health || exit 1

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS org.springframework.boot.loader.launch.JarLauncher"]

Gradle 기반 멀티 스테이지 빌드​

# Dockerfile.gradle

# 스테이지 1: 빌드
FROM gradle:8.5-jdk17-alpine AS builder

WORKDIR /build

# 의존성 캐싱 (Gradle wrapper + build 파일 먼저)
COPY gradlew .
COPY gradle/ gradle/
COPY build.gradle settings.gradle ./
RUN ./gradlew dependencies --no-daemon    # 의존성 미리 해결

# 소스 복사 및 빌드
COPY src/ src/
RUN ./gradlew bootJar --no-daemon -x test \
    && mv build/libs/*.jar build/libs/app.jar

# 스테이지 2: 실행
FROM eclipse-temurin:17-jre-alpine

RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app

COPY --from=builder --chown=appuser:appgroup /build/build/libs/app.jar app.jar

USER appuser

ENV JAVA_OPTS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0"

EXPOSE 8080

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

이미지 크기 비교​

방식이미지 크기
JDK + 전체 JAR~600MB
JRE + 전체 JAR~250MB
JRE + 레이어드 JAR~250MB (캐싱 효율 ↑)
alpine JRE + 레이어드 JAR~180MB

Apache 커스텀 이미지​

# apache/Dockerfile

FROM httpd:2.4-alpine

LABEL maintainer="devteam@example.com"

# 커스텀 httpd.conf 복사
COPY httpd.conf /usr/local/apache2/conf/httpd.conf

# 추가 설정 파일 복사 (mod_proxy, SSL 등)
COPY conf.d/ /usr/local/apache2/conf/extra/

# 정적 파일 복사
COPY --chown=daemon:daemon htdocs/ /usr/local/apache2/htdocs/

# 로그 디렉터리 권한
RUN chown -R daemon:daemon /usr/local/apache2/logs

# 설정 검증
RUN httpd -t

EXPOSE 80 443

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost/ || exit 1

CMD ["httpd-foreground"]

httpd.conf 주요 모듈 활성화​

# httpd.conf - mod_proxy 기반 Tomcat 연동 설정

# 필수 모듈 활성화
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule headers_module modules/mod_headers.so
LoadModule rewrite_module modules/mod_rewrite.so

ServerName example.com

# 프록시 설정
<VirtualHost *:80>
    ServerName example.com

    # Tomcat으로 리버스 프록시
    ProxyPreserveHost On
    ProxyPass / http://app:8080/
    ProxyPassReverse / http://app:8080/

    # 프록시 헤더 전달
    RequestHeader set X-Forwarded-Proto "http"
    RequestHeader set X-Forwarded-Port "80"

    ErrorLog /usr/local/apache2/logs/error.log
    CustomLog /usr/local/apache2/logs/access.log combined
</VirtualHost>

이미지 빌드 및 태깅​

기본 빌드​

# 현재 디렉터리 Dockerfile로 이미지 빌드
docker build -t myapp:1.0 .

# 특정 Dockerfile 지정
docker build -f Dockerfile.prod -t myapp:1.0-prod .

# 빌드 인수 전달
docker build --build-arg BUILD_VERSION=1.0.0 -t myapp:1.0 .

# 멀티 스테이지에서 특정 스테이지까지만 빌드 (디버깅용)
docker build --target builder -t myapp:builder .

# 캐시 없이 강제 재빌드
docker build --no-cache -t myapp:1.0 .

이미지 태깅 전략​

# Semantic Versioning 태깅
docker build -t myapp:1.2.3 .
docker tag myapp:1.2.3 myapp:1.2
docker tag myapp:1.2.3 myapp:1
docker tag myapp:1.2.3 myapp:latest

# Git 커밋 해시 기반 태깅 (CI/CD 권장)
GIT_HASH=$(git rev-parse --short HEAD)
docker build -t myapp:${GIT_HASH} .
docker tag myapp:${GIT_HASH} myapp:latest

Docker Hub / 프라이빗 레지스트리 푸시​

Docker Hub​

# Docker Hub 로그인
docker login

# 이미지 태깅 (Hub 형식: 계정명/이미지명:태그)
docker tag myapp:1.0 username/myapp:1.0
docker tag myapp:1.0 username/myapp:latest

# 이미지 푸시
docker push username/myapp:1.0
docker push username/myapp:latest

# 이미지 풀
docker pull username/myapp:1.0

AWS ECR (Elastic Container Registry)​

# AWS CLI로 ECR 로그인
aws ecr get-login-password --region ap-northeast-2 | \
  docker login --username AWS --password-stdin \
  123456789012.dkr.ecr.ap-northeast-2.amazonaws.com

# ECR 형식으로 태깅
ECR_URI=123456789012.dkr.ecr.ap-northeast-2.amazonaws.com
docker tag myapp:1.0 ${ECR_URI}/myapp:1.0

# 푸시
docker push ${ECR_URI}/myapp:1.0

자체 프라이빗 레지스트리 (Harbor / Registry)​

# Docker Registry 컨테이너 실행 (로컬 테스트용)
docker run -d \
  -p 5000:5000 \
  --name registry \
  -v registry-data:/var/lib/registry \
  registry:2

# 로컬 레지스트리에 태깅 및 푸시
docker tag myapp:1.0 localhost:5000/myapp:1.0
docker push localhost:5000/myapp:1.0

# 프라이빗 레지스트리에서 풀
docker pull localhost:5000/myapp:1.0

docker-compose.yml에서 프라이빗 레지스트리 이미지 사용​

services:
  app:
    image: 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/myapp:1.0
    # build 섹션 없이 레지스트리 이미지 직접 사용

이미지 최적화 실전 요약​

# 이미지 크기 확인
docker images myapp

# 레이어별 크기 분석
docker history myapp:1.0

# 이미지 내부 파일 시스템 검사 (dive 도구)
# docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock \
#   wagoodman/dive:latest myapp:1.0

# 불필요한 이미지 정리
docker image prune -f

# 빌드 캐시 정리
docker builder prune -f

고수 팁​

1. COPY vs ADD

ADD는 URL에서 파일을 다운로드하거나 tar 파일을 자동 압축 해제하는 기능이 있지만, 예측 불가능한 동작을 방지하기 위해 단순 파일 복사는 항상 COPY를 사용합니다.

2. --chown 플래그로 소유권 한 번에 설정

# ❌ 두 개 레이어 생성
COPY app.jar /app/
RUN chown appuser:appgroup /app/app.jar

# ✅ 한 개 레이어로 해결
COPY --chown=appuser:appgroup app.jar /app/

3. XX:+UseContainerSupport JVM 옵션

JDK 8u191, JDK 10 이후부터 컨테이너의 메모리 제한을 자동 인식합니다. -Xmx를 하드코딩하는 대신 -XX:MaxRAMPercentage=75.0을 사용하면 컨테이너 메모리 변경 시 자동 적응합니다.

4. 시크릿 빌드 인수 주의

# ❌ ARG로 전달된 비밀은 docker history에 노출됨
ARG DB_PASSWORD
ENV DB_PASS=${DB_PASSWORD}

# ✅ 런타임에 환경 변수로 주입 (docker-compose.yml의 environment 사용)

빌드 시점에 비밀 정보를 이미지에 넣으면 docker history로 노출됩니다. 모든 민감 정보는 런타임에 환경 변수 또는 Docker Secrets로 주입합니다.