[Docker] Docker Container 실행하기: 단계별 가이드

Bigbread1129 2025. 1. 15. 19:18

Docker를 활용하여 컨테이너를 실행하고 관리하는 방법에 대해 자세히 알아보겠습니다.

Docker는 애플리케이션을 컨테이너화하여 일관된 환경에서 실행할 수 있게 해주는 강력한 도구입니다. 특히, Docker 이미지를 빌드하고 배포한 후, 이를 기반으로 컨테이너를 실행하고 관리하는 과정은 매우 중요합니다.

이 글에서는 docker container run 명령어와 관련된 주요 옵션들을 상세히 설명하고, 실제 예제를 통해 실습해보겠습니다.

docker container

docs.docker.com

Docker Container 실행하기

Docker 이미지를 빌드하고 배포한 후, 이제 해당 이미지를 기반으로 컨테이너를 실행해보겠습니다.

컨테이너는 이미지의 실행 인스턴스이며, 애플리케이션을 실제로 구동하는 환경을 제공합니다.

주요 옵션 설명

docker container run 명령어는 Docker 이미지를 기반으로 컨테이너를 생성하고 실행하는 데 사용됩니다.

다양한 옵션을 통해 컨테이너의 동작 방식을 세밀하게 제어할 수 있습니다. 아래 표는 자주 사용하는 주요 옵션들을 정리한 것입니다.

옵션	설명	사용법	예시 및 주의사항
--name	컨테이너의 이름을 지정합니다.	--name [컨테이너명]	- 예시: --name mbti- 주의사항: 지정하지 않으면 Docker가 자동으로 랜덤 이름을 할당합니다. 명확한 이름을 지정하면 관리가 용이합니다.
-e 또는 --env	컨테이너에 환경 변수를 설정합니다.	-e [변수명]=[값]	- 예시: -e PORT=3000- 용도: 애플리케이션 실행 시 필요한 환경 변수를 설정합니다.- 추가: --env-file 옵션을 사용하여 여러 환경 변수를 파일로 관리할 수 있습니다.
--env-file	환경 변수를 파일로부터 로드합니다.	--env-file [파일 경로]	- 예시: --env-file .docker.env- 용도: 여러 환경 변수를 한꺼번에 로드할 때 유용합니다.
--rm	컨테이너가 종료되면 자동으로 삭제합니다.	--rm	- 설명: 컨테이너 실행 후 종료 시, 관련된 정보를 자동으로 삭제하여 불필요한 데이터가 쌓이지 않도록 합니다.
-d	컨테이너를 백그라운드에서 실행합니다.	-d	- 설명: 터미널을 다른 용도로 사용하기 위해 컨테이너를 백그라운드로 실행합니다.

컨테이너 실행 예제

이제 위에서 설명한 옵션들을 활용하여 실제로 컨테이너를 실행해보겠습니다.
아래는 docker container run 명령어를 사용한 예제입니다.

docker container run \
  --name mbti \
  -e PORT=3000 \
  --rm \
  -d \
  daehyunbigbread/mbti:embedded-db

b5c33cca7b0f895c4e3e1cce9e2ef7bc0c3059231b6c6a3fce0accf8f0a1b206

Docker Desktop으로 보면 로컬에서 컨테이너가 실행된걸 알수 있습니다.

명령어 설명

--name mbti:
- 설명: 컨테이너의 이름을 mbti로 지정합니다.
- 효과: 나중에 컨테이너를 관리할 때 명확한 이름으로 접근할 수 있습니다.
-e PORT=3000:
- 설명: 컨테이너 내에서 PORT 환경 변수를 3000으로 설정합니다.
- 효과: 애플리케이션이 3000 포트를 사용하도록 설정됩니다.
--rm:
- 설명: 컨테이너가 종료되면 자동으로 삭제됩니다.
- 효과: 불필요한 컨테이너가 시스템에 남지 않아 공간을 절약할 수 있습니다.
-d:
- 설명: 컨테이너를 백그라운드에서 실행합니다.
- 효과: 터미널을 다른 작업에 사용할 수 있습니다.
daehyunbigbread/mbti:embedded-db:
- 설명: 실행할 Docker 이미지입니다.
- 효과: 지정된 이미지로부터 컨테이너가 생성되고 실행됩니다.

실행 결과

명령어를 실행하면, Docker는 지정된 이미지를 기반으로 컨테이너를 생성하고 실행합니다.

성공적으로 실행되면, 컨테이너 ID가 출력됩니다.

b5c33cca7b0f895c4e3e1cce9e2ef7bc0c3059231b6c6a3fce0accf8f0a1b206

Container 확인 및 관리

