Docker를 사용하면 손쉽게 리눅스 컨테이너를 만들고 관리할 수 있습니다. Docker에서 가장 많이 사용하고, 가장 중요한 명령어가 바로 컨테이너를 생성하고 실행하는 docker run 명령어입니다. 이 글에서는 docker run 명령어의 사용법과 자주 사용하는 옵션들을 알아보도록 하겠습니다.

시작하기 전에

docker run 명령어를 사용하려면 먼저 Docker가 설치되어있어야합니다. Docker는 리눅스에서 사용할 수 있는 애플리케이션입니다. 리눅스를 사용한다면 Docker Engine을, 윈도우나 맥OS를 사용한다면 경량 리눅스 가상 머신을 기반으로 동작하는 Docker Desktop을 사용하는 것을 추천합니다. 운영체제 별 Docker 설치에 관해서는 다음 글을 참고해주세요.

Docker 설치 방법 총 정리

Docker를 잘 모르고 아직 익숙하지 않다면, 튜토리얼을 따라하면서 Docker와 친해져보시기 바랍니다. 다음 튜토리얼에서는 Docker 명령어들을 하나씩 실행하면서 개념과 사용법을 배울 수 있습니다.

따라하면서 배우는 Docker 입문 튜토리얼

`docker run`의 명령어 형식

Docker 공식 문서의 docker run 명령어의 형식입니다.

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

[] 값들은 생략가능한 옵셔널입니다. 이 형식에서 알 수 있듯이 docker run과 IMAGE 값은 필수적으로 지정해야합니다. 옵션은 docker run과 IMAGE 사이에 들어갑니다. 도커에 조금 익숙해지시면, docker run과 IMAGE 사이에 온갖 옵션들이 주렁주렁 달리는 모습을 목격하게 되실 겁니다.

`docker run`과 도커 이미지

docker run 명령어에서 IMAGE는 도커 이미지의 이름을 의미합니다. 이미지는, 기본적으로 로컬에 저장된 이미지를 사용합니다. 하지만 로컬에 지정한 이미지가 없더라도, Docker Hub의 이미지를 바로 가져다 사용할 수 있습니다. Docker Hub를 통해 이미지를 풀 받을 수 있다는 점은 Docker의 가장 강력한 특징 중 하나입니다.

Docker에서는 다양한 공식 이미지들을 제공하고 있습니다. 예를 들어 nginx나 mongo, redis, rabbitmq, wordpress와 같은 응용 프로그램 이미지를 사용할 수도 있고, ubuntu, debian, rockylinux, alpine과 같이 다른 이미지를 만들 때 주로 사용하는 리눅스 배포판 이미지를 사용할 수도 있습니다. python, ruby, node, golang과 같이 프로그래밍 언어를 실행할 수 있는 이미지도 있습니다. 공식 이미지 이외에도 사용자들이 직접 업로드한 써드파티 이미지를 사용할 수도 있습니다.

nginx 웹 서버를 제공하는 nginx이미지를 사용하고 싶다면, IMAGE 부분을 nginx로 바꿔줍니다. 이는 가장 심플하고, 실제로 동작하는 docker run 명령어입니다.

$ docker run nginx

이미지 이름은 고유한 형식을 가지고 있습니다. nginx라는 하나의 이미지 이름은 Docker Hub에서 하나의 이미지 저장소와 1:1로 매칭됩니다. 하지만 nginx 이미지 저장소에는 다수의 이미지가 업로드 되어있습니다. 이 때 저장소의 이미지들을 구분해주는 게 바로 태그입니다. 태그는 :로 구분합니다. nginx라는 이미지 이름에는 태그가 명시되어있지 않습니다. 이럴 때는 암묵적으로 latest 태그를 지정한 것과 같습니다. 따라서 nginx는 nginx:latest와 같습니다.

$ docker run nginx:latest

Docker Hub의 nginx 저장소에서는 그 이외에도 다양한 이미지(태그)를 제공하고 있습니다.

nginx - Official Image | Docker Hub

공식 이미지가 아닌 경우에는 이미지 이름에 계정명이 붙습니다. 예를 들어 lainyzine 사용자가 제공하는 nginx 이미지는 laniyzine/nginx가 됩니다. 그리고 앞에서 배운대로 태그를 지정하지 않는다면 laniyzine/nginx는 lainyzine/nginx:latest를 의미합니다.

