AWS 배포 A-Z 배포 여정 — 처음 배우는 사람을 위한 전체 정리

🚀 Alpha-Helix 배포 여정 — 처음 배우는 사람을 위한 전체 정리

로컬에서 돌던 웹앱을 진짜 인터넷 주소(https://quant-alphahelix.com) 로 띄우기까지.
Docker · AWS · 도메인 · HTTPS · 구글 로그인 · 자동배포(CI/CD) 를 하나씩.

---

🗺️ 큰 그림 — 우리가 만든 것

3개의 프로그램이 협력하는 웹서비스예요:

[브라우저] → (인터넷) → [프론트엔드(React)] → [백엔드(Spring Boot)] → [DB(MySQL)]
                                                      ↘ [분석서버(FastAPI, 파이썬)]

이걸 내 노트북이 아니라 24시간 켜진 서버(AWS EC2) 에 올려서, 누구나 주소로 접속하게 만드는 게 "배포"예요.

---

1️⃣ Docker — "내 컴퓨터에선 되는데?" 를 없애는 도시락

문제: 프로그램은 OS·버전·설정이 조금만 달라도 안 돌아가요. 내 노트북에선 되는데 서버에선 안 되는 일이 흔하죠.

Docker = 프로그램 + 필요한 환경을 통째로 "도시락(이미지)"에 담는 기술. 그 도시락은 어디서 열든 똑같이 돌아가요.

• 이미지(Image) = 도시락 (레시피대로 만든 결과물)
• 컨테이너(Container) = 그 도시락을 실제로 데워 먹는 것(실행 중인 상태)
• Dockerfile = 도시락 만드는 레시피
• docker-compose.yml = 여러 도시락(우리는 4개: db·backend·analytics·frontend)을 한 번에 차리는 상차림표

우리가 한 일: 4개 서비스의 Dockerfile + compose 작성 →

docker compose up -d --build   # 한 줄로 전체 스택 기동

한 방에 전부 뜨게 만들었어요. (백엔드 도시락 안엔 Claude CLI도 같이 넣어서, BYOK 키만 있으면 AI가 코드 편집까지 함)

💡 배운 점: Docker는 "한 번 만들면 어디서나 똑같이"가 핵심. 배포의 환경 차이 문제를 통째로 없애줘요.

---

2️⃣ 로컬에서 먼저 검증 — 그리고 만난 버그들

서버에 올리기 전에 내 노트북의 Docker에서 먼저 띄워봤어요. 여기서 진짜 문제들을 잡았죠.

🐞 문제 ①: 백엔드가 DB에 연결 못 함 (Access denied for user 'root')

• 증상: 백엔드가 자꾸 재시작, DB 접속 실패.
• 추적: 분명 설정엔 alpha 유저인데 런타임은 root로 접속. 호스트도 db가 아니라 localhost로 풀림.
• 진짜 원인(중요!): application-local.properties(내 로컬 전용 설정 — 로컬 DB는 root/비번, 게다가 실제 이메일까지 적혀있음)가 Docker 이미지 안에 같이 들어가 버려서, 서버용 설정을 덮어쓰고 있었어요.
• 해결: .dockerignore에 그 파일을 추가해 이미지에서 배제.
• 💡 이건 보안 문제이기도 해요. 로컬 비번·이메일이 배포물에 새어 들어가면 안 되니까. 한 방에 기능+보안 둘 다 해결.

🐞 문제 ②: 회원가입이 500 에러 (CORS)

• 원인: "아무 출처나 허용(*)" + "쿠키 인증 허용"을 동시에 켜면 안 된다고 브라우저 규칙이 막아요.
• 해결: *일 땐 allowedOriginPatterns 방식을 쓰도록 코드 수정. (쿠키는 SameSite=Lax라 CSRF는 따로 방어됨)

💡 배운 점: 로컬에서 먼저 돌려보면 이런 버그를 서버 올리기 전에 잡을 수 있어요. "로컬 검증 → 서버 배포" 순서가 중요.

---

3️⃣ AWS EC2에 올리기 — "남의 컴퓨터(클라우드)"에 접속

EC2 = AWS가 빌려주는 24시간 켜진 컴퓨터(서버).

SSH — 내 PC에서 그 서버로 원격 접속

ssh -i "C:\...\who-a.pem" ec2-user@<서버IP>

• who-a.pem = 서버 문 여는 열쇠 파일(인스턴스 만들 때 받음)
• ec2-user = 서버의 로그인 이름(Amazon Linux 기본값)
• 접속되면 프롬프트가 [ec2-user@...]$ 로 바뀜 = 이제부터 명령은 "서버 안에서" 실행

🐞 만난 것: 윈도우에서 .pem 권한이 너무 열려서 SSH가 거부 → icacls로 "나만 읽기"로 잠그니 해결.

서버에서 한 일 (순서대로)

1. 옛 서비스 정지 (포트 80 비우기) + 스왑 메모리 (빌드 중 메모리 부족 방지)
2. Docker 설치
3. 코드 받기 (git clone) — 비공개 repo라 GitHub 토큰(PAT) 필요
4. .env 만들기 — 비밀키들을 openssl rand로 자동 생성
5. docker compose up -d --build — 도시락 4개 빌드+기동

🐞 만난 것: compose build requires buildx 0.17+ → 서버의 빌드 도구(buildx)가 구버전 → 최신 buildx 받아 해결.

✅ 결과: http://<서버IP> 로 사이트가 떴어요!

---

4️⃣ "로그인이 안 돼!" — HTTP(비보안 주소) 특유의 함정 2개

사이트는 떴는데 로그인 페이지가 크래시. 원인이 http://(보안 안 된 주소) 라서 생기는 것들이었어요.

🐞 함정 ①: crypto.randomUUID is not a function

• 이 브라우저 기능은 HTTPS나 localhost에서만 존재해요. http://공인IP에선 없어서 호출 즉시 페이지가 터짐.
• 해결: 없으면 대체로 채워주는 폴리필을 진입점(main.jsx)에 추가.

🐞 함정 ②: Missing required parameter client_id (구글)

• 구글 로그인 키가 빌드에 없어서, 구글 OAuth 초기화가 렌더 중 터짐.
• 해결: 키 없으면 크래시만 막고(더미값) 소셜 버튼은 숨김 → 이메일 가입만 깔끔히 노출.

💡 배운 점: "로컬(localhost)에선 되는데 배포에선 안 되는" 건 보통 HTTPS·환경변수 차이 때문. 이게 배포의 단골 함정이에요.

✅ 여기까지: 이메일 회원가입·로그인 정상 작동!

---

5️⃣ 도메인 + HTTPS — 진짜 주소 + 자물쇠🔒

http://숫자IP는 못생기고, 구글 로그인도 안 받아줘요(구글은 https://도메인만 허용). 그래서:

① Elastic IP — 서버 IP를 "영구 고정"

• EC2의 IP는 서버를 껐다 켜면 바뀌어요. 도메인을 붙여도 재시작하면 깨짐.
• AWS에서 Elastic IP(고정 IP) 를 할당 → 인스턴스에 연결 → IP가 영구 고정.

② 도메인 구매 + DNS 연결 (Cloudflare)

• quant-alphahelix.com 구매 → Cloudflare에 등록
• DNS A 레코드: 도메인 → Elastic IP (이게 "전화번호부": 도메인 입력하면 이 IP로 보내줘)
• 프록시 ON(주황 구름): 트래픽이 Cloudflare를 거쳐감 → 보안·캐싱·무료 HTTPS 제공

③ HTTPS 켜기 (Cloudflare Flexible)

• Cloudflare SSL/TLS 모드를 Flexible로.
• → 방문자↔Cloudflare는 HTTPS(자물쇠), Cloudflare↔우리서버는 HTTP. 서버에 인증서 설치 0으로 https 완성.

💡 용어: DNS = 도메인↔IP 전화번호부 · SSL/TLS = 통신 암호화(자물쇠) · 프록시 = 중간에서 대신 받아주는 문지기.

✅ https://quant-alphahelix.com 으로 자물쇠🔒 달고 접속!

---

6️⃣ 구글 로그인 켜기

이제 https 도메인이 생겼으니 구글이 받아줘요.

1. 구글 클라우드 콘솔 → OAuth 동의 화면 + OAuth 클라이언트 ID 발급
2. 승인된 JavaScript 원본에 https://quant-alphahelix.com 등록 (← "이 주소에서 오는 구글 로그인만 허락")
3. 발급된 클라이언트 ID(...apps.googleusercontent.com)를 빌드에 주입
   • frontend Dockerfile이 VITE_GOOGLE_CLIENT_ID 빌드 인자를 받게 수정 → .env에 키 넣고 재빌드
4. → 구글 버튼이 나타나고, 진짜 구글 로그인 작동!

💡 OAuth = "구글한테 로그인 대신 시키고, 구글이 '이 사람 맞아' 확인해주는" 방식. 키(client_id)로 우리 앱을 식별해요.

---

7️⃣ CI/CD 자동배포 — git push 하나면 끝 🤖

매번 서버 들어가서 git pull + 빌드 하는 손작업을 로봇이 대신:

• CI/CD = 코드 올리면 자동으로 빌드·검사·배포까지 해주는 컨베이어벨트
• GitHub Actions = GitHub이 공짜로 주는 그 로봇. .github/workflows/deploy.yml에 "할 일"을 적어둠
• 우리 로봇의 일: "flow_finish에 push 들어오면 → 임시 컴퓨터가 EC2에 SSH 접속 → git pull + docker 재빌드"
• 필요한 것: GitHub Secrets 3개 (EC2_HOST·EC2_USER·EC2_SSH_KEY)에 서버 접속정보 등록

✅ 이제 git push 하나면 서버가 알아서 최신화돼요.

---

📚 핵심 용어 사전 (한 줄 정리)

용어	한 줄 설명
Docker	프로그램+환경을 도시락(이미지)에 담아 어디서나 똑같이 실행
이미지 / 컨테이너	도시락 / 데워 먹는 중(실행 상태)
볼륨(Volume)	컨테이너가 죽어도 데이터(DB 등)를 보존하는 저장공간
EC2	AWS가 빌려주는 24시간 서버
Elastic IP	재시작해도 안 바뀌는 고정 IP
SSH	내 PC에서 서버로 원격 접속(열쇠=.pem)
DNS / A레코드	도메인↔IP 전화번호부
HTTPS / SSL	통신 암호화(브라우저 자물쇠🔒)
프록시(Cloudflare)	트래픽을 중간에서 받아 보안·HTTPS·캐싱 제공
OAuth	구글/깃헙 같은 외부 계정으로 로그인하는 방식
PAT	GitHub 비공개 접근용 토큰(비번 대용)
CI/CD	push하면 자동 빌드·배포해주는 자동화
버스터블(t3)	평소 저전력, 잠깐만 고성능. 오래 무거우면 느려짐(크레딧 소진)

---

🎯 한 줄 회고

처음엔 "로컬에서 되는 걸 그냥 올리면 되겠지" 였지만, 실제론
환경 차이(Docker) → 시크릿 누출(.dockerignore) → HTTP 함정(crypto·OAuth) → 고정IP·도메인·HTTPS → 외부로그인 → 자동화
순서로 하나씩 풀어야 했어요. 각 단계는 "왜 필요한가"를 알면 안 무서워요. 막히는 에러는 대부분 로그 한 줄에 답이 있고요.

이제 우리 서비스는 진짜 인터넷에 살아있습니다. 🌐✨