컨테이너를 실행한 후, 이를 확인하고 관리하는 방법에 대해 알아보겠습니다.
Docker는 다양한 명령어를 제공하여 컨테이너의 상태를 모니터링하고 조작할 수 있습니다.

실행 중인 컨테이너 확인

실행 중인 모든 컨테이너를 확인하려면 docker container ls 명령어를 사용합니다.

docker container ls

예시 출력

CONTAINER ID   IMAGE                              COMMAND           CREATED          STATUS          PORTS     NAMES
b5c33cca7b0f   daehyunbigbread/mbti:embedded-db   "npm run start"   12 minutes ago   Up 12 minutes             mbti

CONTAINER ID: 컨테이너의 고유 식별자입니다.
IMAGE: 컨테이너가 기반한 이미지입니다.
COMMAND: 컨테이너가 실행 중인 명령어입니다.
CREATED: 컨테이너가 생성된 시간입니다.
STATUS: 컨테이너의 현재 상태입니다.
PORTS: 컨테이너가 노출한 포트입니다.
NAMES: 컨테이너의 이름입니다.

컨테이너 내부 파일 확인하기

컨테이너 내부의 파일을 확인하고 싶을 때는 docker container exec 명령어를 사용합니다.
이 명령어는 실행 중인 컨테이너 내에서 명령어를 실행할 수 있게 해줍니다.

명령어 형식

docker container exec [옵션] [컨테이너명] [실행할 명령어]

예제: /app 디렉토리 파일 목록 확인

docker container exec mbti ls /app

예시 출력

Dockerfile
next-env.d.ts
next.config.mjs
node_modules
package-lock.json
package.json
public
src
tsconfig.json

설명: mbti 컨테이너 내의 /app 디렉토리에 있는 파일들을 나열합니다.

컨테이너에 터미널 접속하기

컨테이너 내부에 직접 접근하여 명령어를 실행하거나 파일을 수정하고 싶을 때는 docker container exec -it 명령어를 사용합니다.
이 명령어는 컨테이너 내부에 터미널을 연결해줍니다.

옵션 설명

-i: 인터랙티브 모드로 실행하여 키보드 입력을 컨테이너에 전달합니다.
-t: TTY를 할당하여 터미널을 사용 가능하게 합니다.

명령어 예제

docker container exec -it mbti bash

실행 결과

root@b5c33cca7b0f:/app#

설명: mbti 컨테이너 내부에 Bash 셸을 실행하여 직접 명령어를 입력할 수 있습니다.
종료: 컨테이너 내부에서 exit 명령어를 입력하여 셸을 종료하고 터미널을 빠져나옵니다.

컨테이너 로그 확인하기

컨테이너의 실행 로그를 실시간으로 확인하려면 docker container logs -f 명령어를 사용합니다.
이 명령어는 컨테이너의 로그를 스트리밍하여 실시간으로 모니터링할 수 있게 해줍니다.

명령어 형식

docker container logs -f [컨테이너명]

예제: mbti 컨테이너 로그 확인

docker container logs -f mbti

예시 출력

> mbti-nextjs@0.1.0 start
> next start

  ▲ Next.js 14.2.3
  - Local:        http://localhost:3000

 ✓ Starting...
 ✓ Ready in 244ms
| GET | /api/healthcheck | Tue Jan 07 2025 07:35:11 GMT+0000 (Coordinated Universal Time) |

설명: mbti 컨테이너의 실시간 로그를 확인합니다. 애플리케이션의 상태, 요청 처리 등을 모니터링할 수 있습니다.

실시간 로그와 요청 체크

컨테이너에 요청을 보내고 로그에 반영되는지를 확인해보겠습니다.

로그 모니터링
docker container logs -f mbti

요청 보내기

docker container exec mbti curl localhost:3000/api/healthcheck

새로운 터미널 창을 열고 다음 명령어를 실행합니다.

로그 확인

> mbti-nextjs@0.1.0 start
> next start

  ▲ Next.js 14.2.3
  - Local:        http://localhost:3000

로그 창에서 요청이 처리된 내역을 확인할 수 있습니다.

✓ Starting... ✓ Ready in 244ms | GET | /api/healthcheck | Tue Jan 07 2025 07:35:11 GMT+0000 (Coordinated Universal Time) |

요청 결과

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                               Dload  Upload   Total   Spent    Left  Speed
100  7428    0  7428    0     0  50815      0 --:--:-- --:--:-- --:--:-- 50876

설명: curl 명령어를 사용하여 API 엔드포인트에 요청을 보냈으며, 컨테이너 로그에 해당 요청이 기록된 것을 확인할 수 있습니다.

실행 중인 컨테이너 종료 명령어

실행 중인 컨테이너를 종료하려면 docker container stop 명령어를 사용합니다.

명령어 형식

docker container stop [컨테이너명]

예제: mbti 컨테이너 종료

