[Docker] 로컬에서 Docker 이미지 빌드하고 서버에서 실행하기

FastAPI나 Python 기반 백엔드 프로젝트를 Docker로 패키징해서 서버에 올리는 방법을 정리했습니다.
한 번 빌드한 이미지를 서버에 가져다 실행하는 것과, 서버에서 직접 빌드하는 방법 두 가지를 비교하며 설명해보겠습니다.

 

1. 로컬에서 Docker 이미지 빌드 → 서버에서 pull & 실행

1️⃣ 로컬에서 Docker 이미지 빌드

로컬에서 프로젝트 디렉토리 안에서 다음 명령어로 이미지를 빌드합니다.

docker build -t hoyeon/collec_ai:latest .

• hoyeon → 내 Docker Hub ID
• collec_ai → 이미지 이름
• latest → 태그 이름

2️⃣ Docker Hub에 로그인 후 이미지 푸시

docker login
docker push hoyeon/collec_ai:latest

이렇게 하면 빌드한 이미지가 Docker Hub에 올라가고, 서버에서 받아쓸 수 있게 됩니다.

3️⃣ 서버에서 이미지 pull → 실행

서버에 접속한 뒤:

docker pull hoyeon/collec_ai:latest

docker run -d \
  -p 8080:8080 \
  --name collec_ai \
  hoyeon/collec_ai:latest

 

2. 서버에서 직접 GitHub 코드 클론 → Docker 빌드

1️⃣ 서버에 접속 후 GitHub에서 코드 클론

git clone https://github.com/~/collec_AI.git
cd collec_AI

2️⃣ Docker 이미지 빌드 및 실행

docker build -t collec_ai .
docker run -d -p 8080:8080 collec_ai

단, 이 방법은 민감한 GCP 키 파일 등이 .gitignore로 잘 빠져 있어야 합니다!

 

어떤 방법이 더 나을까?

구분 방법 1 (이미지 push & pull) 방법 2 (서버에서 직접 빌드)

장점	- 안정적- 여러 서버에 배포 쉬움	- 간단함- Docker Hub 불필요
단점	- Docker Hub 로그인 필요	- 서버 성능 이슈- 키 관리 주의

여러 환경에 배포하거나 재사용할 일이 많다면 방법 1이 확실히 유리합니다.

서버에서 Docker 실행 확인하는 법

1. 컨테이너 실행 상태 확인

docker ps

 

정상 실행 시 예시

CONTAINER ID   IMAGE                        STATUS         PORTS                    NAMES
abc123456789   hoyeon/collec_ai:latest  Up 10 seconds  0.0.0.0:8080->8080/tcp   collec_ai

2. 내부 포트 테스트

curl http://localhost:8080

또는 외부에서 브라우저로 접속:

http://<서버IP>:8080

3. 컨테이너 로그 확인

docker logs collec_ai

Application startup complete. 같은 문구가 보이면 앱이 잘 올라온 것입니다.

---

서버 포트 개방 확인

UFW 사용하는 경우

sudo ufw allow 8080
sudo ufw reload

AWS EC2를 사용하는 경우

• 보안 그룹 > 인바운드 규칙에 TCP 8080포트를 추가해야 외부에서 접속 가능합니다.

---

FastAPI API 문서 확인

FastAPI를 사용 중이라면 아래 주소에서 Swagger UI로 확인할 수 있어요:

http://<서버IP>:8080/docs

---

정리하자면

• 단순 배포라면 방법 2도 충분하지만,
• 여러 서버에 반복 배포하거나 안정성이 중요하다면 방법 1 (Docker Hub 연동)을 추천합니다!

---

필요하다면 나중에 docker-compose.yml로도 관리 자동화할 수 있습니다!
관련해서 다음에 포스팅하도록 하겠습니다 :)