4편 Django 프로젝트 생성부터 Production 설정까지｜PyCharm + Static 파일 처리

이전 글에서는 Docker Compose를 이용해 Django + Nginx + PostgreSQL 환경을 구성하는 흐름을 정리했습니다.

이번 글에서는 실제 Django 프로젝트를 생성하고, 운영 환경에서 필요한 Production 설정과 Static 파일 처리까지 이어서 정리해보겠습니다.

---

PyCharm으로 Django 프로젝트를 생성하는 이유

Django 프로젝트는 명령어만으로도 충분히 생성할 수 있습니다. 하지만 처음 프로젝트를 구성할 때는 폴더 구조, 설정 파일, 실행 환경을 함께 확인해야 하기 때문에 IDE를 사용하면 훨씬 편합니다.

저는 PyCharm Professional 버전을 사용하고 있습니다. PyCharm Professional은 Django 프로젝트 생성 기능과 Django 관련 설정 지원을 제공하기 때문에 처음 프로젝트를 만들 때 기본 구조를 자동으로 생성할 수 있습니다.

---

PyCharm Professional과 Community 차이

구분	PyCharm Professional	PyCharm Community
Django 프로젝트 생성	IDE에서 Django 프로젝트 생성 기능 지원	명령어로 직접 생성
Django 설정 인식	settings.py, manage.py 등 Django 구조 지원	일반 Python 프로젝트로 사용
템플릿 지원	Django 템플릿 작업에 유리	기본 편집은 가능하지만 전용 지원은 제한적
DB 도구	내장 Database 도구 사용 가능	별도 DB 클라이언트 사용 권장
추천 대상	Django를 자주 사용하거나 실서비스 개발을 하는 경우	무료로 Python/Django를 학습하거나 가볍게 시작하는 경우

다만 Community 버전이라고 해서 Django 개발을 못 하는 것은 아닙니다. Django 프로젝트 생성 명령어를 직접 실행하면 동일한 프로젝트 구조를 만들 수 있습니다.

---

이번 글에서 사용할 프로젝트 구조

이번 예시는 Docker 환경에서 운영까지 고려한 구조로 잡겠습니다.

project/
├── docker/
│   └── dev/
│       └── docker-compose.yml
│
├── src/
│   ├── config/
│   │   ├── __init__.py
│   │   ├── settings.py
│   │   ├── urls.py
│   │   ├── wsgi.py
│   │   └── asgi.py
│   │
│   └── blog/
│       ├── __init__.py
│       ├── admin.py
│       ├── apps.py
│       ├── models.py
│       ├── views.py
│       └── urls.py
│
├── manage.py
├── requirements.txt
└── gunicorn.conf.py

---

PyCharm Professional에서 Django 프로젝트 생성하기

PyCharm Professional을 사용한다면 새 프로젝트 생성 화면에서 Django 프로젝트를 선택할 수 있습니다.

생성 순서

1. PyCharm 실행
2. New Project 선택
3. Django 프로젝트 선택
4. 프로젝트 위치 지정
5. Python 인터프리터 선택
6. Application name 입력
7. Create 클릭

이렇게 생성하면 PyCharm이 Django 기본 프로젝트 구조를 자동으로 만들어줍니다.

이 방식은 초기에 Django 구조를 잡기 편하고, IDE에서 프로젝트를 바로 인식하기 때문에 처음 설정 시간을 줄일 수 있습니다.

---

PyCharm Community에서 Django 프로젝트 생성하기

PyCharm Community 버전은 Django 프로젝트 생성 기능이 따로 제공되지 않기 때문에 일반 Python 프로젝트를 만든 뒤 터미널에서 Django 명령어를 실행하면 됩니다.

1단계. 폴더 생성

mkdir project
cd project

mkdir -p docker/dev
mkdir src

2단계. 가상환경 생성

python -m venv .venv

윈도우에서는 아래 명령어로 가상환경을 활성화합니다.

.venv\Scripts\activate

리눅스 또는 macOS에서는 아래 명령어를 사용합니다.

source .venv/bin/activate

3단계. Django 설치

pip install django

4단계. Django 프로젝트 생성

현재 폴더에 manage.py를 만들고, 설정 폴더는 src/config 안에 생성하겠습니다.

django-admin startproject config src

이 명령어를 실행하면 src 폴더 안에 config 폴더와 manage.py가 생성됩니다. 다만 위에서 원하는 구조처럼 manage.py를 프로젝트 루트에 두고 싶다면 다음처럼 파일 위치를 정리할 수 있습니다.

move src\manage.py manage.py

리눅스 또는 macOS에서는 아래 명령어를 사용합니다.

mv src/manage.py manage.py

5단계. 앱 생성

python manage.py startapp blog src/blog

만약 위 명령어에서 폴더 관련 오류가 발생한다면 먼저 앱 폴더를 생성한 뒤 실행합니다.

mkdir src\blog
python manage.py startapp blog src/blog

리눅스 또는 macOS에서는 아래처럼 작성할 수 있습니다.

mkdir -p src/blog
python manage.py startapp blog src/blog

---

manage.py 설정 확인

manage.py는 Django 명령어를 실행하는 진입점입니다. runserver, migrate, createsuperuser 같은 명령어를 실행할 때 사용합니다.

#!/usr/bin/env python
import os
import sys


def main():
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "src.config.settings")
    from django.core.management import execute_from_command_line
    execute_from_command_line(sys.argv)


if __name__ == "__main__":
    main()

---

settings.py 역할과 기본 설정

settings.py는 Django 프로젝트의 전체 설정 파일입니다. 설치된 앱, 데이터베이스, static 경로, 보안 설정 등을 관리합니다.

from pathlib import Path
import os

BASE_DIR = Path(__file__).resolve().parent.parent.parent