docker container stop mbti

실행 결과

mbti

설명: mbti 컨테이너가 종료되며, docker container ls 명령어를 통해 더 이상 실행 중인 컨테이너 목록에 나타나지 않음을 확인할 수 있습니다.

docker container ls

예시 출력

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

설명: mbti 컨테이너가 정상적으로 종료되어 실행 중인 컨테이너 목록에 더 이상 표시되지 않습니다.

만약 컨테이너가 종료만 되고 삭제가 되지 않았을 때?

--rm 옵션을 사용하지 않은 경우, 컨테이너가 종료되더라도 시스템에 남아있을 수 있습니다.

이를 확인하려면 docker container ls -a 명령어를 사용합니다.

명령어 예제

docker container ls -a

예시 출력

CONTAINER ID   IMAGE                              COMMAND           CREATED          STATUS                     PORTS     NAMES
aaf9f623ea59   daehyunbigbread/mbti:embedded-db   "npm run start"   27 seconds ago   Exited (1) 3 seconds ago             mbti

설명: mbti 컨테이너가 종료되었지만, 삭제되지 않고 남아있는 것을 확인할 수 있습니다.

컨테이너 삭제하기

종료된 컨테이너를 삭제하려면 docker container rm 명령어를 사용합니다.

docker container rm mbti

실행 결과

mbti

설명: mbti 컨테이너가 시스템에서 삭제되었습니다.

삭제 확인

docker container ls -a

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

설명: mbti 컨테이너가 더 이상 목록에 나타나지 않습니다.

실행 중인 컨테이너 일괄 삭제하기

여러 개의 실행 중인 컨테이너를 일괄적으로 삭제하려면 docker container prune 명령어를 사용합니다.
이 명령어는 사용하지 않는 모든 컨테이너를 삭제합니다.

명령어 예제

docker container prune

실행 결과

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y
Total reclaimed space: 0B

설명: 모든 정지된 컨테이너가 삭제되며, 사용자가 y를 입력하여 확인을 완료합니다.
주의사항: -f 옵션을 사용하지 않으면 확인 프롬프트가 표시됩니다. 실수로 중요한 컨테이너가 삭제되지 않도록 주의하세요.

docker container prune -f

설명: 확인 프롬프트 없이 모든 정지된 컨테이너가 삭제됩니다.

Example) Next.js 서버 컨테이너 실행하기

이제 실전 예제를 통해 Docker 컨테이너를 실행하고 관리하는 과정을 실습해보겠습니다.
이번에는 Next.js 서버 애플리케이션을 Docker 컨테이너로 실행합니다.

실습 요건

다음 조건에 부합하는 컨테이너를 실행해보겠습니다.

컨테이너 이름: mbti
이미지: [계정명]/mbti:embedded-db
환경 변수:
- PORT: 3000
컨테이너 종료 시 자동 삭제: --rm 옵션 사용
백그라운드 실행: -d 옵션 사용

애플리케이션 소스 코드 다운로드

먼저, 애플리케이션 소스 코드를 다운로드 받아야 합니다.

mbti-mysql.zip

0.10MB

다운로드 받은 mbti-mysql.zip 파일을 압축 해제합니다.

unzip mbti-mysql.zip -d mbti-mysql
cd mbti-mysql

Docker 컨테이너 실행

이제 Docker 이미지를 기반으로 컨테이너를 실행해보겠습니다. 다음 명령어를 사용하여 컨테이너를 실행합니다.

docker container run \
  --name mbti \
  -e PORT=3000 \
  --rm \
  -d \
  daehyunbigbread/mbti:embedded-db

명령어 설명

--name mbti:
- 설명: 컨테이너의 이름을 mbti로 지정합니다.
-e PORT=3000:
- 설명: 컨테이너 내에서 PORT 환경 변수를 3000으로 설정합니다.
--rm:
- 설명: 컨테이너가 종료되면 자동으로 삭제됩니다.
-d:
- 설명: 컨테이너를 백그라운드에서 실행합니다.
daehyunbigbread/mbti:embedded-db:
- 설명: 실행할 Docker 이미지입니다.

실행 결과

명령어를 실행하면, Docker는 지정된 이미지를 기반으로 컨테이너를 생성하고 실행합니다.
성공적으로 실행되면, 컨테이너 ID가 출력됩니다.

b5c33cca7b0f895c4e3e1cce9e2ef7bc0c3059231b6c6a3fce0accf8f0a1b206

컨테이너 로그 확인

컨테이너가 정상적으로 실행되었는지 확인하기 위해 로그를 확인해보겠습니다.

docker container logs -f mbti

예시 출력

> mbti-nextjs@0.1.0 start
> next start

  ▲ Next.js 14.2.3
  - Local:        http://localhost:3000

 ✓ Starting...
 ✓ Ready in 279ms
