"배포 입문 (1/7) — 배포는 왜 필요한가: 로컬 실행과 공개 서비스의 차이"

-

같은 코드를 가지고도 내 노트북에서는 돌아가고, 남의 브라우저에서는 깨질 수 있다. 배포는 그 차이를 줄이는 작업이다.

핵심 요약

  • 배포는 코드를 인터넷에 올리는 행위가 아니라, 다른 사람도 같은 결과를 보게 만드는 운영 절차다.
  • 로컬 실행은 개인 환경에 기대지만, 공개 서비스는 서버 환경·빌드 결과·환경 변수·도메인·가용성을 함께 다뤄야 한다.
  • 배포가 필요한 이유는 접근성, 반복 가능성, 협업, 검증, 복구 가능성 때문이다.
  • 이후 시리즈는 로컬 작업 -> Git -> GitHub -> 호스팅 플랫폼 -> 자동 배포 파이프라인 흐름으로 이어진다.

1. 배포는 실제로 무엇을 하는가

배포를 가장 짧게 정의하면 이렇다. 내 컴퓨터 안의 작업물을, 남도 같은 방식으로 접근할 수 있는 서비스 상태로 바꾸는 것.

이때 바뀌는 것은 코드 한 파일만이 아니다. 보통 함께 결정해야 하는 것이 많다.

  • 어떤 파일을 빌드 결과로 쓸지
  • 어떤 서버나 플랫폼에서 실행할지
  • 어떤 환경 변수와 비밀값을 넣을지
  • 어떤 주소로 공개할지
  • 실패했을 때 어떻게 되돌릴지

그래서 배포는 "마지막 버튼"이 아니라 개발과 운영이 만나는 경계면이다.

2. 왜 로컬 실행만으로는 충분하지 않을까

로컬 실행은 개인 실험에는 훌륭하다. 하지만 서비스 관점에서는 한계가 분명하다.

첫째, 환경이 다르다. 내 맥북의 Node 버전, Python 패키지, 운영체제 설정은 다른 사람과 같지 않다. 둘째, 접근 경로가 없다. 로컬의 localhost는 나만 볼 수 있다. 셋째, 반복성이 약하다. 오늘은 됐는데 내일은 안 되는 경우가 흔하다. 넷째, 복구 이력이 없다. 어떤 버전이 안정적이었는지 바로 알기 어렵다.

배포는 이런 문제를 줄인다. 같은 저장소, 같은 브랜치, 같은 빌드 규칙, 같은 공개 주소를 기준으로 삼기 때문이다.

3. 배포가 주는 진짜 이점

많은 초보자는 배포의 장점을 "URL이 생긴다" 정도로 이해한다. 하지만 더 중요한 것은 아래 다섯 가지다.

접근성

사용자, 팀원, 면접관, 고객이 내 컴퓨터에 접속하지 않아도 결과를 볼 수 있다.

반복 가능성

같은 브랜치를 같은 방식으로 빌드하면 같은 결과가 나와야 한다. 이것이 자동화의 출발점이다.

협업 가능성

배포 주소가 있으면 "코드를 설명"하는 대신 "실제로 열린 화면"을 함께 볼 수 있다.

검증 가능성

배포 전후 테스트, 미리보기 링크, 로그, 롤백 지점을 만들 수 있다.

복구 가능성

문제가 생겼을 때 "직전 안정 버전으로 되돌린다"는 선택지가 생긴다.

4. 배포에도 종류가 있다

배포는 한 가지가 아니다. 앱의 성격에 따라 필요한 방식이 달라진다.

유형 대표 예시 특징
정적 배포 문서 사이트, 포트폴리오, 블로그 HTML/CSS/JS 결과물만 올리면 됨
앱 배포 Next.js, React, Streamlit 앱 빌드 또는 앱 실행 환경이 필요
서비스 배포 API 서버, 백엔드, 워커 항상 떠 있는 프로세스, 로그, 재시작 정책 필요

이 구분이 중요한 이유는 플랫폼 선택 기준이 달라지기 때문이다. GitHub Pages는 정적 사이트에 강하고, Vercel은 프론트엔드 배포 경험이 좋고, Streamlit Community Cloud는 Python 데이터 앱에 단순하며, Railway는 서버 프로세스가 필요한 앱에 맞는다.

5. 초보자가 가장 자주 오해하는 지점

첫 번째 오해는 "배포는 개발이 끝난 뒤 한 번만 한다"는 생각이다. 실제로는 정반대다. 배포는 반복되는 업데이트 흐름의 일부다.

두 번째 오해는 "배포가 되면 운영도 끝"이라는 생각이다. 공개 이후에는 오류 로그, 환경 변수, 빌드 실패, 롤백, 비용 같은 운영 문제가 시작된다.

세 번째 오해는 "일단 메인 브랜치에 올리고 보자"는 태도다. 이 습관이 쌓이면 배포 파이프라인보다 실수 파이프라인이 먼저 만들어진다.

6. 이번 시리즈에서 무엇을 배우게 되나

이 시리즈는 순서를 의도적으로 잡았다.

  1. 왜 배포가 필요한가
  2. Git이 왜 배포의 기반인가
  3. GitHub에서 repository, Pages, Actions가 어떻게 역할을 나누는가
  4. Vercel, Streamlit Community Cloud, Railway는 각각 무엇에 맞는가
  5. 마지막으로 PR, 테스트, preview, production이 이어지는 자동 배포 파이프라인은 어떻게 구성하는가

즉, 도구를 외우기 전에 흐름을 먼저 이해하는 학습 순서다.

참고 자료

  • GitHub Docs, Understanding GitHub Actions — https://docs.github.com/en/actions/get-started/understand-github-actions
  • GitHub Docs, Configuring a publishing source for your GitHub Pages site — https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
  • Vercel Docs, Deploying Git Repositories with Vercel — https://vercel.com/docs/git
  • Streamlit Docs, Deploy your app on Community Cloud — https://docs.streamlit.io/deploy/streamlit-community-cloud/deploy-your-app/deploy
  • Railway Docs, Controlling GitHub Autodeploys — https://docs.railway.com/deployments/github-autodeploys

이 글은 배포 입문 시리즈의 1/7 편입니다. 다음 편: Git 기초 — commit, branch, merge, push를 배포 관점에서 이해하기.

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »