사이드 프로젝트에 Docker 적용해보기 (self-interior-guide)

안녕하세요.

이전 글에서는 Docker의 기본 개념과 전체 구조를 정리해봤습니다.

 

이번 글에서는
실제 프로젝트인 self-interior-guide에 Docker를 적용해본 과정을 정리해보겠습니다.

 

앞선 글에서 Docker의 개념을 이해했다면,
이번에는 그 개념들이 실제로 어떻게 동작하는지 확인하는 단계라고 보면 됩니다.

 

다만 이번 적용은
실제 배포를 위한 것이 아니라 테스트 및 학습 목적으로 진행했습니다.

 

현재 프로젝트는
 **Vercel**을 통해 배포하고 있고,
Docker는 실행 환경을 직접 구성해보기 위한 용도로 사용했습니다.

---

1. Docker 적용을 시작하기 전에

Docker를 적용하기 전에
먼저 Docker가 정상적으로 설치되어 있는지 확인했습니다.

 

docker -v

 

Docker가 정상적으로 설치되어 있다면
버전 정보가 출력됩니다.

---

2. hello-world로 Docker 동작 확인

다음으로 Docker가 실제로 동작하는지 확인하기 위해
hello-world 이미지를 실행해봤습니다.

docker run hello-world

 

 

이 과정에서 Docker 내부에서는 다음과 같은 흐름이 발생합니다.

• Docker Hub에서 이미지 pull
• 컨테이너 생성
• 컨테이너 실행
• 결과 출력

즉, 이 한 번의 실행으로
Docker의 전체 흐름을 간단하게 확인할 수 있습니다.

---

3. 프로젝트 이미지 빌드

이제 실제 프로젝트를 Docker로 실행하기 위해
이미지를 생성했습니다.

 

docker build -t self-interior-guide .

 

 

빌드 과정에서는
Dockerfile을 기준으로 이미지가 생성되며,

• Node 환경 구성
• 패키지 설치
• 프로젝트 파일 복사

와 같은 과정이 단계별로 실행됩니다.

---

4. 실행 시 발생한 문제 (Node 버전 이슈)

이미지를 생성한 후 컨테이너를 실행했지만
바로 문제가 발생했습니다.

 

docker run -p 5173:5173 self-interior-guide

 

에러 내용을 보면 다음과 같습니다.

Vite requires Node.js version 20.19 or 22.12+

 

즉, Dockerfile에서 사용한 Node 버전이
프로젝트 요구사항과 맞지 않았던 것입니다.

이 부분을 통해 확인할 수 있는 점은 다음과 같습니다.

Docker도 결국 실행 환경이기 때문에
런타임 버전이 매우 중요하다

---

5. Dockerfile 수정 후 재빌드

문제를 해결하기 위해
Node 버전을 22로 수정했습니다.

FROM node:22-alpine

 

 

이후 다시 이미지를 빌드했습니다.

docker build -t self-interior-guide .

 

---

6. 정상 실행 확인

수정 후 다시 컨테이너를 실행했습니다.

 

docker run -p 5173:5173 self-interior-guide

 

정상적으로 실행되며
다음과 같은 결과를 확인할 수 있습니다.

 

Local: http://localhost:5173

 

즉, 컨테이너 환경에서도
로컬과 동일하게 프로젝트가 실행됩니다.

---

7. Docker Desktop에서 이미지 확인

Docker Desktop에서도
생성된 이미지를 확인할 수 있습니다.

 

여기서 확인할 수 있는 점은 다음과 같습니다.

• self-interior-guide 이미지 생성 완료
• hello-world 이미지 존재
• 동일 이미지에 대한 tag 존재

즉, CLI에서 생성한 결과를
GUI에서도 확인할 수 있습니다.

---

8. Docker Hub에 이미지 업로드

이미지를 Docker Hub에 업로드하면
다른 환경에서도 동일하게 실행할 수 있습니다.

 

이렇게 업로드된 이미지는
다른 환경에서 다음과 같이 사용할 수 있습니다.

docker pull ryuintae/self-interior-guide
docker run -p 5173:5173 ryuintae/self-interior-guide

 

---

9. Docker 배포 방식 (개발 vs 운영 관점)

Docker를 사용하다 보면
단순히 이미지를 만들고 실행하는 것에서 끝나는 것이 아니라,

누가 어떤 목적에서 사용하느냐에 따라 방식이 달라진다는 점을 확인할 수 있습니다.

 

크게 보면
개발 환경과 운영 환경, 이렇게 두 가지 관점으로 나누어 이해할 수 있습니다.

---

9.1 개발 환경 (개발자 협업 기준)

개발 단계에서는 보통
이미지를 공유하기보다는 소스코드와 Dockerfile을 함께 공유하는 방식으로 진행합니다.

전체 흐름은 다음과 같습니다.

소스코드 + Dockerfile 공유
→ 각자 docker build
→ 로컬에서 실행

 

왜 이런 방식을 사용할까요?

개발 단계에서는 프로젝트가 계속 바뀌기 때문입니다.

• 기능이 추가되기도 하고
• 버그를 수정하기도 하며
• 의존성이 변경되기도 합니다.

이처럼 코드가 자주 바뀌는 상황에서는
매번 이미지를 새로 만들어 공유하는 것이 오히려 비효율적일 수 있습니다.

그래서 개발 환경에서는
이미지 자체를 공유하기보다, 동일한 실행 환경을 맞추는 데 Docker를 활용하게 됩니다.

---

개발 환경에서 Docker의 역할

