docker

Docker CLI의 기본 명령이에요. 모든 docker 명령을 포함하며, 환경 변수, 구성 파일(config.json), 옵션 타입, 데몬 호스트 지정 등을 다뤄요.

출처: 문서

본문

설명: Docker CLI의 기본 명령.

Docker 시스템 구성에 따라 각 docker 명령 앞에 sudo를 붙여야 할 수 있어요. docker 명령에 sudo를 사용하지 않으려면 시스템 관리자가 docker라는 Unix 그룹을 만들고 사용자를 그 그룹에 추가하면 돼요.

Docker 설치나 sudo 구성에 대한 자세한 내용은 운영 체제의 설치 지침을 참조하세요.

도움말 텍스트 표시

어떤 명령이든 --help 옵션을 붙여 실행하면 해당 명령의 도움말을 나열해요.

$ docker run --help

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

Create and run a new container from an image

Options:
      --add-host value             Add a custom host-to-IP mapping (host:ip) (default [])
  -a, --attach value               Attach to STDIN, STDOUT or STDERR (default [])

환경 변수

다음 환경 변수는 docker 명령줄 클라이언트의 동작을 제어해요.

변수	설명
`DOCKER_API_VERSION`	디버깅용으로 협상할 API 버전 재정의 (예: `1.19`)
`DOCKER_CERT_PATH`	인증 키의 위치. `docker` CLI와 `dockerd` 데몬 모두가 사용
`DOCKER_CONFIG`	클라이언트 구성 파일의 위치
`DOCKER_CONTEXT`	사용할 `docker context`의 이름 (`DOCKER_HOST` 환경 변수와 `docker context use`로 설정한 기본 컨텍스트를 재정의)
`DOCKER_CUSTOM_HEADERS`	(실험적) 클라이언트가 보낼 커스텀 HTTP 헤더 구성. 헤더는 `name=value` 쌍의 쉼표로 구분된 목록으로 제공해야 함. 구성 파일의 `HttpHeaders` 필드와 동일
`DOCKER_DEFAULT_PLATFORM`	`--platform` 플래그를 받는 명령의 기본 플랫폼
`DOCKER_HIDE_LEGACY_COMMANDS`	설정 시 Docker는 `docker help` 출력에서 "legacy" 최상위 명령(예: `docker rm`, `docker pull`)을 숨기고 객체 유형별 `Management commands`(예: `docker container`)만 표시함. 향후 릴리스에서 기본이 될 수 있음
`DOCKER_HOST`	연결할 데몬 소켓
`DOCKER_TLS`	`docker` CLI가 만드는 연결에 TLS 활성화 (`--tls` 명령줄 옵션과 동일). 비어 있지 않은 값으로 설정하면 TLS 활성화. 다른 TLS 옵션이 하나라도 설정되면 TLS가 자동으로 활성화됨
`DOCKER_TLS_VERIFY`	설정 시 Docker는 TLS를 사용하고 원격을 검증. `docker` CLI와 `dockerd` 데몬 모두가 사용
`BUILDKIT_PROGRESS`	BuildKit 백엔드로 빌드할 때 진행 출력 유형 설정 (`auto`, `plain`, `tty`, `rawjson`). 컨테이너 출력을 표시하려면 plain 사용 (기본 `auto`)
`NO_COLOR`	https://no-color.org/ 에 따라 출력에서 모든 ANSI 이스케이프 코드 비활성화

Docker는 Go로 개발되므로 Go 런타임이 사용하는 어떤 환경 변수도 사용할 수 있어요. 특히 다음이 유용할 수 있어요.

변수	설명
`HTTP_PROXY`	NoProxy가 재정의하지 않는 한 HTTP 요청의 프록시 URL
`HTTPS_PROXY`	NoProxy가 재정의하지 않는 한 HTTPS 요청의 프록시 URL
`NO_PROXY`	프록시에서 제외해야 하는 호스트를 지정하는 쉼표로 구분된 값

이 변수들에 대한 자세한 내용은 Go 스펙을 참조하세요.

옵션 타입

단일 문자 명령줄 옵션은 결합할 수 있어요. docker run -i -t --name test busybox sh 대신 docker run -it --name test busybox sh라고 쓸 수 있어요.

Boolean

