1편 — Django는 대체 뭘 대신 해주나

😵 Cursor에 "Django로 게시판 만들어줘"라고 했더니 폴더와 파일이 우수수 생겼습니다. 열어보면 이런 생각이 듭니다.

"나는 settings.py를 건드린 적도 없는데 서버는 어떻게 뜨지?"

오늘 풀 질문은 이것 하나입니다. settings.py를 한 줄도 안 건드렸는데 서버가 뜨는 이유는 무엇일까요? 끝에서 답을 정리해 드리겠습니다.

🎬 지난 이야기: 0편에서는 AI가 만든 Django 코드를 눈높이에 맞춰 통역해 드리겠다고 약속했습니다. 오늘은 그 첫 번째 코드 더미를 열어봅니다.

🤖 AI가 짜준 코드

프롬프트:

"Django 프로젝트 시작하는 명령어랑 결과 폴더 구조 알려줘"

django-admin startproject config .
python manage.py startapp community

실행하면 이런 파일이 생깁니다.

my_project/
├── manage.py
├── config/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
└── community/
    ├── __init__.py
    ├── admin.py
    ├── apps.py
    ├── models.py
    ├── views.py
    ├── tests.py
    └── migrations/
        └── __init__.py

명령어 두 줄을 쳤을 뿐인데 파일이 열 몇 개 생겼습니다. 이어서 서버를 켜 보겠습니다.

python manage.py runserver

터미널에는 아래와 같은 줄이 나옵니다. 앞부분의 경고 줄은 생략했습니다.

Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

처음 실행하면 unapplied migration(s) 경고가 함께 보일 수 있습니다. 지금은 무시해도 되고 6편에서 다룹니다.

브라우저에서 이 주소를 열면 로켓 그림과 "The install worked successfully! Congratulations!" 문구가 있는 기본 환영 화면이 보입니다(색과 디자인은 버전마다 다를 수 있습니다). 우리가 화면을 만든 적은 없는데도요.

비밀은 startproject가 만들어 준 config/settings.py에 있습니다. 열어 보면 처음부터 이런 내용이 채워져 있습니다(일반 Django 기본값 중 일부입니다).

# config/settings.py (startproject 기본값 중 일부)
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

🔍 한 줄씩 통역

서버가 뜨는 과정: manage.py → settings → runserver

먼저 startproject가 manage.py에 심어 둔 줄을 보겠습니다. 열어 보면 main() 함수 안에 이런 줄이 있습니다.

# manage.py
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')

이 줄이 settings를 찾는 경로입니다. 풀어서 읽으면 이렇습니다.

• DJANGO_SETTINGS_MODULE은 "Django 설정 파일이 어디 있나요?"에 대한 답을 적어 두는 환경 변수 이름입니다.
• 'config.settings'는 "config 폴더 안의 settings.py"라는 파이썬식 주소입니다. 폴더 이름을 config로 지었기 때문에 이 이름이 들어갔습니다.
• setdefault는 "이미 지정된 값이 없을 때만 이 값을 쓴다"는 뜻입니다.

즉 manage.py는 Django에게 "설정은 config/settings.py에 있다"고 알려 주는 주소 메모를 들고 있는 파일입니다. 그래서 직접 편집할 일이 거의 없습니다.

이제 python manage.py runserver를 쳤을 때 일어나는 일을 순서대로 따라가 봅니다.

1. manage.py가 실행되면서 위의 setdefault 줄이 환경 변수를 config.settings로 맞춥니다.
2. manage.py가 Django의 명령 실행 기능에 runserver라는 명령을 넘깁니다.
3. Django가 config.settings를 import합니다. 이 순간 settings.py의 내용이 파이썬 값으로 메모리에 올라옵니다.
4. Django가 INSTALLED_APPS를 위에서부터 한 줄씩 로딩합니다. admin, auth, contenttypes, sessions, messages, staticfiles 순서로 각 앱을 준비합니다.
5. MIDDLEWARE 목록으로 요청 처리 줄을 세우고, urls.py를 연결합니다.
6. 8000번 포트에서 요청을 기다립니다. 아직 우리가 만든 주소가 하나도 없고 DEBUG가 켜져 있으면 Django가 기본 환영 화면을 보여 줍니다.

settings.py를 직접 고치지 않아도 되는 이유가 여기서 보입니다. startproject가 값이 채워진 파일을 만들었고, manage.py의 한 줄이 그 파일을 가리키고, runserver가 그 파일을 import해서 읽기 때문입니다.

INSTALLED_APPS: 건물 입주 명단

위 기본 6줄은 Django가 기본으로 들고 온 부품입니다. 각각 이런 일을 해 줍니다.

• admin: /admin/에서 데이터를 보고 고치는 관리자 페이지를 제공합니다.
• auth: 회원, 비밀번호, 권한 모델을 제공합니다.
• contenttypes: 모델의 종류를 기록해 두어 권한 같은 기능이 "어떤 모델에 대한 것인지" 가리킬 수 있게 합니다.
• sessions: 로그인 상태 같은 방문자 정보를 서버에 기억합니다.
• messages: "저장되었습니다" 같은 일회성 알림을 화면에 전달합니다.
• staticfiles: CSS, 이미지 같은 정적 파일을 찾아 제공합니다.

내가 만든 앱(community)도 이 명단에 이름을 올려야 Django가 프로젝트의 일부로 인식합니다. 아래 "자주 깨지는 지점"에서 이 실수를 다룹니다.

MIDDLEWARE: 건물 입구 보안 검색대

요청이 들어오면 화면을 만드는 코드에 닿기 전에 이 목록을 위에서부터 차례로 통과합니다.

