Feature #1265
openFeature #1226: [MDGU] 학사관리 시스템 v1 개발 (8주, 2026-11-05 시작)
Feature #1237: [MDGU-04] 인프라·배포 (성용)
[MDGU-04-03] Dockerfile·Compose·/health/·Gunicorn·Nginx 연결·운영 설정
100%
Description
목적¶
서버에서 Docker Compose로 앱과 DB를 올리고 Nginx에서 연결합니다. 운영 설정(DEBUG=False, 보안 쿠키 등)도 여기서 맞춥니다. (가이드 7~9절)
쉬운 설명¶
앱과 DB를 Docker Compose로 묶어 서버에서 실행하고 Nginx와 연결하며 운영용 설정(DEBUG 끄기, 보안 쿠키 등)을 맞춥니다.
기술 스택¶
Docker, Docker Compose, Python 3.12 이미지, WeasyPrint 네이티브 라이브러리와 한글·영문·중문 폰트, Gunicorn(127.0.0.1:8000), Nginx, Django production settings.
예상 결과(산출물)¶
Dockerfile, compose.prod.yml(DB 컨테이너 포함안), compose.cloudsql.yml(운영 적용안, Cloud SQL), .env.example, /health/ 엔드포인트, settings/production.py, Nginx 설정.
개발 작업 상세¶
- Dockerfile: Python 고정 버전, WeasyPrint 의존 라이브러리·폰트, non-root 사용자, Gunicorn.
- compose.prod.yml: web과 PostgreSQL 18 db, healthcheck, 영속 볼륨, 내부 네트워크. DB 5432 host publish 금지, Gunicorn은 127.0.0.1 바인딩.
- settings/production.py: DEBUG=False, ALLOWED_HOSTS, CSRF_TRUSTED_ORIGINS, secure cookies, 보안 헤더.
- /health/ 비민감 엔드포인트(config/urls.py 한 줄은 우섭에게 요청).
- Nginx를 Gunicorn에 연결하고 HTTPS·리디렉션 유지, 정적 파일만 공개하고 보호 파일은 공개 alias 금지.
- 로컬 Docker에서 build·up·ps·
check --deploy·migrate --plan을 확인한다(실제 운영 migrate는 승인 후).
완료 기준¶
- 컨테이너가 healthy 상태로 올라온다.
manage.py check --deploy경고가 없거나 기록되어 있다.- DB 포트가 외부에 노출되지 않는다.
충돌 방지(소유 범위)¶
Dockerfile, compose*.yml, nginx/, deploy/, config/settings/production.py는 성용 소유(예외적으로 config 하위 production.py만 성용). 다른 settings 파일은 우섭 소유입니다.
선행·후행·위험¶
선행: 00-02 DB 분리 수준 확정(김예주, 11/13 종료) / 04-01 VPS 생성·SSH·방화벽·DNS·Nginx 임시 페이지·HTTPS(성용, 11/13 종료)
후행: 04-04 승인형 CD·마이그레이션 게이트·배포 점검(성용) / 04-05 암호화 백업·복원 훈련(성용) / 11-01 증명서 PDF 기반(WeasyPrint·3개 국어 폰트·템플릿 엔진)(서현) / 14-03 이관 리허설·정합성 보고서(서현) / 15-02 UAT 환경 준비·대학 담당자 교육(서현)
위험: WeasyPrint 폰트·라이브러리 의존성은 Docker에서 먼저 검증.
결과 확인 방법¶
"완료 기준"의 각 항목을 화면 또는 명령으로 직접 확인합니다.
- 컨테이너가 healthy 상태로 올라온다.
manage.py check --deploy경고가 없거나 기록되어 있다.- DB 포트가 외부에 노출되지 않는다.
- 확인 결과(화면 캡처 또는 명령 출력 요약)를 일감 메모에 남긴다.
갱신 사항 (2026-11-04)¶
- PostgreSQL은 18로 통일하고 이미지 태그를 고정한다.
- 환경변수 이름이 구현(DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT)과 배포 가이드 8.2(DATABASE_URL, POSTGRES_)가 다르다. 성용이 운영 compose 매핑을 정하고 .env.example과 가이드를 한 계약으로 통일한다(기본 가정: 구현의 DB_).
시작 전 준비¶
- 00-01·00-03 결정 내용과 팀 비밀 저장소(접속 정보 보관 위치)를 확인한다.
- 개발 가이드 7~9절을 읽는다.
- 서버 비밀번호·키·토큰은 일감, 저장소, 채팅에 적지 않는다.
작업 진행 순서¶
- "개발 작업 상세"를 순서대로 진행하며 각 단계의 명령과 결과를 기록한다.
- 한 단계가 끝날 때마다 "완료 기준"의 확인 항목을 점검한다.
- 설정 파일은 저장소에 올리고, 비밀 값은 비밀 저장소(GitHub Secrets 등)에만 둔다.
- PR로 올려 소유자 리뷰를 받고, 서버 작업 내용은 일감 메모에 남긴다.
막힐 때 확인¶
컨테이너가 계속 재시작되면 docker compose logs 서비스명으로 오류를 보세요. DB 포트는 외부에 열지 마세요.
그래도 해결되지 않으면 일감 메모에 "무엇을 했고, 어떤 오류가 났는지"를 붙여 담당 분류 소유자 또는 팀장에게 질문하세요.
용어 풀이¶
- 마이그레이션: 모델(코드)의 변경을 DB 구조에 반영하는 변경 기록 파일과 그 적용 작업입니다. makemigrations로 만들고 migrate로 적용합니다.
- WeasyPrint: HTML과 CSS로 만든 문서를 PDF로 바꿔 주는 Python 도구입니다. 증명서 PDF를 만드는 데 사용합니다.
- Docker·Docker Compose: 프로그램과 실행 환경을 한 상자(컨테이너)로 묶어 어디서나 같은 방식으로 실행하게 해 주는 도구이고, Compose는 여러 상자(앱·DB)를 한꺼번에 켜고 끄게 해 줍니다.
- Gunicorn: Django 앱을 실제 서버에서 실행해 주는 프로그램입니다.
- Nginx: 웹 요청을 받아 앱(Gunicorn)이나 정적 파일로 전달하고 HTTPS를 처리하는 웹 서버입니다.
- HTTPS: 주소창의 자물쇠 표시입니다. 통신 내용을 암호화합니다.
- /health/: 서버가 살아 있는지 확인하는 간단한 주소입니다. 이 주소가 정상 응답하면 앱이 실행 중이라고 봅니다.
- CSRF: 다른 사이트가 사용자 몰래 요청을 보내는 공격입니다. Django 기본 토큰으로 막습니다.
성양 Updated by 성용 양 19 days ago
- Due date changed from 11/20/2026 to 11/16/2026
- Start date changed from 11/17/2026 to 11/11/2026
- Follows Feature #1263: [MDGU-04-01] VPS 생성·SSH·방화벽·DNS·Nginx 임시 페이지·HTTPS added
성양 Updated by 성용 양 19 days ago
- Precedes Feature #1266: [MDGU-04-04] 승인형 CD·마이그레이션 게이트·배포 점검 added
성양 Updated by 성용 양 19 days ago
- Precedes Feature #1287: [MDGU-11-01] 증명서 PDF 기반(WeasyPrint·3개 국어 폰트·템플릿 엔진) added
성양 Updated by 성용 양 14 days ago
- Due date changed from 11/25/2026 to 11/19/2026
- Start date changed from 11/20/2026 to 11/16/2026
- Follows Feature #1244: [MDGU-00-02] DB 분리 수준 확정 added
성양 Updated by 성용 양 14 days ago
- Precedes Feature #1267: [MDGU-04-05] 암호화 백업·복원 훈련 added
성양 Updated by 성용 양 14 days ago
- Precedes Feature #1297: [MDGU-14-03] 이관 리허설·정합성 보고서 added
성양 Updated by 성용 양 14 days ago
- Precedes Feature #1300: [MDGU-15-02] UAT 환경 준비·대학 담당자 교육 added
성양 Updated by 성용 양 8 days ago
- Status changed from New to In Progress
- % Done changed from 0 to 50
[진행 기록 2026-11-09] 로컬 구현·검증 완료, PR 대기 (브랜치 feature/1265-docker-compose, 커밋 0db6e53, 아직 push·PR 전)
만든 것
- Dockerfile(Python 3.12, WeasyPrint 라이브러리·한/영/중 폰트, non-root, Gunicorn), .dockerignore, .gitattributes
- compose.prod.yml: db(PostgreSQL 18, 포트 미게시)·web(127.0.0.1:8000만)·migrate(별도 프로필), healthcheck, 영속 볼륨
- deploy/db/initdb.d: 학사 DB와 개인정보 DB를 분리 생성(초기화 관리자·migrate 계정·app 계정 3종, app은 DML만)
- /health/, production 설정(프록시 HTTPS 헤더, STATIC_ROOT, HSTS 환경값), Nginx 설정 예시, deploy/README.md
- CI에 PII_DB_* 환경변수와 PII 테스트 DB 생성 단계 추가, 환경변수 계약 테스트 추가(코드가 읽는 변수가 compose·.env.example·CI에 없으면 실패)
- 문서: 개발 기준 10.1(운영 DB 계정과 환경변수 이름 확정), 배포 가이드 8절, 모델 계약 5.2, README, PRD B/D 최신화
확인한 것
- 로컬 테스트 36개 통과, ruff 통과, check --deploy는 HSTS 경고(W004) 하나만(기본값 0으로 의도적, 운영 전 설정)
- 임시 PostgreSQL에서 migrate 계정은 migration 가능, app 계정은 SELECT/INSERT 가능·CREATE/DROP 불가·개인정보 DB 접속 불가 확인
- /health/ 200, HTTP의 다른 경로는 301, X-Forwarded-Proto: https면 200
아직 확인 못 한 것(완료 기준 미충족)
- 실제 docker build / compose up (healthy 확인)은 Docker Desktop이 있는 PC에서 해야 함
- CI의 PII DB 생성 단계는 GitHub Actions에서 아직 실행되지 않음
- PostgreSQL 이미지 태그를 18.x 정확한 버전으로 고정하는 일
리뷰 요청 사항
- config/urls.py 한 줄(/health/), .env.example, requirements.txt(gunicorn), 개발 기준·모델 계약·README 수정은 우섭 리뷰 필요
- 02-02(예주)와 04-03(성용) 범위를 PRD B·D에서 정리함(settings의 pii 연결·라우터는 02-02, compose·DB 계정·CI 준비는 04-03). 예주 확인 필요
서버 배포는 04-01(VPS·DNS)과 승인 결정 이후라 이번 범위에 포함하지 않음.
성양 Updated by 성용 양 8 days ago
- % Done changed from 50 to 70
[진행 기록 2026-11-09] PR #12 머지 완료 (main 반영)
- PR: https://github.com/GilbertMoon/university-academic-system/pull/12 (스쿼시 머지)
- GitHub Actions CI 통과(신규 "PII DB 생성" 단계 포함), GitGuardian 비밀값 검출 없음
- 진척도 70%: 구현·문서·CI 반영 완료. 남은 것은 완료 기준 확인뿐
남은 일
- Docker Desktop이 있는 PC에서 docker build / compose up → db·web healthy, check --deploy, 포트 노출 없음(5432 미게시, 8000은 127.0.0.1만) 확인 결과를 이 일감에 기록
- postgres 이미지 태그를 검증한 18.x로 고정
- 02-02(#1254, 예주): settings의 pii 연결·모델 라우터만 구현하면 됨(compose·DB 계정·CI 준비는 이 PR에서 완료, 공통 개발 기준 10.1절)
- 서버 반영은 04-01(VPS·DNS)과 비용·DNS 권한 승인 이후
참고: 리뷰어(우섭) 사전 리뷰 없이 머지했으므로 config/urls.py(/health/ 한 줄), requirements.txt(gunicorn), 개발 기준·모델 계약·README 수정 내용을 사후 확인 요청함.
성양 Updated by 성용 양 8 days ago
2026-11-09 진행 기록: PR #16 머지 (웹 포트 변수화)
[한 일]
- GitHub PR #16 스쿼시 머지(main deb2a48): compose.prod.yml web 게시 포트를 127.0.0.1:${WEB_PORT:-8000}:8000으로 변경. 같은 서버·고정 IP에 동백 쉴만한 교회 사이트(127.0.0.1:8000)가 함께 올라가고 호스트 Nginx가 Host 헤더로 구분한다는 총괄자 전달 사항 반영. .env.example 운영 블록, Nginx 예시(proxy_pass 포트 맞춤, default_server 미사용), deploy/README, 배포 가이드 8.4 갱신.
- DB 구성: 교회와 같은 방식으로 학사관리 전용 PostgreSQL 18 컨테이너를 따로 둔다(A안, 기존 구성 유지).
[확인한 것]
- CI 통과. docker compose config: 기본값 127.0.0.1:8000, WEB_PORT=8001이면 127.0.0.1:8001.
- 04-05 복원 훈련 중 compose.prod.yml의 db 서비스 실제 기동: postgres:18-bookworm(18.6) healthy, 5432는 호스트에 게시되지 않음, 학사·개인정보 DB와 app·migrate 계정 생성 및 app 계정의 개인정보 DB 접속 거부 확인.
[못 확인한 것]
- web 이미지 docker build·compose up 전체, check --deploy(아직 미실행).
[남은 일]
- 서버 정보 수령 후 실제 WEB_PORT·도메인을 서버 .env.production과 Nginx에 반영.
- web 이미지 빌드·기동 검증, postgres 이미지를 검증한 18.x 태그로 고정.
- 배포 가이드 1절 4항(별도 서버 권장)을 같은 서버 사용 결정에 맞게 수정(우섭 리뷰).
성양 Updated by 성용 양 7 days ago
- Description updated (diff)
- Status changed from In Progress to Resolved
- % Done changed from 70 to 100
[성용] 완료 기록 (2026-11-11)
- 운영은
compose.cloudsql.yml(PR #22)로 배포. 00-01(#1243) 결정에 따라 DB 컨테이너 대신 Cloud SQL 학사 DB·개인정보 DB에 SSL로 연결. - 웹 컨테이너에는 웹 계정만 전달하고, migration 계정은 일회성 migrate 작업에만 전달.
- 확인: 컨테이너 healthy, Gunicorn 정상 기동, 내부·외부 /health/ 200, 정적 파일 수집 128개, DB 포트 외부 비노출, 로그인 화면 200, 비로그인 /admin/ 302.
- 배포 SHA: d419824 (main). 이후 main 변경(73ee9b7까지)은 문서뿐이라 재배포하지 않음.
- 이전 기록의 "postgres 이미지 태그 고정"은 운영이 Cloud SQL을 쓰므로 운영 범위에서 제외(로컬·CI는 PostgreSQL 18 유지).
성양 Updated by 성용 양 6 days ago
[성용] 변경 기록 (2026-11-11)
- PR #33 병합(https://github.com/GilbertMoon/university-academic-system/pull/33): deploy/README의 개인정보 DB(pii) 연결 안내를 현재 구현 상태(PR #22)로 정정
- PR #34 병합(https://github.com/GilbertMoon/university-academic-system/pull/34): 로컬 훈련용 compose.prod.yml의 PostgreSQL 이미지를
postgres:18.6-bookworm으로 고정(운영 compose.cloudsql.yml·Cloud SQL 변경 없음) - 남아 있던 "PostgreSQL 이미지 세부 버전 고정" 항목 완료. 운영 check --deploy 경고 W004(HSTS)·W009는 유지 중