지난 글(2025년 11월 30일)에서는 DevHistory의 기본 흐름을 만들었습니다.
GitHub, solved.ac, Velog 데이터를 모아서 대시보드로 보고, 블로그 초안 만들고, 포트폴리오까지 뽑아내는 구조였습니다.
그때는 솔직히 이렇게 생각했습니다.
“기능은 다 돌아가네. 이제 서버에 올리고 배포만 하면 되겠다.”
하지만 완벽한 착각이었습니다. 실제로 계속 돌려보니, 개발 시간보다 더 많이 든 건 전혀 다른 쪽이었습니다.
새로운 기능을 화려하게 추가하는 일보다, 이미 있는 기능이 실제 환경에서 끝까지 동작하는지 확인하고, 실패했을 때 사용자에게 현재 상태를 납득시키는 작업이 훨씬 어렵고 오래 걸렸습니다.
이번 글은 토이 프로젝트를 실제 서비스로 다듬어가는 안정화 과정의 기록입니다.
서비스 첫 진입 화면
수집된 데이터를 한눈에 확인하는 대시보드
1) 2025-11-30 기준, 이미 되던 것들
당시에는 아래 파이프라인이 동작했습니다.
- GitHub OAuth 로그인
- GitHub / solved.ac / Velog 데이터 동기화
- 대시보드 지표/차트 렌더링
- 레포 기반 블로그 초안 생성
- 포트폴리오 페이지 + PDF 내보내기
즉, 수집 → 집계 → 생성 → 출력의 큰 뼈대는 완성돼 있었습니다.
이후의 과제는 “왜 가끔 안 되는지”, “안 될 때 사용자에게 어떻게 보이는지”의 구멍을 메우는 것이었습니다.
2) 이번 사이클에서 크게 바뀐 점
2-1. 생성 UX: 비동기 흐름 정리
코딩 코치(퀴즈 생성)나 AI 글쓰기 기능에서 아주 치명적인 UX 문제가 있었습니다.
- 생성 버튼 클릭
- 한참을 돌다가 실패 메시지 팝업
- 그런데 결과 목록을 새로고침해보면 이미 생성되어 있음
원인은 백엔드 처리 완료 시점과 프론트엔드의 타임아웃 기준이 엇갈렸기 때문입니다. 백엔드는 일을 끝냈는데 프론트가 먼저 지쳐버린 거죠.
그래서 무작정 기다리는 동기 방식을 버리고, 비동기 폴링(Polling)으로 흐름을 바꿨습니다.
- 초기 요청 시 대기하지 않고
task_id만 즉시 반환 - 프론트에서 폴링으로 백그라운드 상태 확인
- 완료되면 즉시 화면에 렌더링
❌ [Before] 타임아웃 지옥
요청 전송 → 프론트 타임아웃(실패 팝업) → 백엔드 작업 뒤늦게 완료
✅ [After] 비동기 UX 안정화
task_id 반환 → 상태 폴링 → 완료 시 정상 반영
2-2. 인증/보안: 로그인 "성공"보다 운영 "신뢰"
초기에는 "소셜 로그인이 뚫렸다"는 사실 자체에 만족했습니다. 하지만 배포를 앞두고 기준을 엄격하게 올렸습니다.
httpOnly쿠키 중심의 안전한 인증 흐름- 로그인/로그아웃 세션 동선 명확화
- 사용자별 BYO LLM API Key 저장/검증/테스트/삭제
- API Key 암호화 저장 보완
사용자가 자신의 API 키를 입력해야 하는 서비스 특성상, 내 데이터와 키가 안전하다는 전제가 없으면 아무리 좋은 기능도 무용지물이기 때문입니다.
2-3. 동기화: 성공률보다 실패 가시성
데이터 동기화 버튼은 겉보기엔 단순하지만, 실패 시나리오를 어떻게 다루느냐에서 신뢰가 갈렸습니다.
- GitHub 소유 레포 기준(
owner) 필터 검증 추가 - 로그인 직후 텅 빈 화면을 막기 위한 동기화 자동 큐잉
- 동기화 상태 및 실패 상황을 사용자 기준으로 확인 가능하게 개선
성공 횟수보다 중요한 건, “실패했다면 왜 안 되는지 명확히 보여주는 것”이었습니다.
2-4. 포트폴리오: 개인 화면에서 공유 결과물로
포트폴리오는 혼자 뿌듯해하는 화면이 아니라, 남에게 전달되는 결과물입니다.
- 공개 URL(
slug) 및 비공개 토큰 링크 공유 기능 - 토큰 재발급/만료 관리 로직
- 이메일 등 민감 정보 공개 제어
특히 고민이 많았던 건 PDF 출력입니다.
브라우저 환경에 따라 폰트나 레이아웃이 깨지는 변수를 통제하기 위해, 현재는 가장 안정적인 화면 캡처 방식의 PDF 저장을 우선 적용해 두었습니다. 당장의 '실사용 안정성'을 위해 타협한 부분이며, 향후 텍스트 보존성이 높은 네이티브 방식으로 고도화해 나갈 계획입니다.
2-5. 배포 준비: 코드보다 운영 비중 증가
이 시점부터는 IDE에서 코드를 치는 시간보다 인프라 세팅 비중이 훨씬 커졌습니다.
- 프로덕션용 Docker Compose 작성
- Caddy 기반 HTTPS 라우팅 및 인증서 설정
- 마이그레이션/운영/보안 문서 정리
- 환경변수/쿠키 도메인/OAuth 콜백 최종 점검
직접 겪어보니 배포는 "코드가 실행된다"의 문제가 아니라, "장애 발생 시 어떻게 확인하고 복구할 것인가"를 준비하는 과정이었습니다.
2-6. 현실적인 고민: devhistory.kr + Oracle Free Tier
로컬 개발이 끝나고 운영 현실의 벽과도 마주했습니다.
devhistory.kr도메인 도입 검토- 서버 비용 방어를 위한 Oracle Cloud Free Tier 등록 시도
악명 높은 오라클 가입 단계에서 막히는 케이스가 계속 반복됐습니다.
그래서 무작정 '무료'에 시간을 쏟기보다는, 약간의 비용을 감수하더라도 예측 가능하고 바로 구축할 수 있는 다른 인프라 대안도 함께 검토하고 있습니다.
3) 이번 구간에서 배운 것 5가지
- 새로운 기능 추가보다 기존 기능의 실패 경험 감소가 우선이다.
- 비동기 처리는 백엔드 로직뿐 아니라 프론트 UX를 함께 설계해야 한다.
- 지표는 계산하는 것보다 정의를 통일하는 것이 먼저다.
- PDF 출력은 단순 UI 기능이 아니라 렌더링 엔지니어링 이슈에 가깝다.
- 문서화는 개발 속도를 늦추지 않는다. 오히려 장애 복구 속도를 비약적으로 높인다.
4) 현재 상태와 다음 단계
현재 DevHistory는 아래 단계까지 완료되었습니다.
- 수집 파이프라인 실사용 동작 검증
- 생성 기능 비동기 흐름 전면 개편
- 포트폴리오 공유/출력 품질 보강
- 운영 체크리스트 기반 배포 준비
다음 단계는 실제 운영 환경에서 아래 항목들을 테스트하는 것입니다.
- 도메인/DNS/HTTPS 최종 연결
- OAuth 콜백/쿠키 도메인 정합성 확인
- 실사용 트래픽 기준 병목 확인
다음 글에서는 배포를 완료하고, 실제 트래픽을 받으며 겪은 운영 트러블슈팅 후기를 정리해 가져오겠습니다 🙌
혹시 사이드 프로젝트 배포하실 때 비슷한 고민을 해보셨거나, 추천하시는 인프라 조합이 있으시다면 댓글로 알려주세요! (오라클 프리티어와 사투 중입니다 😥)
배포 직전의 시행착오가 누군가에게 작은 참고가 되었으면 좋겠습니다.
재밌게 읽으셨다면 공감(💚) 부탁드립니다.
참고
- 이전 글: DevHistory - 개발 포트폴리오 자동화 플랫폼 만들기
- GitHub: DevHistory
