IT 위키 - 사용자 기여 [ko]

Docker run

2026-06-26T07:20:57Z

여전사: 새 문서: docker run은 Docker 이미지로부터 새 컨테이너를 생성하고 실행하는 Docker CLI 명령으로, 공식 명령은 <code>docker container run</code>이며 <code>docker run</code>은 그 별칭으로 사용된다.<ref name="docker-run">Docker Docs, "docker container run", https://docs.docker.com/reference/cli/docker/container/run/, 확인일: 2026-06-26.</ref> == 개요 == <code>docker run</code>은 지정한 이미지로 컨테이너를 만들고, 필요한 경...

docker run은 Docker 이미지로부터 새 컨테이너를 생성하고 실행하는 [[Docker CLI]] 명령으로, 공식 명령은 <code>docker container run</code>이며 <code>docker run</code>은 그 별칭으로 사용된다.<ref name="docker-run">Docker Docs, "docker container run", https://docs.docker.com/reference/cli/docker/container/run/, 확인일: 2026-06-26.</ref>

== 개요 ==
<code>docker run</code>은 지정한 이미지로 컨테이너를 만들고, 필요한 경우 이미지를 레지스트리에서 가져온 뒤, 컨테이너의 기본 명령 또는 사용자가 지정한 명령을 실행한다. 로컬에 이미지가 없으면 기본적으로 이미지를 풀한 뒤 실행하며, 이미 정지된 컨테이너를 다시 실행하려면 <code>docker start</code>를 사용한다.<ref name="docker-run" />

기본 형식은 다음과 같다.

<syntaxhighlight lang="bash">
docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
</syntaxhighlight>

예를 들어 <code>ubuntu:24.04</code> 이미지로 일회성 셸을 실행하려면 다음과 같이 입력한다.

<syntaxhighlight lang="bash">
docker run --rm -it ubuntu:24.04 bash
</syntaxhighlight>

== 기본 구조 ==
<code>docker run</code> 명령은 크게 옵션, 이미지, 컨테이너 내부에서 실행할 명령으로 구성된다.

{| class="wikitable"
! 구성 요소 !! 예시 !! 설명
|-
| 옵션
| <code>--rm -it -v "$PWD":/app -p 8080:80</code>
| 컨테이너 삭제, 터미널 연결, 볼륨 마운트, 포트 공개 등 실행 방식을 지정한다.
|-
| 이미지
| <code>nginx:latest</code>, <code>ubuntu:24.04</code>
| 컨테이너를 생성할 기준 이미지이다. 태그를 생략하면 일반적으로 <code>latest</code> 태그가 사용된다.
|-
| 명령
| <code>bash</code>, <code>npm start</code>
| 이미지에 정의된 기본 명령 대신 컨테이너 안에서 실행할 명령이다.
|}

<syntaxhighlight lang="bash">
docker run [옵션] 이미지[:태그] [컨테이너_내부_명령]
</syntaxhighlight>

== 자주 쓰는 옵션 ==
아래 옵션들은 실무에서 사용 빈도가 높은 순서와 학습 중요도를 고려해 정리한 것이다.

{| class="wikitable"
! 순서 !! 옵션 !! 의미 !! 대표 사용 상황
|-
| 1
| <code>--rm</code>
| 컨테이너 종료 시 자동 삭제
| 테스트, 일회성 실행, 임시 셸
|-
| 2
| <code>-it</code>
| 표준 입력 유지(<code>-i</code>)와 가상 터미널 할당(<code>-t</code>)
| 대화형 셸, 디버깅
|-
| 3
| <code>-v</code>, <code>--volume</code>
| 호스트 경로 또는 Docker 볼륨을 컨테이너에 마운트
| 소스 코드 공유, 데이터 영속화
|-
| 4
| <code>-p</code>, <code>--publish</code>
| 호스트 포트와 컨테이너 포트를 연결
| 웹 서버, API 서버 실행
|-
| 5
| <code>--name</code>
| 컨테이너 이름 지정
| 컨테이너 식별, 로그 확인, 네트워크 연결
|-
| 6
| <code>-d</code>, <code>--detach</code>
| 백그라운드 실행
| 서버 프로세스 실행
|-
| 7
| <code>-e</code>, <code>--env</code>
| 환경 변수 전달
| 설정값, 비밀번호, 실행 모드 지정
|-
| 8
| <code>--env-file</code>
| 파일에서 환경 변수 일괄 전달
| 환경별 설정 관리
|-
| 9
| <code>--network</code>
| 컨테이너 네트워크 지정
| 컨테이너 간 통신, 네트워크 격리
|-
| 10
| <code>--restart</code>
| 컨테이너 재시작 정책 지정
| 운영용 데몬, 장애 자동 복구
|-
| 11
| <code>-w</code>, <code>--workdir</code>
| 컨테이너 내부 작업 디렉터리 지정
| 소스 디렉터리 기준 명령 실행
|-
| 12
| <code>-u</code>, <code>--user</code>
| 컨테이너 내부 실행 사용자 지정
| 루트 권한 회피, 파일 권한 관리
|-
| 13
| <code>--entrypoint</code>
| 이미지의 기본 엔트리포인트 재정의
| 디버깅, 초기화 명령 우회
|-
| 14
| <code>--pull</code>
| 이미지 풀 정책 지정
| 최신 이미지 보장, CI/CD
|-
| 15
| <code>--platform</code>
| 실행 플랫폼 지정
| ARM, AMD64 이미지 선택
|-
| 16
| <code>--cpus</code>, <code>--memory</code>
| CPU와 메모리 제한
| 리소스 제어, 테스트 환경 제한
|-
| 17
| <code>--mount</code>
| 구조화된 마운트 옵션
| 복잡한 바인드 마운트, 볼륨 마운트
|-
| 18
| <code>--add-host</code>
| 컨테이너 내부 <code>/etc/hosts</code> 항목 추가
| 로컬 도메인 테스트, 내부 이름 해석
|-
| 19
| <code>--privileged</code>
| 확장된 권한 부여
| 특수 장치 접근, Docker-in-Docker 등 제한적 상황
|-
| 20
| <code>--cap-add</code>, <code>--cap-drop</code>
| Linux capability 추가 또는 제거
| 최소 권한 원칙 적용
|}