Boolean 옵션은 -d=false 형태를 가져요. 도움말 텍스트에 보이는 값은 해당 플래그를 지정하지 않을 때 설정되는 기본값이에요. 값 없이 Boolean 플래그를 지정하면 기본값과 무관하게 플래그가 true로 설정돼요.

예를 들어 docker run -d를 실행하면 값이 true로 설정되어 컨테이너가 백그라운드의 "detached" 모드로 실행돼요.

기본값이 true인 옵션(예: docker build --rm=true)은 명시적으로 false로 설정해야만 비기본값으로 설정할 수 있어요.

$ docker build --rm=false .

Multi

-a=[] 같은 옵션을 단일 명령줄에서 여러 번 지정할 수 있어요. 예:

$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash

$ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls

때로 여러 옵션이 -v처럼 더 복잡한 값 문자열을 요구할 수 있어요.

$ docker run -v /host:/container example/mysql

Note pty 구현의 제한 때문에 -t와 -a stderr 옵션을 함께 사용하지 마세요. pty 모드에서 모든 stderr는 그냥 stdout으로 감.

Strings and Integers

--name="" 같은 옵션은 문자열을 기대하며 한 번만 지정할 수 있어요. -c=0 같은 옵션은 정수를 기대하며 한 번만 지정할 수 있어요.

구성 파일

기본적으로 Docker 명령줄은 $HOME 디렉터리 안의 .docker라는 디렉터리에 구성 파일을 저장해요.

Docker는 구성 디렉터리의 대부분의 파일을 관리하므로 수정하면 안 돼요. 하지만 config.json 파일을 수정해 docker 명령이 동작하는 특정 측면을 제어할 수 있어요.

환경 변수나 명령줄 옵션으로 docker 명령 동작을 수정할 수 있어요. config.json 안의 옵션으로 같은 동작 중 일부를 수정할 수도 있어요. 환경 변수와 --config 플래그가 모두 설정되면 플래그가 환경 변수보다 우선해요. 명령줄 옵션은 환경 변수를, 환경 변수는 config.json 파일에 지정한 속성을 재정의해요.

.docker 디렉터리 변경

다른 디렉터리를 지정하려면 DOCKER_CONFIG 환경 변수나 --config 명령줄 옵션을 사용해요. 둘 다 지정하면 --config 옵션이 DOCKER_CONFIG 환경 변수를 재정의해요. 아래 예시는 ~/testconfigs/ 디렉터리의 config.json 파일을 사용해 docker ps 명령을 재정의해요.

$ docker --config ~/testconfigs/ ps

이 플래그는 실행 중인 명령에만 적용돼요. 영구 구성의 경우 셸(예: ~/.profile 또는 ~/.bashrc)에서 DOCKER_CONFIG 환경 변수를 설정할 수 있어요. 아래 예시는 새 디렉터리를 HOME/newdir/.docker로 설정해요.

$ echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile

Docker CLI 구성 파일 (config.json) 속성

Docker CLI 구성을 사용해 docker CLI의 설정을 커스터마이즈해요. 구성 파일은 JSON 형식을 사용하며 속성은 다음과 같아요.

기본적으로 구성 파일은 ~/.docker/config.json에 저장돼요. 다른 위치를 사용하려면 .docker 디렉터리 변경 섹션을 참조하세요.

Warning 구성 파일과 ~/.docker 구성 디렉터리의 다른 파일은 프록시 인증 정보나, 자격 증명 저장소에 따라 이미지 레지스트리 자격 증명 같은 민감한 정보를 포함할 수 있어요. 다른 사람과 공유하기 전에 구성 파일 내용을 검토하고, 파일을 버전 관리에 커밋하지 마세요.

명령의 기본 출력 형식 커스터마이즈

--format 플래그가 제공되지 않으면 다음 필드로 일부 명령의 기본 출력 형식을 커스터마이즈할 수 있어요.

속성	설명
`configFormat`	`docker config ls` 출력의 커스텀 기본 형식
`imagesFormat`	`docker images` / `docker image ls` 출력의 커스텀 기본 형식
`networksFormat`	`docker network ls` 출력의 커스텀 기본 형식
`nodesFormat`	`docker node ls` 출력의 커스텀 기본 형식
`pluginsFormat`	`docker plugin ls` 출력의 커스텀 기본 형식
`psFormat`	`docker ps` / `docker container ps` 출력의 커스텀 기본 형식
`secretFormat`	`docker secret ls` 출력의 커스텀 기본 형식
`serviceInspectFormat`	`docker service inspect` 출력의 커스텀 기본 형식
`servicesFormat`	`docker service ls` 출력의 커스텀 기본 형식
`statsFormat`	`docker stats` 출력의 커스텀 기본 형식
`tasksFormat`	`docker stack ps` 출력의 커스텀 기본 형식
`volumesFormat`	`docker volume ls` 출력의 커스텀 기본 형식

