docs: v0.3.5 세션 누적 암묵지 반영 #61

Merged

xhh merged 1 commit from docs/session-tacit-knowledge-v0.3.5 into main

2026-04-26 04:22:41 +09:00

xhh commented

2026-04-26 04:15:36 +09:00

Owner

이번 세션의 새 함정 패턴 5건 (Docker chmod, lifespan create_all, Streamlit + reverse proxy, Tailscale serve, CI Runner 재시도) 정리.

xhh added 1 commit

2026-04-26 04:15:36 +09:00

docs: v0.3.5 세션 누적 암묵지 반영

Tests (PR) / pytest (pull_request) Successful in 29s

Details

010fb1ab63

이번 세션에서 부딪힌 새 함정 패턴 5건 정리:

1. Docker chmod 방어 (확장)
   - 새 컨테이너 추가 시 chmod -R a+rX 단계 빠뜨리지 말 것
   - Streamlit Dockerfile 누락이 v0.3.2 'Permission denied: app.py' 유발
   - Streamlit data 볼륨 read-only 마운트 (#54 까지 임시)

2. DB 스키마 자동 동기화 (lifespan create_all)
   - v0.3.0 배포 실패 사례 (gdpnow_vintages 누락 → /api/health 503)
   - lifespan 에서 Base.metadata.create_all 호출, idempotent
   - 컬럼 변경은 별도 alembic 이슈

3. Streamlit + reverse proxy 운영 패턴
   - 단일 URL + JS 프로브 + 사이드바 토글 fallback 설계
   - Mixed content: HTTPS 페이지에서 HTTP fetch 차단
   - components.html iframe 격리: window.parent.location 필수
   - UI 게이트는 편의, 실보안은 require_private_origin
   - Bootstrap 폴백 (UI 가 자동으로 /bootstrap 시도)
   - reverse proxy 뒤 Streamlit 의 /<page>/_stcore/health 404 무해

4. NAS Tailscale serve 운영
   - tailscale serve --bg 로 HTTPS 리버스 프록시 영속화
   - network_mode: host 면 localhost = 호스트
   - 포트 컨벤션: HTTPS = 평문 + 10000, 443 인덱스 예약
   - userspace-networking 검증은 다른 tailnet 피어에서

5. CI Runner transient 실패 재시도
   - astral.sh 같은 외부망 일시 단절은 빈 커밋으로 재트리거

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>