== 주요 옵션 상세 ==

=== --rm ===
<code>--rm</code>은 컨테이너가 종료될 때 컨테이너 파일 시스템을 자동으로 삭제한다. 테스트용 컨테이너나 일회성 명령 실행에 적합하다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run --rm hello-world
</syntaxhighlight>

임시 Ubuntu 셸을 열고, 종료하면 컨테이너를 남기지 않는다.

<syntaxhighlight lang="bash">
docker run --rm -it ubuntu:24.04 bash
</syntaxhighlight>

Python 스크립트를 임시 컨테이너에서 실행한다.

<syntaxhighlight lang="bash">
docker run --rm -v "$PWD":/app -w /app python:3.12 python app.py
</syntaxhighlight>

<code>--rm</code>은 컨테이너를 남기지 않기 때문에 실행 후 로그나 파일 시스템 상태를 조사해야 하는 경우에는 사용하지 않는 편이 낫다.

=== -it ===
<code>-it</code>는 <code>-i</code>와 <code>-t</code>를 함께 쓴 축약형이다. <code>-i</code>는 표준 입력을 열어 두고, <code>-t</code>는 가상 터미널을 할당한다. 보통 컨테이너 안에서 셸을 열 때 함께 사용한다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run --rm -it ubuntu:24.04 bash
</syntaxhighlight>

Alpine Linux에서 셸을 실행한다.

<syntaxhighlight lang="bash">
docker run --rm -it alpine:latest sh
</syntaxhighlight>

실행 중인 컨테이너에 들어가는 명령은 <code>docker run</code>이 아니라 <code>docker exec</code>를 사용한다.

<syntaxhighlight lang="bash">
docker exec -it my-nginx sh
</syntaxhighlight>

=== -v, --volume ===
<code>-v</code> 또는 <code>--volume</code>은 호스트의 디렉터리, 파일, 또는 Docker 볼륨을 컨테이너 내부 경로에 마운트한다. 짧고 자주 쓰이지만, 복잡한 설정에는 <code>--mount</code>가 더 명시적이다.<ref name="storage">Docker Docs, "Storage", https://docs.docker.com/engine/storage/, 확인일: 2026-06-26.</ref><ref name="bind-mounts">Docker Docs, "Bind mounts", https://docs.docker.com/engine/storage/bind-mounts/, 확인일: 2026-06-26.</ref>

현재 디렉터리를 컨테이너의 <code>/app</code>에 마운트한다.

<syntaxhighlight lang="bash">
docker run --rm -it -v "$PWD":/app -w /app node:22 bash
</syntaxhighlight>

컨테이너 안에서 호스트 파일을 읽는다.

<syntaxhighlight lang="bash">
docker run --rm -v "$PWD":/app -w /app alpine:latest ls -al
</syntaxhighlight>

읽기 전용으로 마운트한다.

<syntaxhighlight lang="bash">
docker run --rm -v "$PWD":/app:ro -w /app alpine:latest cat README.md
</syntaxhighlight>

Docker 볼륨을 사용해 데이터베이스 데이터를 보존한다.

<syntaxhighlight lang="bash">
docker volume create mysql-data

docker run -d \
--name mysql \
-e MYSQL_ROOT_PASSWORD=secret \
-v mysql-data:/var/lib/mysql \
mysql:8.4
</syntaxhighlight>

바인드 마운트와 볼륨 마운트의 차이는 다음과 같다.

{| class="wikitable"
! 구분 !! 예시 !! 특징
|-
| 바인드 마운트
| <code>-v "$PWD":/app</code>
| 호스트의 실제 경로를 컨테이너에 연결한다. 개발 환경에서 소스 코드를 공유할 때 많이 쓴다.
|-
| Docker 볼륨
| <code>-v mysql-data:/var/lib/mysql</code>
| Docker가 관리하는 저장 공간을 연결한다. 데이터베이스 데이터처럼 영속성이 필요한 데이터에 적합하다.
|}

=== -p, --publish ===
<code>-p</code> 또는 <code>--publish</code>는 호스트 포트를 컨테이너 포트에 매핑한다. 컨테이너 내부 서비스는 기본적으로 호스트 외부에서 직접 접근할 수 없으므로, 웹 서버나 API 서버를 테스트할 때 자주 사용한다.<ref name="networking">Docker Docs, "Networking overview", https://docs.docker.com/engine/network/, 확인일: 2026-06-26.</ref>

Nginx 컨테이너의 80번 포트를 호스트 8080번 포트로 연결한다.

<syntaxhighlight lang="bash">
docker run --rm -d --name web -p 8080:80 nginx:latest
</syntaxhighlight>

브라우저 또는 curl로 접근한다.

<syntaxhighlight lang="bash">
curl http://localhost:8080
</syntaxhighlight>

호스트의 특정 IP에만 바인딩할 수도 있다.

<syntaxhighlight lang="bash">
docker run --rm -d --name web -p 127.0.0.1:8080:80 nginx:latest
</syntaxhighlight>

여러 포트를 동시에 공개한다.

<syntaxhighlight lang="bash">
docker run --rm -d \
--name app \
-p 8080:8080 \
-p 8443:8443 \
my-app:latest
</syntaxhighlight>

=== --name ===
<code>--name</code>은 컨테이너 이름을 지정한다. 이름을 지정하지 않으면 Docker가 임의의 이름을 부여한다. 운영이나 디버깅에서는 명시적인 이름을 붙이는 것이 편리하다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run -d --name my-nginx -p 8080:80 nginx:latest
</syntaxhighlight>

이름으로 로그를 확인한다.

<syntaxhighlight lang="bash">
docker logs my-nginx
</syntaxhighlight>

이름으로 컨테이너를 정지하고 삭제한다.