또 한 가지 알아두어야할 점은, 이미지가 반드시 Docker Hub와 연동되어있지는 않다는 점입니다. 로컬에서 이미지를 직접 빌드할 때는 아무 이름이나 붙일 수 있습니다. 예를 들어 로컬에서 nginx:latest라고 이름 붙이고 사용해도 아무 제약이 없습니다.

$ docker build -t nginx:latest .

하지만 이 이미지는 Docker Hub에서 제공하는 nginx:latest 이미지는 아닙니다.

이미지는 Docker Hub에서 찾아보거나 docker search 명령어로 검색해볼 수 있습니다. 또한 quay.io와 같은 외부 이미지 저장소에서 이미지를 풀 받아 사용하는 것도 가능합니다. 하지만 Docker나 리눅스 환경에 익숙하지 않다면 가능하면 도커에서 제공하는 공식 이미지를 사용하는 게 안전합니다.

Docker Hub와 Docker 공식 이미지에 대해서는 다음 글에서 더 상세히 소개합니다.

관련 글: Docker Hub와 Docker 공식 이미지의 이해

docker run = pull + create + start

docker run은 사실 3개의 명령어가 합쳐진 명령어라고 볼 수도 있습니다. 다음 명령어를 실행한다고 가정해보겠습니다.

$ docker run nginx

먼저 Docker는 로컬에서 이미지를 찾아보고 없으면 Docker Hub에서 이미지를 찾아 풀 받습니다. 즉, docker pull로 nginx:latest이미지를 풀 받습니다.

$ docker pull nginx

그리고 이 nginx 이미지로 컨테이너를 생성합니다. docker create 명령어로 컨테이너를 생성할 수 있습니다. 이 명령어는 생성한 컨테이너 ID 값을 출력합니다.

$ docker cerate nginx
<CONTAINER_ID>

마지막으로 이렇게 생성된 컨테이너를 시작합니다. 생성되어있는 컨테이너는 docker start 명령으로 시작할 수 있습니다.

$ docker start <CONTAINER_ID>

이 명령어들을 합쳐서 docker run 하나로 사용할 수 있습니다. docker create와 docker start를 따로 사용하는 경우는 일반적이진 않습니다만, 도커에서는 컨테이너 생성과 시작이 구분되어있습니다. docker run 명령어는 생성과 시작을 한꺼번에 해주는 명령어입니다. 실제로 docker run과 docker create의 옵션은 거의 같습니다.

`docker run` 명령어와 옵션

docker run 명령어는 옵션 없이는 거의 사용할 수 없다고 해도 과언이 아닙니다. 그리고 옵션도 매우 다양합니다. 여기서는 중요하고 많이 사용하는 옵션들부터 설명하도록 하겠습니다. docker run의 모든 옵션을 다 알 필요는 없습니다. 대부분의 케이스는 아래에서 설명하는 옵션들로 충분히 활용할 수 있습니다.

아주 가끔씩 사용되는 옵션들도 있습니다. 이럴 때는 공식 문서의 docker run 레퍼런스 문서를 참고해주시기 바랍니다.

`--name` 옵션: 컨테이너 이름 지정

--name을 사용하면 컨테이너에 이름을 직접 붙일 수 있습니다. 이 옵션은 컨테이너 이름을 인자로 받습니다.

--name <CONTAINER_NAME>

예를 들어 다음과 같이 실행하면, 새로 실행된 컨테이너의 이름은 my-nginx가 됩니다.

$ docker run -d --name my-nginx nginx

맨 뒤의 NAMES 값을 보면 이름이 my-nginx인 것을 확인할 수 있습니다.

$ docker ps
CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS        PORTS     NAMES
7ad0404c665d   nginx     "/docker-entrypoint.…"   2 seconds ago   Up 1 second   80/tcp    my-nginx

Docker에서는 컨테이너 ID나 컨테이너 이름으로 특정 컨테이너를 조작할 수 있습니다. 예를 들어서 방금 실행한 컨테이너를 종료하고 삭제하고 싶다면 다음과 같이 실행할 수 있습니다.

$ docker rm -f my-nginx

--name 옵션을 사용하지 않으면 Docker가 이름을 임의로 붙여줍니다.

