deploy-django

---
name: deploy-django
description: >-
license: MIT
---

# deploy-django

theDetect·theCMS·theMovie·theHome·theListening 5개 골든 레퍼런스
프로젝트를 직접 대조해 추출한, ganzskang 환경에서 Django를 배포하는
표준 절차다. 이 문서에 없는 컨벤션을 지어내지 말 것 — 실제 프로젝트의
기존 관례와 이 스킬이 다르면, 이미 배포되어 동작 중인 그 프로젝트의
관례를 이 스킬의 원칙보다 우선한다 (특히 재배포 작업일 때).

조사 원본과 5개 프로젝트 간 불일치를 어떻게 표준으로 정리했는지는
`doc/2026-08-17-common-pattern-analysis.md`에 전체 비교표와 근거가 있다.

## 이 스킬이 다루는 것 / 안 다루는 것

다룬다: Django 프로젝트 골격(디렉토리 구조, settings 3분리, 환경변수
관리), gunicorn + systemd 프로세스 관리, nginx 리버스 프록시, Cloudflare
Tunnel(`www`, 원격관리) 등록, 정적/미디어 파일 배치, 코드 변경 후
재배포 절차.

다루지 않는다: 애플리케이션 로직 자체, 프로젝트 고유 기능 앱 설계,
Django를 안 쓰는 서비스(theAddress 등 Spring Boot), Celery/Channels
같은 프로젝트별 선택 모듈의 자세한 튜닝(뼈대만 optional-addons.md에
제공).

## 이 환경의 하드 제약 — 항상 전제

- **이 에이전트는 passwordless sudo가 없다.** `systemctl`, `nginx -t`
  이후의 `reload`, `/etc/` 아래 파일 생성/수정, `cloudflared tunnel`
  관리 등 sudo가 필요한 모든 명령은 사용자에게 정확한 명령을 그대로
  전달하고, 사용자가 실행한 결과(출력)를 받아서 검증하는 방식으로
  진행한다. 대신 실행해줄 수 있다고 가정하지 않는다.
- **Cloudflare Zero Trust 대시보드도 이 에이전트가 직접 조작할 수
  없다.** Public Hostname 추가/삭제는 항상 사용자가 브라우저에서 하고,
  이 스킬은 입력할 값의 표를 제공하고 `journalctl`/`curl`/`dig`로
  결과를 검증하는 역할만 한다.
- DB, 소켓/로그 경로, nginx 파일명, 이 문서에 나오는 모든 값은 5개
  프로젝트 실측 + 사용자 확정을 거친 것이다. 프로젝트마다 다를 수밖에
  없는 값(서비스명, 포트, 서브도메인 등)은 `{{service_key}}` 같은
  템플릿 변수로 표시되어 있으니, 실제 값을 채울 때 반드시 사용자에게
  확인한다 — 임의로 짓지 않는다.

## 초기 셋업 순서

새 Django 프로젝트를 처음 퍼블릭 서비스로 세팅할 때는 아래 순서를
따르고, 각 단계 사이(특히 sudo가 필요한 설치/재시작 직전)에 결과를
요약해 사용자 확인을 받는다:

| 단계 | 하는 일 | 참고 |
|---|---|---|
| 1. 프로젝트 골격 | 디렉토리 구조, settings 앱 이름(`project`), docs/, AGENTS.md 생성 | [project-scaffold.md](references/project-scaffold.md) |
| 2. 환경변수/settings | `settings.py`+`settings_dev.py`+`settings_prod.py` 3분리, env 헬퍼, `.env.example` | [env-and-settings.md](references/env-and-settings.md) |
| 3. 정적/미디어 배치 | `staticfiles/`, `media/` repo 안 생성 + `/var/www/{{service_key}}/` 심볼릭 링크 (sudo) | [static-media.md](references/static-media.md) |
| 4. gunicorn + systemd | gunicorn config/service 작성, `/logs/{{service_key}}/` 생성, 유닛 설치·기동 (sudo) | [gunicorn-and-systemd.md](references/gunicorn-and-systemd.md) |
| 5. nginx | site 파일 작성·설치, `nginx -t`, reload (sudo) | [nginx-vhost.md](references/nginx-vhost.md) |
| 6. Cloudflare Tunnel | `www` 터널에 Public Hostname 등록 (사용자가 대시보드에서 직접), 검증 | [cloudflare-tunnel-www.md](references/cloudflare-tunnel-www.md) |
| 7. (필요시) 부가 모듈 | Celery/Redis, Channels/daphne — 요구사항이 명확할 때만 | [optional-addons.md](references/optional-addons.md) |