<syntaxhighlight lang="bash">
docker stop my-nginx
docker rm my-nginx
</syntaxhighlight>

같은 이름의 컨테이너가 이미 있으면 새 컨테이너를 만들 수 없으므로, 기존 컨테이너를 삭제하거나 다른 이름을 사용해야 한다.

=== -d, --detach ===
<code>-d</code> 또는 <code>--detach</code>는 컨테이너를 백그라운드에서 실행하고 컨테이너 ID를 출력한다. 서버 프로세스처럼 계속 실행되는 컨테이너에 많이 사용한다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run -d --name redis redis:7
</syntaxhighlight>

실행 상태를 확인한다.

<syntaxhighlight lang="bash">
docker ps
</syntaxhighlight>

로그를 실시간으로 확인한다.

<syntaxhighlight lang="bash">
docker logs -f redis
</syntaxhighlight>

=== -e, --env ===
<code>-e</code> 또는 <code>--env</code>는 컨테이너에 환경 변수를 전달한다. 애플리케이션 설정, 데이터베이스 비밀번호, 실행 모드 등을 지정할 때 사용한다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run --rm -e NODE_ENV=production node:22 node -e "console.log(process.env.NODE_ENV)"
</syntaxhighlight>

MySQL 컨테이너에 루트 비밀번호와 데이터베이스 이름을 전달한다.

<syntaxhighlight lang="bash">
docker run -d \
--name mysql \
-e MYSQL_ROOT_PASSWORD=secret \
-e MYSQL_DATABASE=appdb \
mysql:8.4
</syntaxhighlight>

호스트의 환경 변수 값을 그대로 전달할 수도 있다.

<syntaxhighlight lang="bash">
export APP_MODE=dev
docker run --rm -e APP_MODE alpine:latest env
</syntaxhighlight>

비밀번호나 토큰을 명령행에 직접 쓰면 셸 히스토리나 프로세스 목록에 노출될 수 있으므로 운영 환경에서는 별도 보안 관리 방식을 고려해야 한다.

=== --env-file ===
<code>--env-file</code>은 환경 변수 파일을 컨테이너에 전달한다. 환경 변수가 많거나 환경별 설정 파일을 분리하고 싶을 때 유용하다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
cat > .env <<'EOF'
APP_ENV=local
APP_PORT=8080
DATABASE_URL=mysql://user:pass@db:3306/app
EOF

docker run --rm --env-file .env alpine:latest env
</syntaxhighlight>

=== --network ===
<code>--network</code>는 컨테이너가 사용할 네트워크를 지정한다. 기본값은 일반적으로 <code>bridge</code> 네트워크이며, 사용자 정의 브리지 네트워크를 만들면 컨테이너 이름으로 서로 통신하기 쉽다.<ref name="networking" />

사용자 정의 네트워크를 만든다.

<syntaxhighlight lang="bash">
docker network create app-net
</syntaxhighlight>

MySQL 컨테이너를 해당 네트워크에서 실행한다.

<syntaxhighlight lang="bash">
docker run -d \
--name db \
--network app-net \
-e MYSQL_ROOT_PASSWORD=secret \
mysql:8.4
</syntaxhighlight>

애플리케이션 컨테이너에서 <code>db</code>라는 이름으로 데이터베이스에 접근한다.

<syntaxhighlight lang="bash">
docker run --rm \
--network app-net \
alpine:latest \
sh -c "apk add --no-cache mysql-client && mysql -h db -uroot -psecret -e 'SELECT 1'"
</syntaxhighlight>

호스트 네트워크를 직접 사용하는 예시는 다음과 같다. 단, <code>host</code> 네트워크는 격리 수준과 플랫폼별 동작 차이를 고려해야 한다.

<syntaxhighlight lang="bash">
docker run --rm --network host nginx:latest
</syntaxhighlight>

=== --restart ===
<code>--restart</code>는 컨테이너 종료 시 재시작 정책을 지정한다. 장시간 실행되는 서비스에 사용하지만, 일회성 컨테이너에는 보통 사용하지 않는다.<ref name="docker-run" />

항상 재시작하도록 실행한다.

<syntaxhighlight lang="bash">
docker run -d \
--name redis \
--restart unless-stopped \
redis:7
</syntaxhighlight>

주요 값은 다음과 같다.

{| class="wikitable"
! 값 !! 설명
|-
| <code>no</code>
| 자동 재시작하지 않는다. 기본값이다.
|-
| <code>on-failure</code>
| 비정상 종료 시 재시작한다.
|-
| <code>always</code>
| 컨테이너가 종료되면 항상 재시작한다.
|-
| <code>unless-stopped</code>
| 사용자가 직접 정지하지 않은 경우 재시작한다.
|}

=== -w, --workdir ===
<code>-w</code> 또는 <code>--workdir</code>는 컨테이너 내부의 작업 디렉터리를 지정한다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run --rm \
-v "$PWD":/app \
-w /app \
python:3.12 \
python main.py
</syntaxhighlight>

Node.js 프로젝트에서 현재 디렉터리를 마운트하고 의존성을 설치한다.

<syntaxhighlight lang="bash">
docker run --rm -it \
-v "$PWD":/app \
-w /app \
node:22 \
npm install
</syntaxhighlight>

=== -u, --user ===
<code>-u</code> 또는 <code>--user</code>는 컨테이너 내부 프로세스를 특정 사용자나 UID/GID로 실행한다. 바인드 마운트한 디렉터리에 루트 소유 파일이 생기는 문제를 줄일 때 유용하다.<ref name="docker-run" />

현재 호스트 사용자의 UID/GID로 실행한다.

<syntaxhighlight lang="bash">
docker run --rm \
-u "$(id -u):$(id -g)" \
-v "$PWD":/app \
-w /app \
node:22 \
npm test
</syntaxhighlight>

컨테이너 내부의 <code>node</code> 사용자로 실행한다.

<syntaxhighlight lang="bash">
docker run --rm -u node node:22 node -e "console.log(process.getuid())"
</syntaxhighlight>

