7장. 웹 UI 연동과 배포
배포 과정: 로컬에서 Streamlit Community Cloud 까지
식당을 열기 전에는 집 부엌에서 메뉴를 시험해 보고, 가게 자리를 빌리고, 재료 목록을 납품 업체에 넘기고, 금고 열쇠를 맡기고, 간판을 겁니다. 웹 앱도 비슷한 차례로 문을 엽니다. 내 PC 에서 streamlit run 으로 돌려 보고, 앱 파일을 GitHub 저장소에 올리고, Streamlit Community Cloud 에서 그 저장소를 골라 앱을 만들고, 패키지 목록(requirements.txt)과 비밀 값(Secrets)을 챙기면 공유 주소가 생깁니다.
화면을 본뜬 그림입니다. 실제 캡처가 아니고, 메뉴 이름은 2026년 11월에 Streamlit 공식 문서(docs.streamlit.io)에서 읽은 것이라 실제 화면과 대조하지 못했습니다. 화면은 바뀔 수 있습니다. 왼쪽에서 오른쪽으로 다섯 걸음이고, 번호는 상자 바깥에 붙여 아래 목록과 짝을 이룹니다. 1번은 내 PC 에서 돌려 보기, 2번은 GitHub 저장소에 올리기, 3번은 Community Cloud 에서 저장소·가지(branch)·앱 파일을 고르는 화면, 4번은 고급 설정(Advanced settings)의 Python 판과 Secrets 칸, 5번은 ….streamlit.app 꼴의 공유 주소입니다. 여기서 집 부엌이 내 PC, 가게 자리가 GitHub 저장소와 Community Cloud, 재료 목록이 requirements.txt, 맡긴 열쇠가 Secrets 입니다. 비유와 다른 점은, 가게는 한 번 열면 그대로지만 앱은 GitHub 저장소에 새 코드를 올릴 때마다 Community Cloud 가 그것을 받아 다시 띄운다는 것입니다.
배포의 다섯 걸음
| 걸음 | 하는 일 | 쓰는 것 | 확인할 것 |
|---|---|---|---|
| 1. 내 PC 에서 돌리기 | streamlit run app.py 로 브라우저에서 써 본다 | http://localhost:8501 | 오류 없이 질문과 답이 오가는지 |
| 2. 저장소에 올리기 | 앱 폴더를 GitHub 저장소로 올린다 | git add, git commit, git push | .env, secrets.toml 이 올라가지 않았는지 |
| 3. 앱 만들기 | Community Cloud 에서 저장소, 가지, 앱 파일 경로를 고른다 | GitHub 계정으로 로그인 | 앱 파일 경로가 맞는지(app.py) |
| 4. 설정 채우기 | 고급 설정에서 Python 판을 고르고 Secrets 칸에 키를 TOML 꼴로 붙여 넣는다 | secrets.toml 의 내용 | 내 PC 와 같은(가까운) Python 판 |
| 5. 공유와 확인 | 공유 주소로 들어가 처음부터 써 본다 | 휴대폰, 다른 브라우저 | 로그에 패키지 설치 오류가 없는지 |
공식 문서는 requirements.txt 를 저장소의 맨 위 폴더나 앱 파일과 같은 폴더에 두라고 합니다. 패키지 목록 파일은 하나만 둡니다. 여러 종류(requirements.txt, pyproject.toml 등)가 있으면 그 가운데 하나만 읽기 때문입니다. 무료로 쓸 수 있는 조건과 앱 수, 메모리 같은 한도는 바뀔 수 있으므로 이 교안에 숫자를 적지 않습니다. 배포하기 전에 공식 문서에서 확인하세요.
내 PC 에서 돌리기와 GitHub 에 올리기
아래 명령은 이 교안을 만들 때 실행하지 않은 안내용 명령입니다. 실습 6이 만든 out_ch07_deploy 폴더를 저장소로 올린다고 보고 적었습니다. 내아이디 와 저장소 이름은 여러분의 것으로 바꿉니다.
# 1) 앱 폴더로 들어간다. cd = change directory(폴더 바꾸기)
cd out_ch07_deploy
# 2) 내 PC 에서 앱을 띄운다. 브라우저에 http://localhost:8501 이 열린다. 끝낼 때는 Ctrl+C
streamlit run app.py
# 3) 이 폴더를 Git 저장소로 만든다. init = initialize(처음 차리기)
git init
# 4) 올릴 파일을 모두 무대에 올린다. add = 더하다, . = 지금 폴더 전부(.gitignore 에 적은 것은 빠진다)
git add .
# 5) 무엇이 올라갈지 확인한다. .env 와 .streamlit/secrets.toml 이 목록에 없어야 한다
git status
# 6) 지금 모습을 기록으로 남긴다. commit = 확정하다, -m = message(기록에 붙일 글)
git commit -m "구름다리여행 약관 챗봇 첫 배포"
# 7) 가지 이름을 main 으로 바꾼다. branch = 가지, -M = --move --force(이름을 강제로 바꾸기)
git branch -M main
# 8) GitHub 에 미리 만든 빈 저장소의 주소를 origin 이라는 이름으로 잇는다. remote = 멀리 있는 저장소
git remote add origin https://github.com/내아이디/gureum-docbot.git
# 9) 기록을 GitHub 로 밀어 올린다. push = 밀다, -u = --set-upstream(다음부터 git push 만 쳐도 이곳으로)
git push -u origin main| 명령과 옵션 | 원래 말 | 뜻 |
|---|---|---|
cd | change directory | 작업 폴더를 바꾼다 |
streamlit run app.py | 실행하다 | 앱 서버를 켜고 브라우저로 화면을 연다 |
git init | initialize | 지금 폴더를 Git 저장소로 차린다 |
git add . | 더하다 | 바뀐 파일을 다음 기록에 넣을 대기석(스테이징 영역)에 올린다 |
git status | 상태 | 올라갈 파일과 빠진 파일을 보여 준다 |
git commit -m "…" | 확정하다, message | 대기석의 파일을 기록 하나로 확정하고 글을 붙인다 |
git branch -M main | 가지, move·force | 지금 가지의 이름을 main 으로 바꾼다 |
git remote add origin 주소 | 멀리 있는, 더하다 | GitHub 저장소 주소를 origin 이라는 이름으로 등록한다 |
git push -u origin main | 밀다, set upstream | 기록을 GitHub 로 올리고, 다음부터 올릴 곳으로 정한다 |
Community Cloud 쪽의 일(3~5걸음)은 웹 화면에서 단추를 눌러 하는 일이라 명령이 없습니다. 실습 6과 프로젝트에서 배포할 폴더를 만들고 점검까지 한 뒤, 프로젝트의 "실제로 배포하려면"에 화면에서 할 일을 차례로 적었습니다.
주의할 점
- 처음
git add .를 하기 전에.gitignore부터 만듭니다. 순서를 거꾸로 하면.env가 기록에 들어가고, 2장에서 본 것처럼 지워도 예전 기록에 남습니다. - 앱이 읽는 파일(이 장에서는
travel_terms.pdf)도 저장소에 함께 올려야 합니다. 앱 코드에서는Path(__file__).parent / "travel_terms.pdf"처럼 앱 파일의 자리를 기준으로 경로를 적어, 어느 폴더에서 실행해도 같은 파일을 찾게 합니다. - 클라우드 서버는 여러분의 PC 와 다른 컴퓨터입니다.
C:\Users\…같은 내 PC 의 경로, 내 PC 에만 설치한 패키지, 내 PC 의.env는 그곳에 없습니다.