커스텀 HTTP 헤더

HttpHeaders 속성은 Docker 클라이언트에서 데몬으로 보내는 모든 메시지에 포함할 헤더 세트를 지정해요. Docker는 이 헤더를 해석하거나 이해하려 시도하지 않고 그냥 메시지에 넣어요. Docker는 이 헤더가 자체적으로 설정한 헤더를 변경하는 것을 허용하지 않아요.

대안으로 v27.1 이상에서 사용할 수 있는 DOCKER_CUSTOM_HEADERS 환경 변수를 사용할 수 있어요. 이 환경 변수는 실험적이며 정확한 동작이 바뀔 수 있어요.

자격 증명 저장소 옵션

credsStore 속성은 기본 자격 증명 저장소 역할을 하는 외부 바이너리를 지정해요. 이 속성이 설정되면 docker login은 $PATH에 보이는 docker-credential-이라는 바이너리에 자격 증명을 저장하려 시도해요. 이 속성이 설정되지 않으면 자격 증명은 CLI 구성 파일의 auths 속성에 저장돼요. 자세한 내용은 docker login 문서의 자격 증명 저장소 섹션을 참조하세요.

credHelpers 속성은 특정 레지스트리의 자격 증명을 저장하고 검색할 때 credsStore나 auths보다 우선적으로 사용할 자격 증명 헬퍼 세트를 지정해요. 이 속성이 설정되면 특정 레지스트리의 자격 증명을 저장/검색할 때 docker-credential- 바이너리가 사용돼요. 자세한 내용은 docker login 문서의 자격 증명 헬퍼 섹션을 참조하세요.

컨테이너 자동 프록시 구성