=== --entrypoint ===
<code>--entrypoint</code>는 이미지에 정의된 기본 엔트리포인트를 재정의한다. 컨테이너가 즉시 종료되거나 기본 실행 명령을 우회해 디버깅해야 할 때 사용한다.<ref name="docker-run" />

이미지의 기본 엔트리포인트 대신 셸을 실행한다.

<syntaxhighlight lang="bash">
docker run --rm -it --entrypoint sh nginx:latest
</syntaxhighlight>

엔트리포인트를 <code>python</code>으로 바꾸고 버전을 확인한다.

<syntaxhighlight lang="bash">
docker run --rm --entrypoint python python:3.12 --version
</syntaxhighlight>

=== --pull ===
<code>--pull</code>은 컨테이너 실행 전에 이미지를 어떻게 가져올지 지정한다. CI/CD 환경에서는 최신 이미지를 보장하기 위해 <code>--pull always</code>를 쓰는 경우가 있다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run --rm --pull always alpine:latest cat /etc/os-release
</syntaxhighlight>

주요 값은 다음과 같다.

{| class="wikitable"
! 값 !! 설명
|-
| <code>missing</code>
| 로컬에 이미지가 없을 때만 가져온다.
|-
| <code>always</code>
| 실행할 때마다 레지스트리에서 이미지를 확인하고 가져온다.
|-
| <code>never</code>
| 이미지를 가져오지 않고 로컬 이미지로만 실행한다.
|}

=== --platform ===
<code>--platform</code>은 실행할 이미지의 플랫폼을 지정한다. 멀티 아키텍처 이미지를 사용할 때 <code>linux/amd64</code>, <code>linux/arm64</code> 등을 명시할 수 있다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run --rm --platform linux/amd64 alpine:latest uname -m
</syntaxhighlight>

Apple Silicon 환경에서 AMD64 이미지를 테스트하는 예시는 다음과 같다.

<syntaxhighlight lang="bash">
docker run --rm --platform linux/amd64 node:22 node -p "process.arch"
</syntaxhighlight>

=== --cpus, --memory ===
<code>--cpus</code>와 <code>--memory</code>는 컨테이너가 사용할 수 있는 CPU와 메모리를 제한한다. 리소스 사용량을 제어하거나 장애 상황을 재현할 때 유용하다.<ref name="resource">Docker Docs, "Runtime options with Memory, CPUs, and GPUs", https://docs.docker.com/engine/containers/resource_constraints/, 확인일: 2026-06-26.</ref>

CPU 1개, 메모리 512MiB로 제한한다.

<syntaxhighlight lang="bash">
docker run --rm \
--cpus="1.0" \
--memory="512m" \
nginx:latest
</syntaxhighlight>

메모리 제한을 걸고 Node.js 스크립트를 실행한다.

<syntaxhighlight lang="bash">
docker run --rm \
--memory="256m" \
node:22 \
node -e "console.log('memory limited container')"
</syntaxhighlight>

=== --mount ===
<code>--mount</code>는 마운트 타입과 옵션을 명시적으로 지정하는 방식이다. <code>-v</code>보다 길지만, 복잡한 마운트 설정을 읽기 쉽게 표현할 수 있다.<ref name="bind-mounts" />

바인드 마운트 예시:

<syntaxhighlight lang="bash">
docker run --rm \
--mount type=bind,source="$PWD",target=/app,readonly \
-w /app \
alpine:latest \
ls -al
</syntaxhighlight>

Docker 볼륨 마운트 예시:

<syntaxhighlight lang="bash">
docker volume create app-cache

docker run --rm \
--mount type=volume,source=app-cache,target=/cache \
alpine:latest \
sh -c "echo cached > /cache/test.txt && cat /cache/test.txt"
</syntaxhighlight>

=== --add-host ===
<code>--add-host</code>는 컨테이너 내부의 <code>/etc/hosts</code>에 호스트명과 IP 주소를 추가한다. 로컬 개발 환경에서 임시 도메인 이름을 테스트할 때 유용하다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run --rm \
--add-host api.local:127.0.0.1 \
alpine:latest \
cat /etc/hosts
</syntaxhighlight>

Docker Desktop 등 일부 환경에서는 호스트 머신을 가리키는 이름으로 <code>host.docker.internal</code>을 사용하는 경우가 많다.

<syntaxhighlight lang="bash">
docker run --rm \
--add-host host.docker.internal:host-gateway \
alpine:latest \
ping -c 1 host.docker.internal
</syntaxhighlight>

=== --privileged ===
<code>--privileged</code>는 컨테이너에 확장된 권한을 부여한다. 장치 접근, 커널 기능 사용, Docker-in-Docker 같은 특수한 경우에 쓰이지만 보안 위험이 크므로 일반 애플리케이션 컨테이너에는 사용하지 않는 것이 좋다.<ref name="docker-run" />

<syntaxhighlight lang="bash">
docker run --rm -it --privileged alpine:latest sh
</syntaxhighlight>

운영 환경에서는 <code>--privileged</code> 대신 필요한 capability나 장치만 제한적으로 부여하는 방식을 우선 검토한다.

=== --cap-add, --cap-drop ===
<code>--cap-add</code>와 <code>--cap-drop</code>은 컨테이너의 Linux capability를 추가하거나 제거한다. 최소 권한 원칙을 적용할 때 사용한다.<ref name="docker-run" />

모든 capability를 제거하고 필요한 권한만 추가하는 예시는 다음과 같다.

<syntaxhighlight lang="bash">
docker run --rm \
--cap-drop ALL \
--cap-add NET_BIND_SERVICE \
nginx:latest
</syntaxhighlight>

네트워크 진단 도구 사용을 위해 <code>NET_ADMIN</code>을 추가하는 예시는 다음과 같다.

<syntaxhighlight lang="bash">
docker run --rm -it \
--cap-add NET_ADMIN \
nicolaka/netshoot
</syntaxhighlight>