## 재배포(지속 배포) 순서

이미 세팅된 프로젝트에 코드 변경을 반영할 때는 위 단계를 반복하지
않고 → [redeploy-checklist.md](references/redeploy-checklist.md)를
바로 따른다 (git pull → 필요시 마이그레이션/정적파일 → 서비스 재시작 →
검증 → 문제 시 롤백).

## references/ 인덱스

| 파일 | 언제 읽는가 |
|---|---|
| [project-scaffold.md](references/project-scaffold.md) | 신규 프로젝트 디렉토리/앱 구조를 처음 잡을 때 |
| [env-and-settings.md](references/env-and-settings.md) | SECRET_KEY/DEBUG/ALLOWED_HOSTS 등을 관리하는 방식을 정할 때, settings 3분리 구조를 만들 때 |
| [static-media.md](references/static-media.md) | STATIC_ROOT/MEDIA_ROOT를 어디에 둘지, `/var/www/`와 어떻게 연결할지 정할 때 |
| [gunicorn-and-systemd.md](references/gunicorn-and-systemd.md) | gunicorn 소켓/서비스 유닛을 만들거나, gunicorn 프로세스/로그를 진단할 때 |
| [nginx-vhost.md](references/nginx-vhost.md) | nginx site 파일을 만들거나, 라우팅/404/502를 진단할 때 |
| [cloudflare-tunnel-www.md](references/cloudflare-tunnel-www.md) | `www` 터널에 새 호스트명을 등록하거나, "Server Not Found"/DNS 오류를 진단할 때 |
| [redeploy-checklist.md](references/redeploy-checklist.md) | 이미 배포된 프로젝트에 코드 변경을 반영할 때 |
| [optional-addons.md](references/optional-addons.md) | 백그라운드 작업(Celery)이나 WebSocket(Channels)이 실제로 필요해졌을 때 |

## 자주 하는 실수

- **Cloudflare Tunnel에 같은 호스트명 항목을 중복으로 남겨둠.** ingress
  규칙은 first-match-wins라, 새 항목을 추가하기 전에 항상 기존 항목
  존재 여부를 먼저 확인해야 한다 — 확인 없이 추가했다가 오래된 죽은
  규칙이 먼저 매치돼 실제 장애로 이어진 사례가 있었다 (자세한 내용
  cloudflare-tunnel-www.md 0번 항목).
- **"Server Not Found"를 전부 같은 원인으로 취급.** nginx ingress
  라우팅 문제(로컬 curl로 origin은 확인되지만 퍼블릭은 실패)와 DNS
  레코드 자체가 없는 문제(모든 리졸버에서 빈 응답)는 진단·해결 방법이
  다르다 — 반드시 `dig`로 구분한다.
- **sudo가 필요한 명령을 대신 실행하려고 시도.** 이 환경엔
  passwordless sudo가 없다. 명령을 사용자에게 전달하고 결과를
  받는 방식으로만 진행한다.
- **프로젝트마다 다를 수밖에 없는 값(서비스명, 포트, 서브도메인,
  기능 앱 구성)을 임의로 다른 프로젝트 것과 똑같이 맞춤.** 템플릿
  변수는 항상 사용자에게 확인 후 채운다.
- **theCMS의 `deploy/` 아래 있는 정교한 blue-green/Postgres/Garage
  구성을 "표준"으로 착각.** 실제로 지금 운영 중인 건 그 정교한
  시스템이 아니라 다른 4개와 같은 단순한 구성이다 (조사 문서 참고).
  Celery만은 실제로 살아있는 예외.
- **코드를 재배포하면서 `git reset --hard`, DB 파일 교체 같은 되돌릴
  수 없는 작업을 사용자 승인 없이 실행.** redeploy-checklist.md의
  롤백 절차도 항상 승인을 먼저 받는다.