개발 환경에서 Docker의 가장 큰 역할은
환경 통일이라고 볼 수 있습니다.

예를 들어 협업을 하다 보면 다음과 같은 문제가 생길 수 있습니다.

• Node 버전이 다를 수 있고
• npm 패키지 충돌이 발생할 수 있으며
• 운영체제 차이로 인해 실행 결과가 달라질 수도 있습니다.

이런 문제를 줄이기 위해
Dockerfile을 기준으로 실행 환경을 고정하게 됩니다.

즉,
같은 소스코드를 받아도
각 개발자가 같은 방식으로 이미지를 빌드하고 실행할 수 있도록 만드는 것입니다.

---

실제 협업 흐름

실제 협업 흐름을 단순하게 정리하면 다음과 같습니다.

Git clone
↓
docker build
↓
docker run

이렇게 하면
모든 개발자가 동일한 환경에서 프로젝트를 실행할 수 있습니다.

---

핵심 특징

개발 환경에서의 Docker 사용 특징을 정리하면 다음과 같습니다.

• 코드 수정이 가능합니다.
• 실행 환경만 Docker로 통일합니다.
• 이미지를 공유하기보다는 소스코드를 공유합니다.
• 빠르게 반복 개발하는 데 적합합니다.

---

9.2 운영 환경 (배포 기준)

반면 운영 환경에서는 방식이 완전히 달라집니다.

운영 단계에서는
소스코드를 전달하지 않고 이미지를 전달하는 방식으로 진행합니다.

전체 흐름은 다음과 같습니다.

Dockerfile → build → image 생성
→ Docker Hub push
→ 서버에서 pull → 실행

 

---

왜 이렇게 할까?

운영 환경에서는 개발 환경과 중요하게 보는 기준이 다릅니다.

• 안정적으로 실행되어야 하고
• 항상 동일한 결과가 나와야 하며
• 배포도 빠르고 일관되게 이루어져야 합니다.

즉, 운영 환경에서는
코드를 수정하는 것보다
정확하게 실행되는 것 자체가 더 중요합니다.

---

운영 환경에서 Docker의 역할

운영 환경에서 Docker의 역할은
완성된 실행 환경을 그대로 전달하는 것입니다.

여기서 전달되는 이미지 안에는

• Node 버전
• 라이브러리
• 애플리케이션 코드

가 모두 포함되어 있습니다.

즉, 서버에서는 소스코드를 다시 세팅하거나
환경을 하나씩 맞출 필요 없이,
이미지를 pull 받아 실행하기만 하면 됩니다.

---

실제 운영 흐름

운영 흐름을 단순하게 정리하면 다음과 같습니다.

개발 서버에서 build
↓
Docker Hub push
↓
운영 서버 pull
↓
docker run

이 방식의 핵심은
서버에서는 별도의 추가 설정 없이
이미지를 실행하는 것만으로 동일한 환경을 그대로 재현할 수 있다는 점입니다.

---

핵심 특징

운영 환경에서의 Docker 사용 특징을 정리하면 다음과 같습니다.

• 코드 수정은 불가능합니다.
• 환경과 코드가 함께 고정됩니다.
• 이미지 기반으로 배포가 이루어집니다.
• CI/CD와 연결하기에 적합합니다.

---

9.3 개발 vs 운영 차이 정리

개발 환경과 운영 환경의 차이를 정리하면 다음과 같습니다.

구분	개발 환경	운영 환경
목적	개발	배포
전달 방식	소스코드	이미지
Docker 역할	환경 통일	실행 환경 전달
수정	가능	불가능
속도	빠른 반복	안정적 실행
사용 위치	로컬	서버

---

9.4 이번 프로젝트 기준 적용

self-interior-guide 프로젝트 기준으로 보면
이번 Docker 적용은 운영 배포보다는
개발 및 학습 환경에 더 가까운 방식이라고 볼 수 있습니다.

실제로 이번 과정에서는

• Dockerfile을 작성했고
• 이미지를 빌드했으며
• 로컬에서 직접 실행해보았습니다.

하지만 실제 서비스는
Vercel을 통해 배포하고 있습니다.

즉, 이번 프로젝트에서는 Docker를
실제 배포 도구로 사용한 것이 아니라,
실행 환경을 직접 구성하고 Docker의 동작 흐름을 이해해보기 위한 도구로 사용했다고 볼 수 있습니다.

---

9.5 한 줄로 정리하면

정리하면 다음과 같습니다.

개발 환경에서는 환경을 맞추기 위해 Docker를 사용하고
운영 환경에서는 환경을 그대로 전달하기 위해 Docker를 사용합니다.

 

즉, 같은 Docker를 사용하더라도
목적에 따라 사용하는 방식은 달라질 수 있습니다.

---

10. 정리

이번 글에서는
self-interior-guide 프로젝트에 Docker를 적용해본 과정을 정리했습니다.

핵심 내용을 정리하면 다음과 같습니다.

• Docker는 실행 환경을 포함한 구조로 동작한다
• 이미지 → 컨테이너 흐름을 직접 확인할 수 있다
• 환경 문제(Node 버전)도 컨테이너에서 동일하게 발생한다
• Docker Desktop을 통해 상태를 시각적으로 확인할 수 있다
• Docker Hub를 통해 이미지 배포가 가능하다

이번 프로젝트에서는 Docker를 실제 배포에는 사용하지 않았지만,
적용 과정을 통해 Docker의 실행 구조와 흐름을 직접 경험해볼 수 있었고,
개념으로만 이해하던 내용을 실제 동작과 연결해볼 수 있었습니다.