앞 페이지에서 저장소 구조를 고정했다면, 이제 그 구조를 실제로 돌릴 수 있어야 합니다. 실전형 풀스택 프로젝트에서 가장 먼저 무너지는 것 중 하나가 로컬 개발환경입니다. 폴더 구조는 멀쩡한데 누구는 storefront만 뜨고, 누구는 DB가 안 붙고, 누구는 환경변수가 없어서 챗봇 패널이 깨지는 식으로 서로 다른 상태가 생기기 쉽습니다.
이번 페이지의 목적은 이 차이를 없애는 것입니다. 어떤 개발자든 저장소를 받은 뒤 같은 명령으로 동일한 런타임을 띄우고, 같은 포트 규칙과 같은 서비스 이름으로 작업할 수 있어야 합니다. 그래야 프론트, 백엔드, 운영 화면, 챗봇 흐름을 같은 기준 위에서 동시에 개발할 수 있습니다.
구현보다 환경을 먼저 고정하는 이유는 간단합니다. 환경이 흔들리면 코드 문제와 실행 문제를 구분할 수 없기 때문입니다.
예를 들어:
storefront를 5173, 어떤 사람은 3000에 띄운다이 상태에서는 코드 리뷰도, 디버깅도, 강의 진행도 느려집니다. 따라서 이번 교재에서는 먼저 아래 세 가지를 고정합니다.
이 페이지를 읽고 나면 아래 항목이 정리되어 있어야 합니다.
compose가 담당할 범위env 항목다음 페이지의 DB, 시크릿, 실행 스크립트 설계도 이 문서 위에서 이어집니다.
이번 이커머스 MVP에서 기본적으로 함께 떠야 하는 것은 아래 네 축입니다.
storefrontadminserverdb선택적으로 아래가 붙을 수 있습니다.
하지만 이번 교재의 첫 실행 기준은 "최소한 구매자 화면, 운영자 화면, 백엔드, 데이터 저장소가 한 번에 같은 방식으로 뜬다"입니다.
compose는 개발환경의 공통 기반을 맞추는 데 좋지만, 모든 것을 무조건 컨테이너에 넣어야 하는 것은 아닙니다.
이번 교재에서는 아래처럼 나누는 것이 자연스럽습니다.
storefront dev serveradmin dev server왜냐하면 프론트는 HMR과 디버깅 편의성이 중요하기 때문입니다. 물론 팀 기준에 따라 전부 컨테이너로 묶을 수 있지만, 학습과 개발 편의성 측면에서는 프론트는 로컬, backend와 DB는 compose로 두는 방식도 충분히 실용적입니다.
다만 이번 교재에서는 "한 명령으로 모두 띄우는 경험"도 중요하므로, 설명상으로는 compose.yml이 최소한 backend와 DB를 표준화하고, 필요하면 프론트도 같이 띄울 수 있는 구조를 권장합니다.
포트는 사소해 보여도 팀 혼선의 원인이 됩니다. 처음부터 고정하는 편이 좋습니다.
예를 들어 이번 교재에서는 아래처럼 정할 수 있습니다.
| 서비스 | 권장 포트 | 이유 |
|---|---|---|
| storefront | 5173 |
Vite 기본 개발 포트와 자연스럽다 |
| admin | 5174 |
storefront와 나란히 구분 가능하다 |
| server API | 8000 |
Python/FastAPI 계열과 잘 맞는다 |
| db | 3306 또는 5432 |
선택 DB 기본 포트를 따른다 |
중요한 것은 특정 숫자 자체보다, 모두가 같은 숫자를 쓰는 것입니다.
포트만큼 중요한 것이 서비스 이름입니다. compose 안에서 서비스 이름과 코드 안의 호스트명이 다르면 혼선이 생깁니다.
이번 교재에서는 아래처럼 단순하게 두는 편이 좋습니다.
storefrontadminserverdb이 이름은 아래 위치에서 반복 사용됩니다.
compose.yml.env즉 서비스 이름은 사람이 읽는 이름이 아니라, 팀 전체가 공유하는 런타임 식별자입니다.
환경변수 설계의 핵심은 "무엇을 숨길 것인가"보다 먼저 "무엇을 어디에서 읽을 것인가"입니다.
이번 교재에서는 최소한 아래 구분이 필요합니다.
공통 런타임 설정이나 compose 변수
예:
storefront와 admin이 읽는 값
예:
server가 읽는 값
예:
중요한 점은 프론트와 백엔드가 같은 .env 파일을 아무 생각 없이 공유하지 않는 것입니다. 앱별 책임에 따라 읽는 값이 달라야 합니다.
이번 MVP 기준으로는 아래 정도면 충분합니다.
VITE_API_BASE_URLVITE_CHATBOT_ENABLEDAPP_ENVAPP_HOSTAPP_PORTDB_HOSTDB_PORTDB_USERDB_PASSWORDDB_NAMESECRET_KEYPAYMENT_MODECHATBOT_ENABLED이 변수들을 너무 많이 늘리기보다, 실제 런타임에 필요한 것만 유지하는 편이 좋습니다.
환경변수는 많을수록 좋은 것이 아닙니다. 자주 바뀌지 않는 상수까지 env로 빼면 오히려 읽기 어려워집니다.
즉 env는 "변할 가능성이 있는 실행 설정"을 위한 도구입니다.
.env.example은 왜 필요한가실전 프로젝트에서 새로 들어온 사람이 가장 먼저 보는 파일 중 하나가 .env.example입니다. 이것이 없으면 실행 장벽이 급격히 높아집니다.
이번 교재에서도 .env.example은 반드시 있어야 합니다.
.env.example은 실행 문서의 일부라고 생각하면 됩니다.
개발자는 아래 순서로 로컬을 띄우면 됩니다.
.env.example을 기준으로 환경변수 파일 준비compose로 backend와 DB 기동storefront와 admin dev server 기동이 순서가 중요한 이유는, API와 DB가 먼저 안정적으로 떠 있어야 프론트의 로그인/주문/운영 흐름을 바로 확인할 수 있기 때문입니다.
단순히 프로세스가 떴다고 끝이 아닙니다. 최소한 아래를 확인해야 "환경이 준비됐다"고 볼 수 있습니다.
storefront 첫 화면이 열린다admin 로그인 화면이 열린다이 네 가지가 확인되면 그다음부터는 기능 개발 문제로 넘어갈 수 있습니다.
로컬에서 자주 터지는 문제 중 하나가 base URL mismatch입니다.
예를 들어:
http://localhost:8000을 보는데http://127.0.0.1:8000을 보고불필요한 디버깅이 발생합니다.
따라서 이번 교재에서는 문서, env, 코드 예시 모두 같은 host 표기를 쓰는 것이 좋습니다. 보통 localhost로 통일하는 편이 설명하기 쉽습니다.
처음부터 너무 무거운 구성으로 가면 학습 난이도가 불필요하게 올라갑니다.
이번 교재의 목표는 "실전형이지만 따라갈 수 있는 구성"입니다. 따라서 최소 런타임부터 시작하고, 이후 장에서 확장하는 것이 맞습니다.
이번 교재를 따라 하는 학습자는 아래 정도를 목표로 잡으면 충분합니다.
services:
server:
...
db:
...
그리고 프론트는 아래처럼 별도 dev server로 붙여도 됩니다.
client/storefrontclient/admin또는 필요하면 compose에 프론트까지 포함해도 됩니다. 중요한 것은 방법이 하나로 고정되어 팀 전체가 같은 기준을 쓰는 것입니다.
.env 없이 각자 로컬 상수로 실행한다compose에 너무 많은 서비스를 한 번에 넣는다.env.example 없이 말로만 실행 방법을 전달한다이 다섯 가지 실수는 개발 초반부터 팀 속도를 크게 떨어뜨립니다.
이 페이지에서 우리는 로컬 개발환경을 같은 기준으로 맞추기 위해 compose, env, 포트, 서비스 이름, 실행 순서를 정리했습니다. 이제 누가 저장소를 받아도 같은 방식으로 backend와 DB를 띄우고, 같은 기준으로 storefront와 admin을 실행할 수 있는 바닥이 생겼습니다. 다음 페이지에서는 이 환경 위에서 실제 데이터 저장과 실행을 뒷받침하는 DB, 시크릿, 실행 스크립트 구성을 더 구체적으로 정리합니다.
다음 페이지에서는 DB, 시크릿, 스토리지, 실행 스크립트를 어떻게 정리해야 실전 개발이 흔들리지 않는지 더 구체적으로 설명합니다.