byteTuto EC2 배포
배포 체인
git pushonmain→.github/workflows/deploy.yml- test 작업 :
docker build,nginx -t, 스모크 테스트 (/healthz, 홈페이지, 404, CSP 헤더). - publish 작업 : 멀티 아키텍처(amd64 + arm64) 이미지를
ghcr.io/bytetuto/website:<sha7>및:latest에 푸시. - deploy 작업 : EC2에 SSH 접속,
/opt/bytetuto/.env작성,docker-compose.yml+deploy/*.sh복사,deploy/deploy.sh실행. deploy.sh: pull,up -d,/healthz대기(최대 40초). 실패 →.last_image의 이미지로 자동 롤백.
PR은 test 작업만 실행합니다.
GitHub Secrets / 변수 (Settings → Secrets and variables → Actions)
- Secrets :
EC2_HOST,EC2_USER(ec2-user 또는 ubuntu),EC2_SSH_KEY(전체 개인 키),EC2_KNOWN_HOSTS(권장:ssh-keyscan -H <ip>결과). - Variables :
DOMAIN(예: bytetuto.com),LETSENCRYPT_EMAIL. - GitHub
production환경 (수동 승인이 필요할 수 있음).
유용한 명령어 (EC2에서, /opt/bytetuto 디렉토리)
- 상태 :
docker compose ps· 로그 :docker compose logs -f web - 헬스 체크 :
curl -fsS http://127.0.0.1/healthz - 특정 버전 재배포 :
IMAGE=ghcr.io/bytetuto/website:<sha7> bash deploy/deploy.sh - 수동 롤백 : 이전 태그로
deploy.sh재실행 (GitHub Packages 탭에서 확인 가능). - HTTPS (DNS 설정 후, 한 번만) :
bash deploy/init-ssl.sh(먼저STAGING=1로 테스트). - 갱신 : cron
/etc/cron.d/bytetuto-certbot(하루 2회), 로그는certbot-renew.log.
nginx가 HTTP 또는 HTTPS를 선택하는 방법
nginx/40-bytetuto-ssl.sh가 컨테이너 시작 시 실행됩니다.
$DOMAIN에 대한 인증서가 있으면 → https.conf.template, 없으면 → http.conf.template.
init-ssl.sh 실행 후 docker compose restart web만 하면 됩니다.
빠른 진단
| 증상 | 원인 |
|---|---|
deploy 작업: Permission denied (publickey) | EC2_SSH_KEY / EC2_USER 오류 |
docker: permission denied | 사용자가 docker 그룹에 없음 → ec2-setup.sh 후 재접속 |
pull access denied | GHCR 패키지가 비공개이고 로그인 실패, 또는 패키지를 공개로 전환 |
| 외부에서 HTTP 타임아웃 | Security Group에서 포트 80/443이 열려 있지 않음 |
| certbot 실패 | DNS가 아직 전파되지 않았거나 포트 80이 닫힘 |
exec format error | 아키텍처: 이미지가 멀티 아키텍처인지 확인 |
규칙
.env, SSH 키 또는certbot/을 읽거나 표시하지 않음.git push,ssh,scp또는deploy/및 워크플로 수정 시 확인 요청.