== 실전 예시 ==

=== 임시 명령 실행 ===
컨테이너를 남기지 않고 명령만 실행한다.

<syntaxhighlight lang="bash">
docker run --rm alpine:latest echo "hello docker"
</syntaxhighlight>

현재 날짜를 컨테이너 안에서 출력한다.

<syntaxhighlight lang="bash">
docker run --rm alpine:latest date
</syntaxhighlight>

=== 대화형 셸 실행 ===
Ubuntu 컨테이너 안에서 셸을 연다.

<syntaxhighlight lang="bash">
docker run --rm -it ubuntu:24.04 bash
</syntaxhighlight>

Alpine 컨테이너 안에서 셸을 연다.

<syntaxhighlight lang="bash">
docker run --rm -it alpine:latest sh
</syntaxhighlight>

=== 현재 디렉터리에서 Python 실행 ===
현재 디렉터리를 컨테이너에 마운트하고 Python 파일을 실행한다.

<syntaxhighlight lang="bash">
docker run --rm \
-v "$PWD":/app \
-w /app \
python:3.12 \
python main.py
</syntaxhighlight>

패키지를 설치하고 테스트를 실행한다.

<syntaxhighlight lang="bash">
docker run --rm \
-v "$PWD":/app \
-w /app \
python:3.12 \
sh -c "pip install -r requirements.txt && pytest"
</syntaxhighlight>

=== Node.js 프로젝트 실행 ===
현재 디렉터리를 마운트하고 Node.js 명령을 실행한다.

<syntaxhighlight lang="bash">
docker run --rm -it \
-v "$PWD":/app \
-w /app \
node:22 \
npm install
</syntaxhighlight>

테스트를 실행한다.

<syntaxhighlight lang="bash">
docker run --rm \
-v "$PWD":/app \
-w /app \
node:22 \
npm test
</syntaxhighlight>

개발 서버를 실행하고 포트를 연결한다.

<syntaxhighlight lang="bash">
docker run --rm -it \
-v "$PWD":/app \
-w /app \
-p 3000:3000 \
node:22 \
npm run dev
</syntaxhighlight>

=== Nginx 웹 서버 실행 ===
Nginx를 백그라운드로 실행하고 호스트 8080번 포트로 공개한다.

<syntaxhighlight lang="bash">
docker run -d \
--name web \
-p 8080:80 \
nginx:latest
</syntaxhighlight>

정적 파일을 Nginx 기본 경로에 읽기 전용으로 마운트한다.

<syntaxhighlight lang="bash">
docker run --rm -d \
--name static-web \
-p 8080:80 \
-v "$PWD/html":/usr/share/nginx/html:ro \
nginx:latest
</syntaxhighlight>

로그를 확인한다.

<syntaxhighlight lang="bash">
docker logs -f static-web
</syntaxhighlight>

=== MySQL 실행 ===
MySQL 컨테이너를 실행하고 데이터를 Docker 볼륨에 저장한다.

<syntaxhighlight lang="bash">
docker volume create mysql-data

docker run -d \
--name mysql \
-e MYSQL_ROOT_PASSWORD=secret \
-e MYSQL_DATABASE=appdb \
-v mysql-data:/var/lib/mysql \
-p 3306:3306 \
mysql:8.4
</syntaxhighlight>

MySQL 클라이언트 컨테이너로 접속한다.

<syntaxhighlight lang="bash">
docker run --rm -it \
--network container:mysql \
mysql:8.4 \
mysql -h 127.0.0.1 -uroot -psecret appdb
</syntaxhighlight>

=== Redis 실행 ===
Redis를 백그라운드로 실행한다.

<syntaxhighlight lang="bash">
docker run -d \
--name redis \
-p 6379:6379 \
redis:7
</syntaxhighlight>

Redis CLI로 접속한다.

<syntaxhighlight lang="bash">
docker run --rm -it \
--network container:redis \
redis:7 \
redis-cli -h 127.0.0.1
</syntaxhighlight>

=== 컨테이너 간 네트워크 연결 ===
사용자 정의 네트워크를 만들고 애플리케이션과 데이터베이스를 같은 네트워크에 배치한다.

<syntaxhighlight lang="bash">
docker network create app-net

docker run -d \
--name db \
--network app-net \
-e POSTGRES_PASSWORD=secret \
postgres:16

docker run --rm -it \
--name app \
--network app-net \
-e DATABASE_HOST=db \
alpine:latest \
sh
</syntaxhighlight>

사용자 정의 네트워크에서는 같은 네트워크에 속한 컨테이너가 컨테이너 이름으로 서로를 찾을 수 있다.

=== 일회성 빌드 도구처럼 사용 ===
호스트에 Go를 설치하지 않고 Go 테스트를 실행한다.

<syntaxhighlight lang="bash">
docker run --rm \
-v "$PWD":/src \
-w /src \
golang:1.23 \
go test ./...
</syntaxhighlight>

호스트에 Maven을 설치하지 않고 Java 프로젝트를 빌드한다.

<syntaxhighlight lang="bash">
docker run --rm \
-v "$PWD":/workspace \
-w /workspace \
maven:3.9-eclipse-temurin-21 \
mvn test
</syntaxhighlight>

=== 파일 권한 문제 줄이기 ===
바인드 마운트한 디렉터리에 루트 소유 파일이 생기지 않도록 현재 사용자 UID/GID로 실행한다.

<syntaxhighlight lang="bash">
docker run --rm \
-u "$(id -u):$(id -g)" \
-v "$PWD":/app \
-w /app \
node:22 \
npm install
</syntaxhighlight>

=== 이미지 기본 명령 확인 또는 우회 ===
이미지의 기본 명령 대신 셸을 실행한다.

<syntaxhighlight lang="bash">
docker run --rm -it --entrypoint sh nginx:latest
</syntaxhighlight>

컨테이너의 환경을 확인한다.

<syntaxhighlight lang="bash">
docker run --rm --entrypoint env nginx:latest
</syntaxhighlight>