$ docker run -d nginx

$ docker ps
CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS         PORTS     NAMES
ba8168618de3   nginx     "/docker-entrypoint.…"   4 seconds ago   Up 3 seconds   80/tcp    nice_kirch

여기서는 nice_kirch라는 이름이 붙었습니다. 이 이름으로 컨테이너를 조작할 수 있지만, 이름만으로는 용도나 의미를 알기 어렵습니다. --name 옵션을 적극 활용하면, 좀 더 편리하게 도커 컨테이너를 활용할 수 있습니다.

관련 글: Docker 컨테이너 이름 지정 및 변경

`-it` 옵션: STDIN과 TTY

docker run을 사용하면서 가장 많이 사용하지만 아리송한 옵션이 바로 -it 옵션입니다. 특히 리눅스 배포판 이미지에서 셸을 실행할 때는 필수적으로 사용합니다.

먼저 리눅스에 익숙하지 않다면, 이 옵션이 하나인지 두 개인지부터 헷갈립니다. -it 옵션은 -i와 -t 옵션 두개를 의미합니다. 리눅스에서는 한 글자 옵션들을 - 다음에 연결해서 한꺼번에 지정할 수 있습니다.

관련 글: 리눅스 명령어 형식과 옵션 이해하기

-i 옵션은 --interactive 옵션과 같으며, 명령어를 실행하고 나서 STDIN으로 키보드 입력을 전달하겠다는 의미입니다. 그리고 -t 옵션은 --tty와 같으며 가상 TTY(pseudo-TTY)를 할당하는 옵션입니다.

직접 실행해보면서 옵션의 기능을 확인해보겠습니다. 먼저 -it 옵션 없이 alpine 이미지에서 sh 명령어를 실행해보겠습니다. 여기서 alpine:latest는 이미지, sh는 실행할 명령어입니다.

$ docker run alpine:latest sh
$

이렇게 실행하면, 그냥 바로 종료되어 버립니다. 그럼 이번에는 -i 옵션을 붙여보겠습니다. -i 옵션을 사용하면 STDIN으로 키보드 입력을 전달할 수 있습니다.

$ docker run -i alpine:latest sh
<입력 대기 중>

whoami를 입력하고 엔터를 입력합니다.

whoami
root

root라는 값이 자동으로 출력됩니다. 프롬프트는 없지만 셸이 동작중인 것을 알 수 있습니다. 다른 명령어들도 실행해보시기 바랍니다. 이렇게도 셸을 사용할 수는 있습니다만, 뭔가 어색하고 불완전해 보입니다. exit를 실행하면 컨테이너 셸이 종료됩니다.

그럼 -t만 옵션을 사용해보겠습니다. 이번에는 난이도가 상당히 높습니다. 이 명령어를 실행하기 전에 다른 터미널을 하나 더 실행해서 컨테이너를 중지할 준비를 해주세요.

$ docker run --name broken-sh -t alpine:latest sh
/ #

이번에는 정상적으로 컨테이너 셸이 실행되고, 프롬프트도 변경된 걸로 보입니다. 하지만 명령어를 입력해도 화면에 출력될 뿐, 셸에 전달되지 않습니다. exit 명령어나 ^D 키조차 안 먹어서 심지어 셸을 종료할 수조차 없습니다. 미리 준비한 다른 터미널에서 컨테이너를 종료해주세요.

$ docker rm -f broken-sh

앞에서 -t 옵션은 가상 TTY를 할당한다고 설명했습니다, 정확한 원리까지 아실 필요는 없습니다만 셸은 TTY를 통해서 사용자와 통신한다는 정도만 기억해주세요. 모르셔도 괜찮습니다. 그냥 셸을 사용할 때는 -it 옵션을 사용해주세요.

$ docker run -i -t alpine:latest sh
/ # whoami
root
/ #

-it 옵션을 사용하면, 항상 그래왔듯이 정상적으로 컨테이너 셸을 사용할 수 있습니다.

아주 엄밀하게 따지면, 셸을 사용하는 경우가 아니면 -t 옵션은 사용하지 않아도 됩니다. 하지만 docker run으로 포그라운드에서 명령어를 실행하는 경우 -it 옵션을 사용하는 걸 추천 드립니다.

`-d`, `--detach`: 컨테이너를 백그라운드에서 실행

