생성한 프로젝트와 실행하는 경로를 일치시키기

처음 Django 프로젝트를 만들 때 저는 PyCharm의 생성 기능을 사용했습니다. 하지만 IDE가 파일을 만들어 주는 것과 Docker 안에서 그 프로젝트가 실행되는 것은 별개였습니다. 이전 글에서 config, src.config, myproject 같은 이름과 manage.py 위치를 혼용한 부분을 현재 win-j 구조에 맞춰 다시 정리합니다.

이 글은 기존 프로젝트에 startproject를 다시 실행하라는 안내가 아닙니다. 설치된 IDE의 메뉴보다 실제 파일 위치, Python import 경로, 실행 작업 폴더를 확인하는 데 초점을 둡니다. PyCharm 제품별 지원 기능은 바뀔 수 있으므로 과거 Professional·Community 비교표를 현재 설치 기준으로 사용하지 않습니다.

현재 프로젝트의 기준 경로

프로젝트 루트/
├── docker/dev/docker-compose.dev.yml
├── docker/prod/docker-compose.prod.yml
├── docker/prod/nginx.conf
└── src/
    ├── manage.py
    ├── myproject/settings.py
    ├── myproject/urls.py
    ├── myproject/wsgi.py
    └── blog/

manage.py는 src에 있습니다. 프로젝트 루트에서는 python src/manage.py ...를 사용합니다. 운영 Compose는 /app/src를 PYTHONPATH에 넣고, Gunicorn에 --chdir src와 myproject.wsgi:application을 지정합니다. 설정 모듈은 myproject.settings입니다. 이 조합에 예전 예제의 src.config.settings를 섞으면 실제 파일이 있어도 import 오류가 날 수 있습니다.

새 학습 프로젝트에서 django-admin startproject config src를 사용하면 manage.py도 src 안에 생깁니다. 이후 이유 없이 루트로 옮기기보다 그 구조에 맞춰 명령을 실행하는 편이 경로를 추적하기 쉽습니다. 이 설명은 win-j의 설정 모듈 이름을 config로 변경하라는 뜻이 아닙니다.

설정을 확인하는 작은 점검

실행 중인 개발 web 컨테이너에서 다음 명령을 사용할 수 있습니다. web이 꺼져 있다면 실행 오류가 나는 것이 정상이며, 이 명령만으로 서비스를 시작하지는 않습니다.

docker compose -f .\docker\dev\docker-compose.dev.yml exec web python src/manage.py check
docker compose -f .\docker\dev\docker-compose.dev.yml exec web python src/manage.py shell -c "from django.conf import settings; print(settings.ROOT_URLCONF); print(settings.WSGI_APPLICATION); print(settings.STATIC_ROOT)"

현재 기본 경로는 각각 myproject.urls, myproject.wsgi.application, /app/staticfiles입니다. 마지막 값은 환경 변수로 바꿀 수 있어 실제 출력과 비교해야 합니다. SECRETKEY나 DATABASEURL을 출력해서 경로를 확인할 필요는 없습니다.

일반 check 통과는 배포 보안이나 실제 페이지 정상의 보장이 아닙니다. 운영 설정에서는 DEBUG=False, 허용 호스트, CSRF 신뢰 출처, HTTPS 전달과 쿠키 설정을 Django 배포 점검표에 맞춰 따로 확인합니다.

CSS 파일을 찾는 세 단계

단계 이 프로젝트의 운영 기준 실패할 때 볼 항목
원본 탐색 앱 static과 STATICFILES_DIRS 파일명·경로·중복 파일
수집 web의 /app/staticfiles 기본값 collectstatic 로그·쓰기 권한
제공 nginx의 /var/www/static/ 공유 volume·alias·요청 URL

collectstatic은 파일을 수집하는 변경 명령입니다. 현재 운영 web 시작 과정에 포함되어 있으므로 CSS가 안 보인다는 이유만으로 무조건 다시 실행하기보다 해당 단계의 성공 여부부터 확인합니다. 특정 원본을 찾는 데는 findstatic admin/css/base.css --verbosity 2처럼 Django의 파일 탐색 명령을 사용할 수 있습니다.

브라우저가 /static/admin/css/base.css를 요청했다면 Nginx는 alias 아래의 admin/css/base.css를 찾습니다. HTML은 정상인데 CSS만 404라면 이 연결을 점검합니다. 200인데 이전 CSS라면 응답 본문과 캐시를 확인합니다. 현재 Nginx는 static에 긴 캐시와 immutable을 선언하므로 같은 URL에 내용을 덮어쓰는 방식에서는 캐시 영향도 구분해야 합니다. 자세한 수집 절차는 Django static 배포 문서를 참고합니다.

HTTPS와 오류를 구분해서 보기

저장소 설정의 SECURE_PROXY_SSL_HEADER는 X-Forwarded-Proto: https를 신뢰하도록 되어 있습니다. 반면 내부 Nginx는 HTTP를 수신하고 프록시 헤더에 자기 $scheme을 넣습니다. NAS 앞단의 실제 전달 설정은 별도 확인 대상이므로 저장소만 보고 HTTPS 판정이 정상이라고 단정할 수 없습니다. 로그인이나 CSRF 오류가 있을 때 외부 HTTPS와 Django가 인식하는 scheme을 함께 대조해야 하는 이유입니다.

DisallowedHost는 허용 호스트, ModuleNotFoundError는 모듈 경로, CSS 404는 파일 제공 경로를 우선 확인합니다. 각각 다른 실패 지점이므로 한 번에 모든 설정을 바꾸면 원인을 찾기 어려워집니다. DB 연결까지 이어서 확인하려면 PostgreSQL 연결과 조회 점검을 참고하세요.