== 자주 쓰는 조합 ==
{| class="wikitable"
! 목적 !! 명령 예시
|-
| 임시 셸
| <code>docker run --rm -it ubuntu:24.04 bash</code>
|-
| 현재 디렉터리 마운트
| <code>docker run --rm -v "$PWD":/app -w /app alpine ls</code>
|-
| 웹 서버 실행
| <code>docker run -d --name web -p 8080:80 nginx</code>
|-
| 환경 변수 전달
| <code>docker run --rm -e APP_ENV=dev alpine env</code>
|-
| 볼륨으로 데이터 보존
| <code>docker run -d -v mysql-data:/var/lib/mysql mysql:8.4</code>
|-
| 사용자 정의 네트워크 사용
| <code>docker run --network app-net --name app my-app</code>
|-
| 현재 사용자 권한으로 실행
| <code>docker run --rm -u "$(id -u):$(id -g)" -v "$PWD":/app image command</code>
|-
| 최신 이미지 확인 후 실행
| <code>docker run --rm --pull always alpine</code>
|}

== 주의사항 ==
* <code>docker run</code>은 새 컨테이너를 생성한다. 기존 컨테이너를 다시 시작하려면 <code>docker start</code>를 사용한다.
* <code>--rm</code>을 사용하면 컨테이너 종료 후 컨테이너 자체가 삭제되므로, 종료 후 상태 분석이 필요한 경우에는 사용하지 않는다.
* 바인드 마운트는 호스트 파일 시스템을 컨테이너에 노출하므로 경로와 권한을 신중히 지정해야 한다.
* 데이터베이스처럼 데이터 보존이 필요한 컨테이너는 컨테이너 내부 파일 시스템에만 의존하지 말고 Docker 볼륨을 사용한다.
* <code>-p 8080:80</code>에서 앞의 <code>8080</code>은 호스트 포트, 뒤의 <code>80</code>은 컨테이너 포트이다.
* <code>latest</code> 태그는 항상 같은 이미지를 의미하지 않을 수 있으므로 운영 환경에서는 명시적인 버전 태그를 사용하는 것이 좋다.
* <code>--privileged</code>는 컨테이너 격리를 크게 약화할 수 있으므로 필요한 경우에만 제한적으로 사용한다.
* 민감한 값을 <code>-e PASSWORD=...</code> 형태로 명령행에 직접 넣으면 기록에 남을 수 있으므로 운영 환경에서는 보안 저장소나 오케스트레이션 도구의 시크릿 기능을 고려한다.

== 관련 명령어 ==
{| class="wikitable"
! 명령어 !! 설명
|-
| <code>docker ps</code>
| 실행 중인 컨테이너 목록을 확인한다.
|-
| <code>docker ps -a</code>
| 정지된 컨테이너를 포함해 모든 컨테이너 목록을 확인한다.
|-
| <code>docker logs</code>
| 컨테이너 로그를 확인한다.
|-
| <code>docker exec</code>
| 실행 중인 컨테이너 안에서 새 명령을 실행한다.
|-
| <code>docker stop</code>
| 실행 중인 컨테이너를 정지한다.
|-
| <code>docker start</code>
| 정지된 컨테이너를 다시 시작한다.
|-
| <code>docker rm</code>
| 정지된 컨테이너를 삭제한다.
|-
| <code>docker volume</code>
| Docker 볼륨을 생성, 조회, 삭제한다.
|-
| <code>docker network</code>
| Docker 네트워크를 생성, 조회, 삭제한다.
|}

== 같이 보기 ==
* [[도커]]
* [[도커파일]]
* [[컨테이너 저장소]]
* [[쿠버네티스]]

== 각주 ==
<references />

[[분류:Docker]]
[[분류:컨테이너]]
[[분류:개발도구]]

아마존 ECR

2026-06-26T06:35:40Z

여전사: 새 문서: Amazon ECR(Amazon Elastic Container Registry)은 AWS가 제공하는 완전관리형 컨테이너 이미지 레지스트리 서비스로, Docker 이미지, OCI(Open Container Initiative) 이미지 및 OCI 호환 아티팩트를 저장·배포·관리하는 데 사용된다.<ref name="what-is-ecr">Amazon Web Services, "What is Amazon Elastic Container Registry?", https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html, 확인일: 2026-06-26.</ref> == 개요 =...

Amazon ECR(Amazon Elastic Container Registry)은 [[AWS]]가 제공하는 완전관리형 컨테이너 이미지 레지스트리 서비스로, Docker 이미지, OCI(Open Container Initiative) 이미지 및 OCI 호환 아티팩트를 저장·배포·관리하는 데 사용된다.<ref name="what-is-ecr">Amazon Web Services, "What is Amazon Elastic Container Registry?", https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html, 확인일: 2026-06-26.</ref>

== 개요 ==
Amazon ECR은 컨테이너 기반 애플리케이션 배포 파이프라인에서 이미지 저장소 역할을 하는 [[AWS]] 서비스이다. 사용자는 [[Docker CLI]], [[AWS CLI]], [[AWS SDK]], [[CI/CD]] 도구 등을 이용해 컨테이너 이미지를 Amazon ECR 리포지토리에 푸시하고, [[Amazon ECS]], [[Amazon EKS]], [[AWS Lambda]], [[AWS App Runner]] 또는 온프레미스 실행 환경에서 이미지를 풀하여 사용할 수 있다.<ref name="ecr-doc">Amazon Web Services, "Amazon Elastic Container Registry Documentation", https://docs.aws.amazon.com/ecr/, 확인일: 2026-06-26.</ref>

Amazon ECR은 기본적으로 계정과 리전에 연결된 프라이빗 레지스트리를 제공하며, 하나의 레지스트리 안에 여러 리포지토리를 생성할 수 있다. 각 리포지토리는 이미지 태그와 이미지 다이제스트를 기준으로 Docker 이미지, OCI 이미지, OCI 호환 아티팩트를 관리한다.<ref name="private-registry">Amazon Web Services, "Amazon ECR private registry", https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html, 확인일: 2026-06-26.</ref><ref name="repositories">Amazon Web Services, "Amazon ECR private repositories", https://docs.aws.amazon.com/AmazonECR/latest/userguide/Repositories.html, 확인일: 2026-06-26.</ref>

