20강. 최종 실습: 기초집 학습 사이트 배포·점검·운영 체크리스트 완성

?1. 이번 강의에서 해결할 문제

최종 결과는 배포 URL 하나가 아니라 다른 사람도 반복할 수 있는 검증·배포·점검·복구 절차입니다. 정상과 실패 시나리오를 모두 포함합니다.

✓2. 학습 목표

✓이 강의를 마치면

• Docusaurus Pages 전체 흐름을 실행 가능한 체크리스트로 정리합니다.
• 홈·강의·사이드바·모바일·404와 비밀 비노출을 검증합니다.
• 배포 실패 한 가지와 revert 기반 복구 절차를 설명합니다.

◇3. 핵심 개념

운영 체크리스트는 변경 SHA, 실행 명령, 예상 결과, 실제 결과, 담당자와 시간을 남깁니다. 현재 사이트는 source→npm ci→npm run build→Pages artifact→deploy→사용자 점검 흐름입니다. 공개 정적 구조라 서버 비용 없이 운영할 수 있지만 FastAPI 실행, 중앙 진도 저장, 로그인·DB는 제공하지 않습니다.

✎4. 단계별 실습

1. PowerShell

실행 위치: 저장소 루트

실행 전 확인: 예상 변경만 있는지 확인하고 실제 비밀이 출력되면 공유하지 않습니다.

대상: 배포 전 소스·lockfile·build·비밀 패턴

PowerShell

git status --short --branch
git diff --check
npm.cmd ci
npm.cmd run build
git ls-files .env .env.local
git grep -n -I -E "BEGIN .*PRIVATE KEY|API_TOKEN=.+|PASSWORD=.+"

예상 결과: 의도한 변경만 있고 build가 성공하며 추적된 .env와 실제 비밀 패턴이 없습니다.

2. 파일 편집

실행 위치: 저장소 루트

실행 전 확인: 기존 .gitignore를 덮어쓰지 말고 같은 규칙이 이미 있는지 확인합니다.

대상: .gitignore의 로컬 비밀 제외 규칙

.gitignore에 추가할 예시

.env
.env.*
!.env.example
*.pem
*.key

예상 결과: 문서화용 .env.example만 공유할 수 있고 실제 환경 파일과 개인 키는 추적에서 제외됩니다. 이미 추적된 파일은 ignore만으로 사라지지 않으므로 git ls-files로 별도 확인합니다.

3. GitHub 웹 화면

실행 위치: PR → Actions → Pages deployment

실행 전 확인: base/compare, build 결과와 배포 SHA를 확인합니다.

대상: 검토된 main 커밋과 배포 URL

GitHub 웹 화면

1. PR diff·build 확인
2. main 병합
3. Pages build·deploy job 확인
4. page_url과 배포 SHA 기록
5. 실패하면 새 변경 중지 후 최초 오류 확인

예상 결과: 검토한 SHA와 배포된 SHA가 일치하고 배포 기록이 남습니다.

4. 브라우저·PowerShell

실행 위치: 실제 Pages URL

실행 전 확인: 가상 example-learner 주소를 실제 공개 주소로 바꾸고 인증 값은 사용하지 않습니다.

대상: 홈·강의·사이드바·모바일·404·에셋

브라우저·PowerShell

$site = "https://example-learner.github.io/dev-foundations"
$paths = @("/", "/docs/curriculum", "/does-not-exist")
foreach ($path in $paths) {
  try { $r = Invoke-WebRequest -Uri "$site$path"; "$path $($r.StatusCode)" }
  catch { "$path $([int]$_.Exception.Response.StatusCode)" }
}

예상 결과: 홈과 강의는 성공하고 없는 경로는 의도한 404이며 브라우저에서 사이드바·모바일·에셋도 정상입니다.

5. 복구 훈련

실행 위치: 운영 문서와 별도 복구 브랜치

실행 전 확인: 마지막 정상 SHA와 문제 SHA를 기록하고 reset·force push를 사용하지 않습니다.

대상: 가상 build 실패 커밋 한 개

복구 훈련

1. 새 배포 중지
2. 로컬 build로 재현
3. Actions 최초 실패 step 기록
4. 문제 SHA 확인
5. 별도 브랜치에서 git revert
6. build·PR 검토
7. 배포 후 사용자 경로 재점검

예상 결과: 이력을 지우지 않고 실패 원인·복구 커밋·검증 결과가 연결됩니다.

→5. 배포·운영 흐름이 동작하는 이유

배포 전 build와 비밀 검사가 잘못된 artifact를 막고, GitHub Actions가 동일한 절차를 깨끗한 환경에서 반복합니다. 배포 후 사용자 경로 검증이 실제 서비스 결과를 확인하며 revert 절차가 빠르고 추적 가능한 복구를 제공합니다.

!6. 자주 하는 실수와 안전한 해결법

!자주 하는 실수

• 실수: 배포 성공 배지만 확인하고 사용자 화면 생략 안전한 해결: 홈·강의·사이드바·모바일·404·Network를 확인합니다.
• 실수: .gitignore만 믿고 이미 추적된 비밀을 놓침 안전한 해결: git ls-files와 패턴 검색을 함께 사용합니다.
• 실수: 복구 절차를 장애 중 처음 생각 안전한 해결: 문제 SHA와 정상 SHA를 사용하는 revert 훈련을 미리 문서화합니다.

✎7. 직접 실습

✎직접 실습

1. 배포 전 명령과 완료 기준을 실행 기록표로 만듭니다.
2. 배포 후 여섯 사용자 점검 항목을 확인합니다.
3. .gitignore에 .env, .env.*, !.env.example, 개인 키 패턴을 설명과 함께 설계합니다.
4. build 실패 시나리오와 revert 복구 흐름을 작성합니다.
5. 정적 Pages와 FastAPI 서버의 기능·비용·운영 차이를 최종 표로 정리합니다.

실습 기록에는 변경 SHA, 실행 위치, 확인 대상, 예상 결과와 실제 결과를 남기고 실제 토큰·비밀번호·SSH 개인 키·.env 내용은 포함하지 않습니다.

?8. 이해 점검 질문 3개

?이해 점검

1. 최종 배포 완료를 증명하는 소스·workflow·사용자 결과는 무엇인가요?
2. .gitignore 외에 추적 비밀을 확인할 명령은 무엇인가요?
3. 현재 구조가 월 비용 0원으로 가능한 대신 제공하지 않는 기능은 무엇인가요?

■9. 핵심 요약

■핵심 요약

기초집 사이트 운영은 build·비밀 검사, 검토된 main, Pages artifact, 사용자 경로 확인과 revert 복구로 완성됩니다. 정적 구조의 0원 장점과 서버 기능 한계를 함께 기록했습니다.