| GET | /api/healthcheck | Tue Jan 07 2025 08:03:44 GMT+0000 (Coordinated Universal Time) |

설명: 애플리케이션이 정상적으로 시작되었으며, http://localhost:3000에서 실행 중임을 확인할 수 있습니다.

요청 보내기 및 로그 확인

실시간 로그가 제대로 출력되는지 확인하기 위해 컨테이너에 요청을 보내보겠습니다.

docker container exec mbti curl localhost:3000/api/healthcheck

실행 결과

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  7428    0  7428    0     0  50815      0 --:--:-- --:--:-- --:--:-- 50876

설명: curl 명령어를 사용하여 API 엔드포인트에 요청을 보냈으며, 요청이 성공적으로 처리되었음을 확인할 수 있습니다.

로그 확인

로그 창을 확인하면, 요청이 어떻게 처리되었는지 확인할 수 있습니다.

> mbti-nextjs@0.1.0 start
> next start

  ▲ Next.js 14.2.3
  - Local:        http://localhost:3000

 ✓ Starting...
 ✓ Ready in 279ms
| GET | /api/healthcheck | Tue Jan 07 2025 08:03:44 GMT+0000 (Coordinated Universal Time) |

설명: /api/healthcheck 엔드포인트에 대한 GET 요청이 성공적으로 처리되었음을 확인할 수 있습니다.

추가 팁 및 주의사항

Docker 컨테이너를 효율적으로 관리하고 운영하기 위해 몇 가지 팁과 주의사항을 알아두면 좋습니다.

이미지 태그 관리

버전 태그 사용: v1.0.0, v1.0.1 등 버전별로 태그를 지정하여 특정 버전을 쉽게 참조할 수 있습니다.
latest 태그 주의: latest 태그는 항상 최신 이미지를 가리키므로, 배포 환경에서는 명시적인 태그를 사용하는 것이 안전합니다.
일관된 태그 전략: 프로젝트마다 일관된 태그 전략을 수립하여 관리의 편의성을 높입니다.

컨테이너 자동 재시작 설정

컨테이너가 예기치 않게 종료되었을 때 자동으로 재시작하도록 설정할 수 있습니다.

docker container run \
  --name mbti \
  -e PORT=3000 \
  --rm \
  -d \
  --restart unless-stopped \
  daehyunbigbread/mbti:embedded-db

옵션 설명:
- --restart unless-stopped: 컨테이너가 수동으로 중지되지 않는 한, Docker가 자동으로 재시작합니다.

포트 매핑 설정

호스트와 컨테이너 간의 포트를 매핑하여 외부에서 애플리케이션에 접근할 수 있습니다.

docker container run \
  --name mbti \
  -e PORT=3000 \
  --rm \
  -d \
  -p 3000:3000 \
  daehyunbigbread/mbti:embedded-db

옵션 설명:
- -p [호스트 포트]:[컨테이너 포트]: 호스트의 3000 포트를 컨테이너의 3000 포트에 매핑합니다.
효과: 외부에서 http://localhost:3000으로 접근하면 컨테이너 내 애플리케이션에 접속할 수 있습니다.

환경 변수 파일 활용

여러 개의 환경 변수를 관리할 때는 --env-file 옵션을 사용하여 환경 변수 파일을 활용하는 것이 편리합니다.

환경 변수 파일 생성 (.docker.env):

PORT=3000
DB_HOST=localhost
DB_PORT=3306
DB_NAME=db_mbti
DB_USERNAME=user_mbti
DB_PASSWORD=pw_mbti

컨테이너 실행 시 환경 변수 파일 지정:

docker container run \
--name mbti \
--env-file .docker.env \
--rm \
-d \
daehyunbigbread/mbti:embedded-db

장점: 환경 변수를 한 곳에서 관리할 수 있어 편리하며, 코드와 환경 설정을 분리할 수 있습니다.

docker container run 명령어와 주요 옵션들을 상세히 살펴보고, 실제 예제를 통해 컨테이너를 실행하고 로그를 확인하는 방법을 배웠습니다. 또한, 컨테이너를 효율적으로 관리하기 위한 추가 팁과 주의사항도 알아보았습니다.

Docker를 활용하면 개발, 테스트, 배포 과정에서 발생할 수 있는 환경 차이 문제를 해결하고, 애플리케이션의 이식성과 확장성을 크게 향상시킬 수 있습니다.

참고 자료

Docker 공식 문서: https://docs.docker.com/
Docker CLI Reference: Docker Container Commands
Docker Hub: Docker Hub Container Image Library | App Containerization
Next.js 공식 문서: Next.js Documentation

저작자표시 비영리 동일조건 (새창열림)