first commit

PRODUCTION_DEPLOYMENT.md

@@ -0,0 +1,80 @@
+# sourcehub.nexpa-ai.com 교체 절차
+
+## 0. 원칙
+3.8은 Production Candidate입니다. 실제 운영 Credentials를 넣기 전에는 `production_ready=false`가 정상입니다.
+기존 3.2 사이트를 바로 덮어쓰기 전에 DB/파일 백업과 별도 포트 검증을 먼저 수행합니다.
+
+## 1. 기존 서버 백업
+- 현재 SourceHub 소스 디렉터리 전체 백업
+- DB 백업
+- 업로드 파일/첨부 파일 백업
+- 현재 Nginx/Reverse Proxy 설정 백업
+
+3.8 자체 백업 도구:
+```bash
+python scripts/backup.py --out backups
+```
+
+## 2. Production 환경파일
+`.env.production.example` → `.env.production` 복사 후 모든 `CHANGE_ME` 교체.
+
+필수 Gate:
+- PostgreSQL
+- MinIO
+- ClamAV
+- NEXPA Core OIDC
+- Secure Session Cookie
+- CSRF
+- HSTS
+- Session/Download Secret
+
+배포 Executor는 초기 전환 시 `disabled` 유지 권장.
+
+## 3. DB Migration
+```bash
+alembic upgrade head
+```
+
+## 4. 신규 버전 별도 기동
+```bash
+docker compose -f docker-compose.production.yml up -d --build
+```
+SourceHub 3.8 컨테이너는 `127.0.0.1:18000`에만 노출합니다.
+기존 SourceHub(python3)가 호스트 `8000`을 사용 중이므로 병렬 기동 시 8000을 재사용하지 않습니다.
+Gitea는 `deploy/gitea/docker-compose.yml` 기준 `127.0.0.1:3200`(웹), `2222`(SSH)입니다.
+
+## 5. 내부 검증
+- `/health` 200
+- 로그인 전 `/` → NEXPA Core 로그인 화면만 표시
+- `/static/index.html` → 404
+- OIDC 로그인
+- 7개 Current Baseline 확인
+- 파일 업로드 → ClamAV → SHA-256 → R1
+- R2 추가 시 R1 유지
+- 만료형 다운로드 URL 확인
+- 역할별 승인 권한 확인
+- Gitea 바인딩 확인
+- Production 배포 Gate 확인
+
+## 6. Nginx 전환
+`deploy/nginx-sourcehub.conf`를 서버 환경에 맞게 적용.
+인증서 경로 확인 후 Nginx config test를 수행합니다.
+
+## 7. 최종 전환
+기존 3.2 프로세스를 중단하고 3.8 upstream으로 교체.
+
+## 8. 전환 후 30분 점검
+- 4xx/5xx 로그
+- OIDC callback
+- MinIO 저장
+- ClamAV 응답
+- PostgreSQL connection
+- 파일 다운로드
+- 감사 로그
+
+## Rollback
+문제 발생 시 Nginx upstream을 기존 서비스로 복귀하고, 필요한 경우:
+```bash
+python scripts/restore.py --db <backup> --storage <storage-backup> --yes-really-restore
+```
+PostgreSQL/MinIO 운영환경은 pg_restore 및 MinIO versioning/replication 절차를 우선 사용합니다.