-it 옵션과 함께 많이 사용하는 옵션이 바로 -d 옵션입니다. -d 혹은 --detach 옵션은 실행한 컨테이너 ID를 출력하고, 백그라운드에서 컨테이너를 실행합니다. -it 옵션은 포그라운드에서 컨테이너를 실행할 때, -d 옵션은 백그라운드에서 컨테이너를 실행할 때 사용한다고 기억해주세요. 그리고 -it 옵션과 -d 옵션은 같이 사용하지 않습니다. -d 옵션은 주로 장시간 돌아가는 배치 스크립트나 서버 애플리케이션을 실행할 때 사용합니다.

$ docker run -d --name my-nginx nginx:latest
d100c429c9428ac33641b0ea74b30b4e2d1480269d4da1bf1c8c47e8d8ee3b93

--name 옵션에 지정한 이름이나, 출력된 컨테이너 ID를 사용해 컨테이너를 조작할 수 있습니다. -d 옵션을 사용하는 경우 컨테이너의 출력이 화면에 나타나지 않기 때문에 제대로 실행되었는지 알 수 없습니다. docker ps나 docker logs로 상태를 확인하는 게 일반적입니다.

$ docker ps
CONTAINER ID   IMAGE           COMMAND                  CREATED          STATUS                  PORTS     NAMES
d100c429c942   nginx:latest    "/docker-entrypoint.…"   2 seconds ago    Up Less than a second   80/tcp    my-nginx

$ docker logs my-nginx
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
[...]
2023/07/12 16:50:15 [notice] 1#1: start worker process 30
2023/07/12 16:50:15 [notice] 1#1: start worker process 31

STATUS와 로그 내용을 보고 정상적으로 실행중인 것을 확인할 수 있습니다.

`--rm`: 컨테이너 종료시 삭제

--rm 옵션은 컨테이너를 포그라운드로 실행할 때 주로 사용합니다. 이 옵션은 실행한 컨테이너가 종료되면 컨테이너를 삭제합니다.

$ docker run -it --rm debian:12 uname -a
Linux 9e6d1a877156 5.15.90.1-microsoft-standard-WSL2 #1 SMP Fri Jan 27 02:56:13 UTC 2023 x86_64 GNU/Linux

$ docker ps
CONTAINER ID   IMAGE    COMMAND    CREATED    STATUS    PORTS    NAMES

위 명령어를 실행하면 uname -a 명령어가 실행되고, 컨테이너가 종료 됩니다. --rm 옵션을 사용했기 때문에 종료와 함께 컨테이너가 삭제되었습니다. 컨테이너와 프로세스는 거의 동의어지만, 약간의 차이가 있습니다. 컨테이너는 프로세스 자체를 지칭하기도 하지만, 메타데이터와 로그와 같은 추가적인 정보를 가지고 있는 더 넓은 의미로 사용되기도 합니다. 따라서 docker run으로 실행한 컨테이너(=프로세스)가 종료되더라도, 명시적으로 삭제하기 전까지 컨테이너는 남아있습니다.

앞에서 이야기한대로 --rm 명령어는 주로 일회성으로 사용하는 포그라운드 컨테이너를 실행할 때 자주 사용합니다. 반대로 -d 옵션을 사용해서 백그라운드에서 컨테이너를 실행하는 경우에는 이 옵션을 사용하지 않는 것을 추천 드립니다. 컨테이너가 비정상적으로 종료된 경우, 이를 디버깅하기 위해서는 로그나 컨테이너 메타데이터와 같은 정보가 필요합니다. 그런데 --rm 옵션을 사용해버리면, 언제 종료되었는지도 알 수 없고, 어떻게 종료되었는지 로그도 확인할 수 없습니다.

`-e`, `--env`: 환경변수 지정

-e, --env 옵션은 컨테이너를 실행할 때 환경변수를 지정합니다. 리눅스에서는 환경변수로 애플리케이션 동작을 제어하는 경우가 많이 있습니다. 예를 들어 리눅스 셸에서 env 명령어를 실행해보면, 현재 셸 세션에 정의된 모든 환경변수를 확인할 수 있습니다.

env

간단한 예제로 -e 옵션을 사용해 컨테이너에 환경변수를 지정해보겠습니다.