proxies 속성은 컨테이너에 자동으로 설정되고 docker build 중 사용되는 컨테이너에 --build-arg로 설정될 프록시 환경 변수를 지정해요. "default" 프록시 세트를 구성할 수 있으며, 클라이언트가 연결하는 모든 Docker 데몬에 사용되거나 호스트(Docker 데몬)별 구성(예: https://docker-daemon1.example.com)을 사용해요. 각 환경에 대해 다음 속성을 설정할 수 있어요.

속성	설명
`httpProxy`	컨테이너의 `HTTP_PROXY`와 `http_proxy` 기본값, `docker build`의 `--build-arg`
`httpsProxy`	컨테이너의 `HTTPS_PROXY`와 `https_proxy` 기본값, `docker build`의 `--build-arg`
`ftpProxy`	컨테이너의 `FTP_PROXY`와 `ftp_proxy` 기본값, `docker build`의 `--build-arg`
`noProxy`	컨테이너의 `NO_PROXY`와 `no_proxy` 기본값, `docker build`의 `--build-arg`
`allProxy`	컨테이너의 `ALL_PROXY`와 `all_proxy` 기본값, `docker build`의 `--build-arg`

이 설정은 컨테이너의 프록시 설정을 구성하는 데만 사용되며, docker CLI나 dockerd 데몬의 프록시 설정으로는 사용되지 않아요. CLI와 데몬의 프록시 설정 구성은 환경 변수 섹션과 Daemon 프록시 구성 가이드를 참조하세요.

Warning 프록시 설정은 민감한 정보를 포함할 수 있어요(예: 프록시가 인증을 요구하는 경우). 환경 변수는 컨테이너의 구성에 평문으로 저장되므로 원격 API를 통해 검사하거나 docker commit을 사용할 때 이미지에 커밋될 수 있어요.

컨테이너에서 분리하는 기본 키 시퀀스

컨테이너에 연결하면 사용자는 CTRL-p CTRL-q 키 시퀀스로 분리하고 실행을 계속하게 해요. 이 분리 키 시퀀스는 detachKeys 속성으로 커스터마이즈할 수 있어요. 속성에 값을 지정해요.의 형식은 문자 [a-Z]이거나, ctrl-과 다음 중 하나의 조합인 쉼표로 구분된 목록이에요.

a-z (단일 소문자 알파 문자)
@ (앳 기호)
[ (왼쪽 대괄호)
\\ (백슬래시 두 개)
_ (밑줄)
^ (캐럿)

커스터마이즈는 Docker 클라이언트로 시작한 모든 컨테이너에 적용돼요. 사용자는 docker attach, docker exec, docker run, docker start 명령에 --detach-keys 플래그를 지정해 컨테이너별로 커스텀 또는 기본 키 시퀀스를 재정의할 수 있어요.

CLI 플러그인 옵션

plugins 속성은 CLI 플러그인 특정 설정을 포함해요. 키는 플러그인 이름이며 값은 해당 플러그인 특정 옵션의 추가 맵이에요.

샘플 구성 파일

다음은 다양한 필드에 사용되는 형식을 보여주는 샘플 config.json 파일이에요.

{
  "HttpHeaders": {
    "MyHeader": "MyValue"
  },
  "psFormat": "table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.Labels}}",
  "imagesFormat": "table {{.ID}}\t{{.Repository}}\t{{.Tag}}\t{{.CreatedAt}}",
  "pluginsFormat": "table {{.ID}}\t{{.Name}}\t{{.Enabled}}",
  "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}",
  "servicesFormat": "table {{.ID}}\t{{.Name}}\t{{.Mode}}",
  "secretFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}",
  "configFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}",
  "serviceInspectFormat": "pretty",
  "nodesFormat": "table {{.ID}}\t{{.Hostname}}\t{{.Availability}}",
  "detachKeys": "ctrl-e,e",
  "credsStore": "secretservice",
  "credHelpers": {
    "awesomereg.example.org": "hip-star",
    "unicorn.example.com": "vcbait"
  },
  "plugins": {
    "plugin1": {
      "option": "value"
    },
    "plugin2": {
      "anotheroption": "anothervalue",
      "athirdoption": "athirdvalue"
    }
  },
  "proxies": {
    "default": {
      "httpProxy":  "http://user:[email protected]:3128",
      "httpsProxy": "https://my-proxy.example.com:3129",
      "noProxy":    "intra.mycorp.example.com",
      "ftpProxy":   "http://user:[email protected]:3128",
      "allProxy":   "socks://example.com:1234"
    },
    "https://manager1.mycorp.example.com:2377": {
      "httpProxy":  "http://user:[email protected]:3128",
      "httpsProxy": "https://my-proxy.example.com:3129"
    }
  }
}

실험적 기능

실험적 기능은 향후 제품 기능에 대한 조기 접근을 제공해요. 이 기능들은 테스트와 피드백을 위한 것이며, 경고 없이 릴리스 간에 바뀌거나 향후 릴리스에서 제거될 수 있어요.

Docker 20.10부터 실험적 CLI 기능은 기본으로 활성화되며 활성화하는 데 구성이 필요 없어요.

Notary

자체 notary 서버와 자체 서명 인증서 또는 내부 인증 기관을 사용한다면, 인증서를 Docker 구성 디렉터리의 tls//ca.crt에 배치해야 해요.

또는 인증서를 시스템의 루트 인증 기관 목록에 추가해 전역으로 신뢰할 수 있어요.

옵션

옵션	기본값	설명
`--config`	`/root/.docker`	클라이언트 구성 파일의 위치
`-c, --context`		데몬에 연결하는 데 사용할 컨텍스트 이름 (`DOCKER_HOST` 환경 변수와 `docker context use`로 설정한 기본 컨텍스트를 재정의)
`-D, --debug`		디버그 모드 활성화
`-H, --host`		연결할 데몬 소켓
`-l, --log-level`	`info`	로깅 수준 설정 (`debug`, `info`, `warn`, `error`, `fatal`)
`--tls`		TLS 사용; --tlsverify가 암시
`--tlscacert`	`/root/.docker/ca.pem`	이 CA가 서명한 인증서만 신뢰
`--tlscert`	`/root/.docker/cert.pem`	TLS 인증서 파일 경로
`--tlskey`	`/root/.docker/key.pem`	TLS 키 파일 경로
`--tlsverify`		TLS 사용 및 원격 검증

예시

데몬 호스트 지정 (-H, --host)

-H, --host 플래그를 사용해 docker 명령을 호출할 때 사용할 소켓을 지정할 수 있어요. 다음 프로토콜을 사용할 수 있어요.

스킴	설명	예시
`unix://[]`	Unix 소켓	`unix:///var/run/docker.sock`
`tcp://[[:port]]`	TCP 연결	`tcp://174.17.0.1:2376`
`ssh://***@][:port]`	SSH 연결	`ssh://[email protected]`
`npipe://[]`	명명된 파이프 (Windows 전용)	`npipe:////./pipe/docker_engine`

-H 플래그를 지정하지 않고 커스텀 컨텍스트를 사용하지 않으면 명령은 다음 기본 소켓을 사용해요.

macOS와 Linux에서 unix:///var/run/docker.sock
Windows에서 npipe:////./pipe/docker_engine

모든 명령에 -H 플래그를 지정하지 않고 비슷한 효과를 얻으려면 컨텍스트를 만들거나 대안으로 DOCKER_HOST 환경 변수를 사용할 수 있어요.

-H 플래그에 대한 자세한 내용은 Daemon 소켓 옵션을 참조하세요.

TCP 소켓 사용

다음 예시는 IP 주소 174.17.0.1, 포트 2376에서 수신 대기하는 원격 데몬에 TCP로 docker ps를 호출하는 방법을 보여줘요.

$ docker -H tcp://174.17.0.1:2376 ps

Note 관례상 Docker 데몬은 보안 TLS 연결에 포트 2376을, 비보안 비-TLS 연결에 포트 2375를 사용해요.

SSH 소켓 사용

SSH로 원격 데몬에서 명령을 호출하면 요청이 SSH 호스트의 /var/run/docker.sock Unix 소켓으로 전달돼요.

$ docker -H ssh://[email protected] ps

SSH 주소 끝에 경로 구성 요소를 추가해 소켓 위치를 선택적으로 지정할 수 있어요.

$ docker -H ssh://[email protected]/var/run/docker.sock ps

하위 명령

명령	설명
`docker builder`	빌드 관리
`docker buildx`	Docker Buildx
`docker checkpoint`	체크포인트 관리
`docker compose`	Docker Compose
`docker config`	Swarm 구성 관리
`docker container`	컨테이너 관리
`docker context`	컨텍스트 관리
`docker debug`	어떤 컨테이너나 이미지에서도 셸 얻기. `docker exec`로 디버깅하는 대안
`docker desktop`	Docker Desktop
`docker dhi`	Docker Hardened Images 관리 CLI
`docker image`	이미지 관리
`docker init`	프로젝트용 Docker 관련 스타터 파일 생성
`docker inspect`	Docker 객체에 대한 저수준 정보 반환
`docker login`	레지스트리 인증
`docker logout`	레지스트리에서 로그아웃
`docker manifest`	Docker 이미지 매니페스트 및 매니페스트 목록 관리
`docker mcp`	MCP 서버와 클라이언트 관리
`docker model`	Docker Model Runner
`docker network`	네트워크 관리
`docker node`	Swarm 노드 관리
`docker offload`	CLI에서 Docker Offload 제어
`docker pass`	로컬 OS 키체인 비밀 관리
`docker plugin`	플러그인 관리
`docker scout`	Docker Scout용 명령줄 도구
`docker search`	Docker Hub에서 이미지 검색
`docker secret`	Swarm 비밀 관리
`docker service`	Swarm 서비스 관리
`docker stack`	Swarm 스택 관리
`docker swarm`	Swarm 관리
`docker system`	Docker 관리
`docker trust`	Docker 이미지 신뢰 관리
`docker version`	Docker 버전 정보 표시
`docker volume`	볼륨 관리

docker

docker

본문

도움말 텍스트 표시

환경 변수

옵션 타입

Boolean

Multi

Strings and Integers

구성 파일

.docker 디렉터리 변경

Docker CLI 구성 파일 (config.json) 속성

명령의 기본 출력 형식 커스터마이즈

커스텀 HTTP 헤더

자격 증명 저장소 옵션

컨테이너 자동 프록시 구성

컨테이너에서 분리하는 기본 키 시퀀스

CLI 플러그인 옵션

샘플 구성 파일

실험적 기능

Notary

옵션

예시

데몬 호스트 지정 (-H, --host)

TCP 소켓 사용

SSH 소켓 사용

하위 명령

더 알아보기 (Learn more)