[개인 공부] "배포" 기본 개념 정리(1)

1. 배포(Deployment)의 기본 개념

배포란 개발자의 PC에서만 동작하던 코드를, 24시간 인터넷에 연결되어 있는 '서버(Server)' 컴퓨터로 옮겨 실행함으로써 일반 사용자가 웹 브라우저나 앱을 통해 접근할 수 있게 만드는 모든 과정을 의미합니다.

• 로컬 환경 (Local): 현재 개발에 사용한 내 PC 환경입니다. 내가 끄면 서버도 죽습니다.
• 운영 환경 (Production): AWS, GCP, Vercel 등 클라우드 서비스에서 제공하는 서버 컴퓨터입니다. 24시간 무중단으로 실행되며 고정된 주소(IP 또는 도메인)를 갖습니다.

배포의 핵심은 "내 컴퓨터에서 되던 것이 다른 컴퓨터(서버)에서도 똑같이, 멈추지 않고 돌아가게 만드는 것"입니다.

---

2. Meat-A-Eye 프로젝트 배포 아키텍처의 이해

블로그 참고: https://pak1010pak.tistory.com/142

[프로젝트 회고] Meat-A-Eye: AI 기반 축산물 부위 인식 및 관리 플랫폼 개발기

블로그에 명시된 기술 스택(Next.js, FastAPI, AI/OCR, MySQL)을 기준으로 배포 구조를 나누어 이해해야 합니다.

• Frontend (Next.js 16):
  • 사용자에게 보여지는 화면입니다. 정적 파일과 클라이언트 라우팅을 담당하므로, Vercel이나 Netlify 같은 프론트엔드 전용 클라우드 플랫폼에 배포하는 것이 가장 빠르고 효율적입니다.
• Backend (FastAPI) & AI Server:
  • API 요청을 처리하고 DB와 통신하며, 무거운 비전 모델과 OCR 엔진을 돌립니다. 이 부분은 파이썬 환경과 여러 라이브러리(PyTorch, PaddleOCR 등) 의존성이 강하므로, 환경을 통째로 묶어서 배포할 수 있는 도구가 필수적입니다.
• Database (MySQL):
  • 회원 정보와 이력 데이터 등을 저장합니다. 서버가 재부팅되어도 데이터가 날아가지 않도록 관리해야 하며, 보통 클라우드의 데이터베이스 전용 서비스(RDS 등)를 쓰거나 별도의 서버 공간에 띄웁니다.

---

3. 배포 공부를 위해 반드시 알아야 할 3가지

A. 도커 (Docker) : 환경의 일치

가장 중요합니다. 내 PC에서는 PaddleOCR이 잘 돌았는데, 서버에 코드를 올리니 OS 버전이나 의존성 라이브러리가 달라 에러가 나는 경우가 부지기수입니다. 도커는 코드, 실행 환경, 라이브러리를 '컨테이너(Container)'라는 하나의 상자로 포장하는 기술입니다. 이 상자만 서버에 가져가면 내 PC와 100% 동일한 환경에서 프로그램이 실행됩니다.

B. CI/CD (지속적 통합/지속적 배포) : 자동화

깃허브의 코드를 수정할 때마다 개발자가 서버에 접속해서 코드를 다운받고 서버를 껐다 켜는 것은 비효율적입니다. GitHub Actions 같은 도구를 사용하면, main 브랜치에 코드를 Push하는 순간 자동으로 코드를 테스트하고 서버에 반영해 주는 파이프라인을 구축할 수 있습니다.

C. 클라우드 컴퓨팅 (Cloud Computing) : 인프라 대여

물리적인 컴퓨터를 사는 대신, 인터넷을 통해 필요한 만큼 서버 자원을 빌려 쓰는 개념입니다.

• IaaS (Infrastructure as a Service):
  • AWS EC2처럼 텅 빈 컴퓨터 한 대를 빌려주는 형태입니다. 자유도가 높지만 OS 설치부터 모두 직접 해야 합니다.
• PaaS (Platform as a Service):
  • 코드를 올리기만 하면 실행 환경을 다 알아서 구성해 주는 형태입니다. 프론트엔드를 위한 Vercel이 대표적입니다.

---

4. 전체적인 흐름도

1단계: 모노레포 구조로 코드 통합 및 Push

가장 먼저 흩어져 있던 프론트엔드, 백엔드, AI 코드를 새로 만든 하나의 저장소에 모아야 합니다.

• 폴더 구조화: 프로젝트 루트(최상위) 폴더 안에 client(프론트), server(백엔드), ai(모델 및 추론 로직) 폴더를 만들고 각각의 코드를 넣습니다.
• Git 반영: 정리된 전체 폴더를 meat-a-eye-service 리포지토리의 main 브랜치에 Push 합니다.

2단계: 환경 변수 및 설정 파일 분리

배포 환경에서는 로컬에서 쓰던 비밀번호나 API 키가 그대로 올라가면 보안 사고가 발생합니다.

• .env 파일 분리: DB 접속 정보, Gemini API 키, 공공데이터(시세, 이력제) API 키 등을 모두 .env 파일로 뺍니다.
• .gitignore 확인: .env 파일과 AI 모델의 무거운 가중치 파일(.pth, .pt 등)이 깃허브에 올라가지 않도록 반드시 .gitignore에 추가합니다.

3단계: Docker를 이용한 컨테이너화

개발자의 PC(로컬)와 실제 운영 서버의 환경(OS, 패키지 버전 등)이 달라서 생기는 오류를 막기 위해 도커(Docker)를 사용합니다.

• Dockerfile 작성: client, server, ai 폴더 각각에 이 프로그램들을 어떻게 실행하는지 적어둔 설명서인 Dockerfile을 만듭니다.
• docker-compose.yml 작성: 프로젝트 최상위 경로에 이 3개의 컨테이너를 한 번에 묶어서 실행하고 서로 통신할 수 있게 해주는 설정 파일을 만듭니다.

4단계: 클라우드 인프라(서버) 준비 및 수동 배포

콜드 스타트(지연 시간) 없이 4초 미만의 AI 비전 및 OCR 속도를 유지하기 위해, 항상 켜져 있는 서버를 하나 준비합니다.

• 서버 임대: AWS EC2, NCP(네이버 클라우드), 혹은 Cloudtype 같은 서비스에서 GPU가 포함되거나 CPU 성능이 넉넉한 인스턴스를 하나 대여합니다.
• 최초 실행: 임대한 서버에 접속하여 깃허브 저장소를 git clone 받고, 환경 변수(.env)를 서버에 직접 세팅한 뒤 docker-compose up 명령어로 전체 서비스를 실행해 봅니다. 접속이 잘 되는지 테스트하는 단계입니다.

5단계: GitHub Actions로 CI/CD 구축 (자동화)

서버가 잘 돌아가는 것을 확인했다면, 앞으로 코드를 수정할 때마다 서버에 직접 들어가서 끄고 켜는 수고를 덜어야 합니다.

• 파이프라인 작성: 깃허브 저장소에 .github/workflows/deploy.yml 파일을 만들어 자동화 스크립트를 작성합니다.
• 자동 배포: 이제 누군가 main 브랜치에 코드를 Push 하면, 깃허브가 알아서 코드를 빌드하고 서버에 접속해 새로운 버전으로 서비스를 재시작해 줍니다.