SECRET_KEY = "dev-secret-key"

DEBUG = True

ALLOWED_HOSTS = []

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",

    "src.blog",
]

ROOT_URLCONF = "src.config.urls"

WSGI_APPLICATION = "src.config.wsgi.application"
ASGI_APPLICATION = "src.config.asgi.application"

STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

---

urls.py 역할

urls.py는 사용자가 접속한 URL을 어떤 view로 보낼지 결정하는 파일입니다.

src/config/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("src.blog.urls")),
]

src/blog/urls.py

from django.urls import path
from . import views

app_name = "blog"

urlpatterns = [
    path("", views.index, name="index"),
]

---

views.py 역할

views.py는 실제 요청을 처리하고 응답을 반환하는 파일입니다. 가장 간단한 예시로 문자열을 반환하는 화면을 만들 수 있습니다.

from django.http import HttpResponse


def index(request):
    return HttpResponse("Django 프로젝트 생성 완료")

나중에는 이 views.py에서 HTML 템플릿을 렌더링하거나, 게시글 목록, 상세 페이지, 유틸리티 기능 등을 처리하게 됩니다.

---

admin.py 역할

admin.py는 Django 관리자 페이지에 모델을 등록하는 파일입니다. 예를 들어 게시글 모델을 만들었다면 admin.py에 등록해야 관리자 페이지에서 관리할 수 있습니다.

from django.contrib import admin

# Register your models here.

---

wsgi.py 역할

wsgi.py는 Gunicorn 같은 WSGI 서버가 Django 프로젝트를 실행할 때 사용하는 진입점입니다. 일반적인 운영 배포에서는 Gunicorn이 이 파일을 바라봅니다.

import os

from django.core.wsgi import get_wsgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "src.config.settings")

application = get_wsgi_application()

---

asgi.py 역할

asgi.py는 비동기 서버 환경에서 사용하는 진입점입니다. WebSocket, 실시간 채팅, 비동기 처리 기능을 사용할 때 ASGI 구성이 필요할 수 있습니다.

import os

from django.core.asgi import get_asgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "src.config.settings")

application = get_asgi_application()

일반적인 게시판, 블로그, 유틸리티 사이트는 처음부터 ASGI를 깊게 다루지 않아도 됩니다. 다만 Django 프로젝트 생성 시 기본으로 생성되는 파일이기 때문에 역할만 알아두면 됩니다.

---

__init__.py 역할

__init__.py 파일은 해당 폴더를 Python 패키지로 인식하게 만드는 파일입니다. 파일 내용이 비어 있어도 정상입니다.

# 빈 파일이어도 정상입니다.

---

requirements.txt 작성

requirements.txt는 프로젝트에서 사용할 Python 패키지 목록입니다. Docker 이미지 빌드 시 이 파일을 기준으로 패키지를 설치합니다.

Django
gunicorn
psycopg2-binary

PostgreSQL을 사용할 예정이라면 psycopg2-binary가 필요합니다. 운영 환경에서는 버전을 고정해두는 것이 좋습니다.

Django==5.2.5
gunicorn==23.0.0
psycopg2-binary==2.9.10

---

gunicorn.conf.py 작성

gunicorn.conf.py는 Gunicorn 실행 옵션을 파일로 관리하기 위한 설정입니다.

bind = "0.0.0.0:8000"
workers = 3
timeout = 120

---

Production 설정으로 바꾸기

개발 단계에서는 DEBUG=True로 사용하지만, 실제 운영 서버에서는 반드시 DEBUG=False로 변경해야 합니다.

DEBUG = False

ALLOWED_HOSTS = [
    "win-j.com",
    "www.win-j.com",
]

---

Static 파일 설정

Django에서 CSS, JavaScript, 이미지 파일은 static 파일로 관리합니다. 운영 환경에서는 Django가 직접 static 파일을 제공하기보다 Nginx가 처리하는 구조가 일반적입니다.

STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

---

collectstatic 실행

운영 환경에서는 프로젝트 곳곳에 있는 static 파일을 한 곳으로 모아야 합니다. 이때 사용하는 명령어가 collectstatic입니다.

python manage.py collectstatic

Docker 환경에서는 보통 web 컨테이너 안에서 실행합니다.

docker compose -f docker/dev/docker-compose.yml exec web python manage.py collectstatic

---

Nginx에서 Static 파일 연결

Nginx 설정에서는 /static/ 요청이 들어왔을 때 Django로 넘기지 않고, static 파일 폴더에서 바로 찾아서 응답하도록 설정합니다.

location /static/ {
    alias /app/staticfiles/;
}

---

실행 흐름 정리

---

자주 발생하는 오류

• DisallowedHost 오류 : ALLOWED_HOSTS에 도메인을 추가해야 합니다.
• CSS가 적용되지 않음 : collectstatic 실행 여부와 Nginx alias 경로를 확인해야 합니다.
• ModuleNotFoundError : DJANGO_SETTINGS_MODULE 경로가 실제 폴더 구조와 맞는지 확인해야 합니다.
• admin 페이지 CSS 깨짐 : Django admin static 파일도 collectstatic으로 모아야 합니다.

---

함께 보면 좋은 글 + 추천 유틸리티

• Docker Compose 생성기
• Django + Nginx + Docker 서버 구축 전체 구조 정리
• 2편 Docker 설치 방법 총정리 (윈도우 / 리눅스 / 시놀로지 NAS)
• 3편 Django Docker Compose 배포 구성 (Nginx + PostgreSQL 완벽 가이드)

---

마무리

이번 글에서는 Django 프로젝트를 생성하는 방법부터 기본 파일 역할, 그리고 운영 환경에서 필요한 Production 설정과 Static 파일 처리까지 정리했습니다.