$ docker run -it -e HELLOENV=WORLD debian:12 bash
root@46c311a5c9b4:/# env | grep HELLO
HELLOENV=WORLD

-e 옵션으로 지정한 HELLOENV 환경변수를 env 명령어로 확인할 수 있습니다. 예제에서 확인할 수 있듯이 환경변수는 키=밸류 형식을 사용합니다. 이 때 키는 관습적으로 대문자만 사용합니다. 스페이스를 포함하는 등 값이 복잡한 경우 키=밸류 전체를 따옴표로 감싸서 사용할 수 있습니다.

$ docker run -it -e "HELLOENV=some complex value" debian:12 bash
root@8cb904204138:/# env | grep HELLO
HELLOENV=some complex value

환경변수가 그 자체로 어떤 의미를 가지는 것은 아닙니다. 이미지나 애플리케이션에 특정 환경변수 값을 처리하도록 미리 구현 되어있어야합니다. 예를 들어 MySQL 공식 이미지에서는 MYSQL_ROOT_PASSWORD 환경 변수로 루트 사용자 패스워드를 지정할 수 있습니다.

$ docker run -p 3306:3306 -e MYSQL_ROOT_PASSWORD=mysql-password -d mysql:8.0

환경변수로 간단한 설정값들을 전달하는 방식은 Docker 이미지를 만들 때 많이 사용되는 패턴 중 하나입니다. 아주 긴 docker run 명령어를 보면, 대부분은 환경변수를 지정하는 -e 옵션이 사용되는 것을 확인할 수 있습니다.

다음은 wordpress 이미지를 실행할 때 데이터베이스 연결 설정을 환경변수로 정의하는 docker run 명령어 예제입니다.

$ docker run -d \
  --name wordpress \
  -p 3000:80 \
  -e "WORDPRESS_DB_HOST=mysql:3306" \
  -e "WORDPRESS_DB_USER=wordpress" \
  -e "WORDPRESS_DB_PASSWORD=awesome-wordpress-password"
  wordpress:latest

`-w`, `--workdir`: 작업 디렉터리 변경

-w, --workdir 옵션은 컨테이너를 실행할 때 작업 디렉터리를 변경하는 명령어입니다. 이미지에 지정된 기본값을 덮어씁니다. 예시로 debian:12 이미지에서 pwd를 실행해보겠습니다.

$ docker run -it debian:12 pwd
/

현재 디렉터리는 /(루트)입니다. 이번에는 -w /tmp를 지정해서 실행해보겠습니다.

$ docker run -it -w /tmp debian:12 pwd
/tmp

작업 디렉터리가 /tmp로 변경된 것을 확인할 수 있습니다.

`--network`: 컨테이너의 네트워크 지정

컨테이너의 네트워크를 지정합니다. 도커에서는 docker network ls 명령어를 사용해, 컨테이너에 지정 가능한 네트워크를 확인할 수 있습니다. 기본적으로 birdge, host, none 3개의 네트워크가 제공됩니다. 따로 지정하지 않으면 호스트의 docker0 브릿지를 사용하는 브릿지 네트워크가 사용됩니다.

$ docker network ls
NETWORK ID     NAME      DRIVER    SCOPE
ba9a8023c78d   bridge    bridge    local
17d9b4ad6c78   host      host      local
8162fb961f40   none      null      local

bridge: 컨테이너에 호스트의 docker0 브릿지에 연결된 네트워크 인터페이스를 생성하고 이를 통해 외부와 통신합니다.
host: 호스트의 네트워크를 그대로 사용합니다. 예를 들어 80포트를 컨테이너로 열면, -p 옵션이 없어도 호스트의 80포트가 사용됩니다.
none: 외부(혹은 호스트)와 연결되지 않은 고립된 컨테이너를 생성합니다.

일반적으로는 특별한 이유가 없다면 기본값(bridge)를 사용합니다. 이 방식을 사용하면 외부에 노출되는 포트를 -p 옵션으로 제어할 수 있습니다. 특수한 용도나 네트워크 디버깅을 할 때 host를 사용하기도 하지만, 권장하지는 않습니다. 이 방식은 컨테이너 네트워크가 격리되어있지 않다는 의미이기도 합니다. 아래 예제는 nginx 컨테이너를 host 네트워크로 실행합니다. 호스트의 80 포트로 nginx 서버에 접속할 수 있습니다.