== 주요 구성 요소 ==
{| class="wikitable"
! 구성 요소 !! 설명
|-
| 레지스트리
| [[AWS 계정]]과 [[AWS 리전]]에 연결된 컨테이너 이미지 저장 영역이다. 프라이빗 레지스트리는 계정별로 제공되며 여러 리포지토리를 포함할 수 있다.
|-
| 리포지토리
| 특정 애플리케이션 또는 이미지 계열을 저장하는 논리적 단위이다. Docker 이미지, OCI 이미지, OCI 호환 아티팩트를 저장할 수 있다.
|-
| 이미지
| 컨테이너 실행에 필요한 파일 시스템과 메타데이터를 포함한 산출물이다. 일반적으로 태그 또는 다이제스트로 식별한다.
|-
| 이미지 태그
| 사람이 읽기 쉬운 이미지 식별자이다. 예를 들어 <code>latest</code>, <code>v1.0.0</code> 같은 값이 사용된다.
|-
| 이미지 다이제스트
| 이미지 콘텐츠를 기준으로 생성되는 고유 식별자이다. 동일 태그가 변경될 수 있는 것과 달리 다이제스트는 특정 이미지 버전을 식별하는 데 유용하다.
|-
| 리포지토리 정책
| 리포지토리 단위로 접근 권한을 제어하는 리소스 기반 정책이다.
|}

== 주요 기능 ==
* '''프라이빗 컨테이너 이미지 저장소''': 조직 내부 또는 특정 [[AWS 계정]]에서 사용하는 컨테이너 이미지를 안전하게 저장한다.
* '''퍼블릭 레지스트리''': [[Amazon ECR Public]]을 통해 공개 컨테이너 이미지를 배포할 수 있다.<ref name="ecr-public">Amazon Web Services, "What Is Amazon Elastic Container Registry Public?", https://docs.aws.amazon.com/AmazonECR/latest/public/what-is-ecr.html, 확인일: 2026-06-26.</ref>
* '''[[AWS IAM]] 기반 접근 제어''': [[AWS IAM]] 사용자, 역할, 서비스, 다른 [[AWS 계정]]에 대해 푸시·풀·관리 권한을 세밀하게 부여할 수 있다.<ref name="iam">Amazon Web Services, "How Amazon Elastic Container Registry works with IAM", https://docs.aws.amazon.com/AmazonECR/latest/userguide/security_iam_service-with-iam.html, 확인일: 2026-06-26.</ref>
* '''리포지토리 정책''': 리포지토리 단위의 리소스 기반 정책을 설정해 특정 주체의 접근을 허용하거나 제한할 수 있다.<ref name="repo-policy">Amazon Web Services, "Private repository policies in Amazon ECR", https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html, 확인일: 2026-06-26.</ref>
* '''취약점 스캔''': 컨테이너 이미지의 소프트웨어 취약점을 식별한다. 기본 스캔과 [[Amazon Inspector]] 연동 기반의 향상된 스캔을 제공한다.<ref name="scan">Amazon Web Services, "Scan images for software vulnerabilities in Amazon ECR", https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-scanning.html, 확인일: 2026-06-26.</ref>
* '''수명 주기 정책''': 오래되었거나 사용하지 않는 이미지를 조건에 따라 만료 또는 아카이브하여 저장소를 관리한다.<ref name="lifecycle">Amazon Web Services, "Automate the cleanup of images by using lifecycle policies in Amazon ECR", https://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html, 확인일: 2026-06-26.</ref>
* '''이미지 복제''': 리전 간 또는 계정 간 프라이빗 이미지 복제를 지원한다.<ref name="replication">Amazon Web Services, "Private image replication in Amazon ECR", https://docs.aws.amazon.com/AmazonECR/latest/userguide/replication.html, 확인일: 2026-06-26.</ref>
* '''풀 스루 캐시''': 외부 업스트림 레지스트리의 이미지를 Amazon ECR 프라이빗 레지스트리로 캐시해 반복적인 이미지 풀을 단순화할 수 있다.<ref name="cache">Amazon Web Services, "Sync an upstream registry with an Amazon ECR private registry", https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache.html, 확인일: 2026-06-26.</ref>
* '''[[AWS PrivateLink]] 연동''': 인터페이스 [[VPC 엔드포인트]]를 사용해 [[Amazon VPC]] 내부에서 Amazon ECR API에 비공개로 접근할 수 있다.<ref name="privatelink">Amazon Web Services, "Amazon ECR interface VPC endpoints (AWS PrivateLink)", https://docs.aws.amazon.com/AmazonECR/latest/userguide/vpc-endpoints.html, 확인일: 2026-06-26.</ref>

== 동작 방식 ==
일반적인 사용 흐름은 다음과 같다.

# Amazon ECR 리포지토리를 생성한다.
# [[AWS CLI]] 또는 [[Docker CLI]]로 Amazon ECR 레지스트리에 인증한다.
# 로컬에서 빌드한 컨테이너 이미지에 Amazon ECR 리포지토리 주소를 태그로 지정한다.
# 이미지를 Amazon ECR 리포지토리에 푸시한다.
# [[Amazon ECS]], [[Amazon EKS]], [[AWS Lambda]], [[AWS App Runner]] 또는 배포 파이프라인에서 해당 이미지를 풀하여 실행한다.

<pre>
aws ecr get-login-password --region ap-northeast-2 \
| docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com

docker build -t sample-app .
docker tag sample-app:latest 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/sample-app:latest
docker push 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/sample-app:latest
</pre>