1. SecurityMiddleware: 기본 보안 설정 적용
2. SessionMiddleware: "이 방문자가 누구였더라?"를 쿠키로 확인해 세션을 꺼내 둠
3. CommonMiddleware, CsrfViewMiddleware: 주소 정리와 위조 요청 방어 같은 공통 검사
4. AuthenticationMiddleware: 세션을 바탕으로 로그인한 사용자를 찾아 둠

그래서 세션과 로그인 사용자를 꺼내는 코드를 직접 쓰지 않았는데도, 뷰에서 request.session과 request.user를 바로 쓸 수 있습니다.

• request.session: SessionMiddleware가 채웁니다.
• request.user: AuthenticationMiddleware가 채웁니다(8편).

📌 AI 프로젝트를 받으면 이 순서로 열어 보세요: settings.py → urls.py(2편) → models.py(5편). wsgi.py, asgi.py, __init__.py, tests.py는 지금은 "있구나" 정도면 충분합니다.

🎁 보너스: 실전에서는 목록이 늘어납니다

AI가 만든 프로젝트나 실제 서비스에서는 기본 6줄 아래에 외부 패키지가 더 붙습니다. 가장 흔히 만나는 것이 allauth입니다. 이메일 가입, 소셜 로그인처럼 Django 기본 auth에 없는 회원 기능을 추가하려고 등록합니다. 이 회차 예제에서는 config/settings.py에 community 앱만 추가해 쓰면 됩니다.

약속했던 질문의 답

settings.py를 건드린 적이 없어도 서버가 뜨는 이유는, startproject가 이미 동작하는 settings.py를 만들어 주고, manage.py의 DJANGO_SETTINGS_MODULE 줄이 그 파일을 가리키며, runserver가 그 파일을 import해 앱과 미들웨어를 로딩하기 때문입니다. 그래서 우리가 짜야 하는 부분은 이렇게 좁아집니다.

⚠️ 자주 깨지는 지점

1. 앱을 만들고 등록하지 않았을 때

startapp만 하고 INSTALLED_APPS에 넣지 않으면 Django는 그 앱이 프로젝트의 일부인지 모릅니다. 그래서 모델을 작성하고 makemigrations를 해도 앱을 건너뜁니다.

No changes detected

또 그 모델을 임포트하는 순간 이런 에러가 납니다.

RuntimeError: Model class community.models.Post doesn't declare an explicit app_label and isn't in an application in INSTALLED_APPS.

(참고로 no such table: community_post 같은 OperationalError는 앱은 등록했는데 마이그레이션을 만들지 않았거나 적용하지 않은 채 쿼리할 때 나오는 별개의 증상입니다.)

해결 순서:
1. INSTALLED_APPS에 'community.apps.CommunityConfig'(또는 'community')를 추가합니다.
2. python manage.py makemigrations community
3. python manage.py migrate

(마이그레이션은 6편에서 자세히 다룹니다.)

2. 끝의 점(.)을 빼먹었을 때

django-admin startproject config처럼 점이 없으면 바깥에 config/ 프로젝트 폴더가 하나 더 생기고, 그 안에 manage.py와 안쪽 config/ 패키지가 들어가 config/config/ 중첩 구조가 됩니다. 이때 manage.py가 없는 바깥 위치에서 python manage.py runserver를 치면 이런 에러가 납니다.

python: can't open file '.../manage.py': [Errno 2] No such file or directory

manage.py는 바깥 config/ 폴더 안에 있으니, cd config로 들어간 뒤 실행하세요. 또는 처음부터 점을 붙여 다시 만들어도 됩니다.

🎮 직접 해보기

내 프로젝트 기준으로 따라 하세요. 설정 파일은 config/settings.py입니다(테크창 사이트는 config/settings/base.py라서 경로가 다릅니다).

1. python manage.py runserver로 기본 환영 화면(로켓 그림)을 먼저 띄워 봅니다.
2. manage.py를 열어 DJANGO_SETTINGS_MODULE 줄을 찾고, config/settings.py의 INSTALLED_APPS 기본 6줄과 MIDDLEWARE의 SessionMiddleware, AuthenticationMiddleware도 찾아 봅니다.
3. 서버를 켠 채로 INSTALLED_APPS에서 'django.contrib.staticfiles', 줄 앞에 #을 붙여 저장합니다. 파일이 바뀌면 서버가 자동으로 다시 시작되니 터미널을 지켜보세요.
4. 기대 결과: 서버는 에러 없이 다시 뜨고, 환영 화면도 그대로 보입니다. 다만 브라우저에서 /admin/에 들어가면 CSS가 빠진 밋밋한 로그인 화면이 보이고, 터미널에는 /static/admin/... 같은 주소의 404 줄이 찍힐 수 있습니다. 개발 서버의 정적 파일 제공은 staticfiles 앱이 맡기 때문입니다. 버전에 따라 다를 수 있으니 실제로 보이는 모습을 그대로 메모하세요.
5. #을 지워 원래대로 돌려놓고 /admin/ 화면의 디자인이 돌아오는지 확인합니다.

막히면 테크창 커뮤니티에 스크린샷과 함께 질문해 주세요.

⏭️ 다음 편 예고

브라우저에 /posts/를 쳤을 때 Django는 수많은 파일 중 어디로 안내할까요? 2편에서 urls.py의 한 줄을 해부합니다.

📚 시리즈: AI가 짜준 Django, 이제 알고 씁니다 · 1편 (0~9편, 총 10회)
테크창 연구팀
본 칼럼은 AI 보조로 작성되었으며, 코드·예시는 학습용입니다.