$ docker run -d --network host nginx

도커의 네트워크 기능을 사용하면, 직접 네트워크를 생성해서 지정하는 것도 가능합니다.

`-p`, `--publish`: 호스트와 포트 연결

-p 혹은 --publish 옵션은 브릿지 네트워크를 사용할 때 호스트 포트와 컨테이너 포트를 연결하는 용도로 사용합니다. 아래 그림에서와 같이 이 옵션을 8080:80으로 지정하면 호스트의 8080 포트와 컨테이너의 80 포트를 연결할 수 있습니다. 호스트와 컨테이너를 연결하는 포트포워딩 기능입니다.

기본적으로 -p 옵션은 호스트의 0.0.0.0 IP로 연결됩니다. PORTS 값이 0.0.0.0:8000->80/tcp으로 지정된 것을 확인할 수 있습니다.

$ docker run -d -p 8000:80 nginx:alpine

$ docker ps
CONTAINER ID   IMAGE           COMMAND                  CREATED         STATUS         PORTS                  NAMES
6b5775436307   nginx:alpine    "/docker-entrypoint.…"   3 seconds ago   Up 2 seconds   0.0.0.0:8000->80/tcp   suspicious_sanderson

기본적으로 tcp를 사용하지만 맨 뒤에 /udp와 같이 통신 방식을 지정할 수 있습니다.

직접 IP 값를 직접 지정하는 것도 가능합니다. 이때는 IP:HOST_PORT:CONTAINER:PORT 형식을 사용합니다.

$ docker run -d -p 127.0.0.1:8001:80 nginx:alpine
$ docker ps
CONTAINER ID   IMAGE           COMMAND                  CREATED         STATUS         PORTS                    NAMES
1082c88d1edd   nginx:alpine    "/docker-entrypoint.…"   3 seconds ago   Up 2 seconds   127.0.0.1:8001->80/tcp   tender_hoover
6b5775436307   nginx:alpine    "/docker-entrypoint.…"   2 minutes ago   Up 2 minutes   0.0.0.0:8000->80/tcp     suspicious_sanderson

예를 들어 이 예제와 같이 127.0.0.1을 지정하면, 이 주소로만 접근이 가능하기 때문에 호스트 머신에서만 nginx 서버에 접속할 수 있습니다. 반면에 기본값인 0.0.0.0을 지정하는 경우(기본값), 호스트 포트로 외부에서도 접근할 수 있습니다.

`-v`, `--volume`: 호스트 디렉터리나 도커 볼륨 마운트

-v, --volume 옵션은 호스트의 특정 디렉터리나 도커 뷸름을 컨테이너에 마운트할 때 사용합니다. 예를 들어 다음 예제에서는 docker 명령어를 실행하는 현재 디렉터리를 컨테이너의 /data/ 디렉터리에 마운트합니다. 이를 통해 호스트의 데이터를 컨테이너에 전달하거나, 컨테이너의 작업 내용을 호스트로 가져올 수 있습니다.

$ docker run -it --rm -v $(pwd):/data linuxserver/ffmpeg:latest

아래 그램에서, $(pwd)는 /home/lainyzine/docker/ffmpeg 디렉터리로 치환됩니다.

호스트의 디렉터리가 아닌, 자체적으로 관리되는 Docker 볼륨을 만들어서 사용할 수도 있습니다. 이 때는 호스트 디렉터리의 경로 대신, 볼륨 이름을 지정해서 사용합니다. 도커 볼륨을 하나 만들어서 테스트해보겠습니다.

$ docker volume create my-data
$ docker volume ls
DRIVER    VOLUME NAME
local     my-data

아래 예제는 my-data 볼륨에 파일을 추가하고, 다른 컨테이너에서 my-data를 다시 마운트해서 앞에서 만든 파일이 있는지 확인하는 예제입니다.

$ docker run -it --name container1 -v my-data:/data debian:12
contaienr1 $ cd /data
container1 $ touch data1 data2 data3
container1 $ exit

$ docker run -it --name container2 -v my-data:/data ubuntu:lunar
contanier2 $ cd /data
contanier2 $ ls
data1  data2  data3

이 옵션을 사용할 때 읽기/쓰기 권한을 컨트롤할 수 있습니다. 아래는 읽기/쓰기 권한을 지정해서 옵션을 사용하는 예제입니다.