Amazon ECR에 인증하려면 일반적으로 <code>ecr:GetAuthorizationToken</code> 권한이 필요하다. 인증 후에는 부여된 [[AWS IAM]] 권한과 리포지토리 정책에 따라 이미지 푸시, 풀, 삭제, 리포지토리 관리 작업을 수행한다.<ref name="docker-pull">Amazon Web Services, "Pulling an image to your local environment from an Amazon ECR private repository", https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-pull-ecr-image.html, 확인일: 2026-06-26.</ref>

== 보안 ==
Amazon ECR의 접근 제어는 [[AWS IAM]]과 리포지토리 정책을 중심으로 구성된다. [[AWS IAM]] 정책은 사용자나 역할이 Amazon ECR API를 호출할 수 있는 권한을 정의하고, 리포지토리 정책은 특정 리포지토리에 대한 리소스 기반 권한을 정의한다.<ref name="iam" /><ref name="repo-policy" />

이미지 취약점 관리는 Amazon ECR의 핵심 보안 기능 중 하나이다. 기본 스캔은 컨테이너 이미지의 알려진 취약점을 식별하는 데 사용되며, 향상된 스캔은 [[Amazon Inspector]]와 통합되어 운영체제 패키지와 프로그래밍 언어 패키지 취약점까지 분석할 수 있다.<ref name="enhanced-scan">Amazon Web Services, "Scan images for OS and programming language package vulnerabilities in Amazon ECR", https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-scanning-enhanced.html, 확인일: 2026-06-26.</ref>

네트워크 측면에서는 [[AWS PrivateLink]] 기반 인터페이스 [[VPC 엔드포인트]]를 구성해 인터넷 게이트웨이, NAT 디바이스, 가상 프라이빗 게이트웨이를 사용하지 않고 [[Amazon VPC]]에서 Amazon ECR API에 접근하도록 설계할 수 있다.<ref name="privatelink" />

== 운영 관리 ==
Amazon ECR 저장소는 이미지가 누적되기 쉬우므로 운영 환경에서는 수명 주기 정책을 함께 사용하는 것이 일반적이다. 수명 주기 정책은 태그 상태, 이미지 개수, 이미지 나이, 마지막 풀 시점 등의 조건을 기준으로 이미지를 정리할 수 있으며, 정책 적용 전 미리보기 기능을 사용해 영향을 확인할 수 있다.<ref name="lifecycle" /><ref name="lifecycle-preview">Amazon Web Services, "Creating a lifecycle policy preview in Amazon ECR", https://docs.aws.amazon.com/AmazonECR/latest/userguide/lpp_creation.html, 확인일: 2026-06-26.</ref>

멀티 리전 또는 다중 계정 환경에서는 이미지 복제를 사용해 배포 지연을 줄이고 장애 대응성을 높일 수 있다. Amazon ECR은 리전 간 복제와 계정 간 복제를 지원하며, 계정 간 복제의 경우 대상 계정의 레지스트리 권한 정책 설정이 필요하다.<ref name="replication" />

풀 스루 캐시는 Docker Hub, GitLab Container Registry 등 외부 업스트림 레지스트리 이미지를 Amazon ECR을 통해 가져오고 캐시하는 기능이다. 캐시된 태그 이미지는 이후 풀 요청에서 업스트림 변경 여부를 확인해 갱신을 시도한다.<ref name="cache" />

== 과금 ==
Amazon ECR은 주로 저장된 이미지 데이터 용량과 데이터 전송량을 기준으로 과금된다. 같은 리전 내에서 [[AWS]] 서비스가 Amazon ECR 이미지를 풀하는 경우와 리전 간 전송, 인터넷 전송 등은 과금 조건이 달라질 수 있으므로 운영 전 공식 요금표와 사용 리전을 확인해야 한다.<ref name="pricing">Amazon Web Services, "Amazon ECR Pricing", https://aws.amazon.com/ecr/pricing/, 확인일: 2026-06-26.</ref>

== 활용 사례 ==
* '''[[CI/CD]] 파이프라인''': 빌드 서버에서 생성한 컨테이너 이미지를 Amazon ECR에 저장하고 배포 단계에서 동일 이미지를 사용한다.
* '''[[Amazon ECS]]·[[Amazon EKS]] 배포''': [[Amazon ECS]] 태스크나 [[Amazon EKS]] 파드에서 Amazon ECR 이미지를 참조해 컨테이너를 실행한다.
* '''서버리스 컨테이너 배포''': [[AWS Lambda]] 컨테이너 이미지 또는 [[AWS App Runner]] 서비스의 이미지 저장소로 활용한다.
* '''멀티 리전 배포''': 이미지 복제를 이용해 여러 [[AWS 리전]]에 동일한 컨테이너 이미지를 배포한다.
* '''외부 이미지 캐시''': 풀 스루 캐시를 이용해 외부 레지스트리 의존도를 낮추고 이미지 풀 경로를 표준화한다.

== 장점과 한계 ==
{| class="wikitable"
! 구분 !! 내용
|-
| 장점
| [[AWS IAM]], [[Amazon ECS]], [[Amazon EKS]], [[AWS Lambda]], [[AWS App Runner]] 등 [[AWS]] 서비스와 통합성이 높고, 관리형 서비스이므로 별도 레지스트리 서버 운영 부담이 작다.
|-
| 장점
| 취약점 스캔, 수명 주기 정책, 이미지 복제, 풀 스루 캐시, [[AWS PrivateLink]] 연동 등 운영 기능을 제공한다.
|-
| 한계
| [[AWS 계정]]과 [[AWS 리전]] 구조에 종속되므로 멀티 클라우드 또는 온프레미스 중심 환경에서는 접근 경로, 인증 방식, 비용 구조를 별도로 설계해야 한다.
|-
| 한계
| 저장 이미지가 계속 누적될 경우 비용이 증가할 수 있어 이미지 태그 전략, 수명 주기 정책, 저장소 권한 관리를 함께 설계해야 한다.
|}

== 같이 보기 ==
* [[FaaS]]
* [[코드형 인프라]]

== 각주 ==
<references />

[[분류:AWS]]
[[분류:클라우드]]
[[분류:컨테이너]]