-v /tmp:/data:ro
-v /tmp:/data:rw

읽기/쓰기 권한은 맨 뒤에 :으로 구분해서 지정해줍니다. 기본값은 rw(읽기/쓰기 가능)이며, 컨테이너에서 읽기만 가능하도록 설정하려면 ro를 붙여줍니다.

`--volumes-from`: 다른 컨테이너에서 볼륨 마운트

--volumes-from은 다른 컨테이너에 마운트 된 불륨을 가져다 사용하는 기능입니다. 이 옵션에는 특정 컨테이너를 지정합니다. 앞의 --volume 옵션에서 만든 my-data를 사용해보겠습니다.

$ docker run -it --name volume-test -v my-data:/data debian:12
volume-test $ cd /data
volume-test $ ls
data1  data2  data3
volume-test $ exit

$ docker run -it --name container4 --volumes-from volume-test ubuntu:lunar
container4 $ cd /data
container4 $ ls
data1  data2  data3

volume-test 컨테이너는 종료 상태로 남아있습니다. 이 상태에서 conatiner4에서 volumes-from 옵션으로 volume-test 컨테이너의 마운트 정보를 가져왔습니다. /data 디렉터리에 volume-test 컨테이너에 마운트한 my-data 볼륨의 데이터를 확인할 수 있습니다.

`--entrypoint`: Entrypoint 덮어쓰기

도커 이미지를 빌드할 때, 이미지의 기본 명령어를 지정하기 위한 방법이 CMD와 ENTRYPOINT 두 가지가 있습니다. 기본 명령어를 지정하는 CMD는 docker run 맨 뒤에 명령어를 지정해서 쉽게 덮어쓸 수 있습니다. 반면에 ENTRYPOINT를 사용하는 경우, 이미지에서 기본적으로 실행되는 명령어가 강제되기 때문에 docker run 맨 뒤에 명령어를 지정해도, ENTRYPOINT에 지정된 명령어가 실행됩니다. 예제로 확인해보겠습니다.

$ docker run -it --rm linuxserver/ffmpeg:latest whoami
ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers
[...]

분명히 whoami 명령어를 지정했지만, ffmpeg이 실행된 것을 확인할 수 있습니다. 정확한 명령어는 inspect로 확인해야합니다만, 위 명령어는 ffmpeg whoami 이렇게 실행한 것과 마찬가지입니다. 이 이미지에서 다른 명령어를 실행하고 싶다면 ENTRYPOINT 값 자체를 덮어써야합니다. 이럴 때 --entrypoint 옵션을 사용합니다.

$ docker run -it --rm --entrypoint whoami linuxserver/ffmpeg:latest
root

이번에는 의도한대로 whoami 명령어가 실행되었습니다.

`-h`, `--host`: 호스트 이름 지정

-h 혹은 --host 옵션으로 컨테이너의 호스트 이름을 지정할 수 있습니다. 기본적으로 컨테이너 ID의 일부가 호스트 이름으로 사용됩니다. 아래 예제를 통해서 확인해보겠습니다. hostname 명령어는 호스트 이름을 출력합니다.

$ docker run -it --rm alpine:latest hostname
fa30c83e0967

-h 옵션으로 호스트 이름을 변경하고 확인해봅니다.

$ docker run -it --rm -h lainyzine-container alpine:latest hostname
lainyzine-container

`--dns`: DNS 서버 지정

리눅스에서는 resolv.conf에서 DNS 서버 설정을 관리합니다. 그리고 Docker에서는 이 파일을 컨테이너 실행 시에 생성하고 직접 관리합니다. 컨테이너를 실행해서 설정 파일을 확인해보겠습니다.

$ docker run -it --rm alpine:latest
alpine $ cat /etc/resolv.conf
# DNS requests are forwarded to the host. DHCP DNS options are ignored.
nameserver 192.168.65.7
root@1f2cba1c4f30:/# exit

주석에서 설명하는대로 Docker 컨테이너에서는 기본적으로 DNS 요청을 호스트로 포워딩해서 처리합니다. --dns 옵션을 지정하면, 컨테이너에서 사용하는 DNS 서버를 강제로 지정할 수 있습니다. 예를 들어 CloudFlare에서 제공하는 1.1.1.1을 사용하고 싶다면 다음과 같이 사용합니다.

$ docker run -it --dns 1.1.1.1 alpine:latest
alpine $ cat /etc/resolv.conf
nameserver 1.1.1.1

/etc/resolv.conf 파일에 1.1.1.1이 지정된 것을 확인할 수 있습니다. nslookup 명령어를 실행해보면 1.1.1.1로 DNS 쿼리를 보냅니다.

$ nslookup lainyzine.com
Server:         1.1.1.1
Address:        1.1.1.1:53

Non-authoritative answer:
[...]

`-l`, `--label`: 컨테이너에 메타데이터 지정

-l 혹은 --label 옵션은 컨테이너에 메타데이터를 지정하는 옵셥입니다. 이 옵션에는 인자로 키를 지정하거나 키=밸류 형식으로 메타데이터를 지정할 수 있습니다. 아래는 --label 옵션을 사용하는 예제입니다.

$ docker run -d --label linux=ubuntu ubuntu:latest sleep 1000
$ docker run -d --label linux=debian debian:12.0 sleep 1000

이 정보는 컨테이너에 저장됩니다. docker ps로 컨테이너 목록을 출력할 때 이 값으로 필터링을 할 수 있습니다.

$ docker ps --filter "label=linux=ubuntu"
CONTAINER ID   IMAGE           COMMAND        CREATED          STATUS          PORTS     NAMES
96543948ddde   ubuntu:latest   "sleep 1000"   30 seconds ago   Up 29 seconds             peaceful_mclaren

목록에 linux=ubuntu를 지정한 컨테이너만 출력됩니다.

메타데이터는 컨테이너 동작을 변경하는 옵션은 아닙니다만, 다양한 용도로 사용할 수 있습니다. 하나 주의할 점은, 이 옵션이 컨테이너 생성 시에만 사용할 수 있다는 점입니다. 이미 생성된 컨테이너의 메타데이터를 변경하는 것은 불가능합니다.

`--restart`: 컨테이너 종료 시 재시작 정책 설정

--restart 옵션으로 컨테이너의 종료 시 재시작 정책을 지정할 수 있습니다. 지정할 수 있는 값들은 다음과 같습니다.

no: 컨테이너 종료 시 재시작을 하지 않습니다. 기본값입니다.
on-failure:n: exit 코드가 0이 아닌 경우 최대 n번 재시작을 시도합니다. n은 숫자로 지정합니다.
unless-stopeped: 명시적으로 컨테이너를 종료했거나, Docker 자체가 중지되거나 재시작 되는 경우가 아니라면 컨테이너를 재시작합니다.
always: exit 코드에 상관없이 컨테이너가 종료되면 항상 재시작합니다.

리눅스에서는 프로세스가 종료할 때 exit 코드를 반환합니다. 이 값이 0이면 정상적으로 종료되었다는 의미입니다. 예를 들어 on-failure:n 옵션의 경우 컨테이너가 실행에 실패하는 경우(exit 코드가 0이 아닌 경우), 최대 n번까지 재시도하는 정책입니다. 최대 3번을 재시작하려면 다음과 같이 사용할 수 있습니다.

$ docker run -d --restart on-failure:3 batch_job:latest

Docker로 서버 애플리케이션을 실행하는 경우, 항상 재시작하는 always 옵션이 유용합니다. 서버 애플리케이션은 어떤 원인에 의해서 종료될 수 있지만, 서버에 접속 가능한 상태를 유지하는 게 더 중요할 때 이 옵션을 사용합니다.

$ docker run -d -p 8080:80 --restart alawys nginx:latest

추천 문서

이 글에서는 docker run을 사용할 때 자주 사용하는 옵션들을 위주로 설명했습니다만, 이외에도 다양한 옵션들이 있습니다. 이 정도만 알아도 Docker를 활용하는 데는 충분합니다만, 시스템 자원 할당과 관련된 옵션이나 권한 관련 옵션은 가끔씩 사용하는 경우가 있습니다. 처음 보거나 잘 모르는 옵션을 만나면 레퍼런스 문서들을 참고해주세요.

그 외에 Docker 관련 글들은 다음 문서에 정리하고 있습니다.

개발자를 위한 Docker 사용법 총 정리

docker run 사용법: 컨테이너 실행

댓글