# Wagtail을 Django 프로젝트에 통합하기

Wagtail은 새로운 Wagtail 프로젝트를 가능한 한 빨리 시작할 수 있도록 `wagtail start` 명령과 프로젝트 템플릿을 제공하지만, 기존 Django 프로젝트에도 Wagtail을 쉽게 통합할 수 있습니다.

```{note}
스탠드얼론 Wagtail 프로젝트를 만들 계획이 없더라도 [시작하기 튜토리얼](tutorial)을 통해 학습하는 것을 강력히 권장합니다. 이렇게 하면 Wagtail 개념을 잘 이해할 수 있습니다.
```

Wagtail은 현재 Django 4.2, 5.1 및 5.2와 호환됩니다. 먼저 PyPI에서 `wagtail` 패키지를 설치합니다:

```sh
pip install wagtail
```

또는 기존 요구 사항 파일에 패키지를 추가합니다. 이렇게 하면 **Pillow** 라이브러리도 종속성으로 설치되며, libjpeg 및 zlib가 필요합니다. 자세한 내용은 Pillow의 [플랫폼별 설치 지침](https://pillow.readthedocs.io/en/stable/installation/building-from-source.html#external-libraries)을 참조하십시오.

## 설정

settings.py 파일에 다음 앱을 `INSTALLED_APPS` 에 추가합니다:

```python
'wagtail.contrib.forms',
'wagtail.contrib.redirects',
'wagtail.embeds',
'wagtail.sites',
'wagtail.users',
'wagtail.snippets',
'wagtail.documents',
'wagtail.images',
'wagtail.search',
'wagtail.admin',
'wagtail',

'modelcluster',
'taggit',
```

`MIDDLEWARE` 에 다음 항목을 추가합니다:

```python
'wagtail.contrib.redirects.middleware.RedirectMiddleware',
```

프로젝트에 아직 `STATIC_ROOT` 설정이 없는 경우 추가합니다:

```python
STATIC_ROOT = os.path.join(BASE_DIR, 'static')
```

프로젝트에 아직 `MEDIA_ROOT` 및 `MEDIA_URL` 설정이 없는 경우 추가합니다:

```python
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
MEDIA_URL = '/media/'
```

`DATA_UPLOAD_MAX_NUMBER_FIELDS` 설정을 10000 이상으로 설정합니다. 이는 폼 제출에서 허용되는 최대 필드 수를 지정하며, Wagtail의 페이지 편집기에서 특히 복잡한 페이지 모델이 이 제한을 초과할 수 있으므로 Django의 기본값인 1000에서 늘리는 것이 좋습니다:

```python
DATA_UPLOAD_MAX_NUMBER_FIELDS = 10_000
```

`WAGTAIL_SITE_NAME` 을 추가합니다. 이 이름은 Wagtail 관리 백엔드의 기본 대시보드에 표시됩니다:

```python
WAGTAIL_SITE_NAME = 'My Example Site'
```

`WAGTAILADMIN_BASE_URL` 을 추가합니다. 이는 Wagtail 관리 사이트에서 사용되는 기본 URL입니다. 일반적으로 알림 이메일에 포함할 URL을 생성하는 데 사용됩니다:

```python
WAGTAILADMIN_BASE_URL = 'http://example.com'
```

이 설정이 없으면 Wagtail은 `request.site.root_url` 또는 요청의 호스트 이름으로 대체됩니다. 이 설정은 엄격하게 필수는 아니지만, 생략하면 알림 이메일에 사용할 수 없는 URL이 생성될 수 있으므로 강력히 권장됩니다.

`WAGTAILDOCS_EXTENSIONS` 설정을 추가하여 Wagtail이 문서로 업로드할 수 있는 파일 형식을 지정합니다. 모든 파일 형식을 허용하도록 생략할 수 있지만, 신뢰할 수 없는 사용자가 문서를 업로드하도록 허용하면 보안 위험이 발생할 수 있습니다. 자세한 내용은 [](user_uploaded_files)를 참조하십시오.

```python
WAGTAILDOCS_EXTENSIONS = ['csv', 'docx', 'key', 'odt', 'pdf', 'pptx', 'rtf', 'txt', 'xlsx', 'zip']
```

Wagtail의 동작을 구성하는 다양한 다른 설정을 사용할 수 있습니다. [설정](/reference/settings)을 참조하십시오.

## URL 구성

이제 `urls.py` 파일에 다음을 추가합니다:

```python
from django.urls import path, include

from wagtail.admin import urls as wagtailadmin_urls
from wagtail import urls as wagtail_urls
from wagtail.documents import urls as wagtaildocs_urls

urlpatterns = [
    ...
    path('cms/', include(wagtailadmin_urls)),
    path('documents/', include(wagtaildocs_urls)),
    path('pages/', include(wagtail_urls)),
    ...
]
```

여기에서 URL 경로를 변경하여 프로젝트의 URL 체계에 맞출 수 있습니다.

`wagtailadmin_urls` 는 Wagtail의 [관리 인터페이스](https://guide.wagtail.org/en-latest/concepts/wagtail-interfaces/#admin-interface)를 제공합니다. 이는 Django 관리 인터페이스인 `django.contrib.admin` 과 별개입니다. Wagtail 전용 프로젝트는 Wagtail 관리자를 `/admin/` 에 호스팅하지만, 프로젝트의 기존 관리 백엔드와 충돌하는 경우 `/cms/` 와 같은 대체 경로를 사용할 수 있습니다.

Wagtail은 `wagtaildocs_urls` 위치에서 문서 파일을 제공합니다. Wagtail의 문서 관리 기능을 사용할 계획이 없는 경우 이 설정을 생략할 수 있습니다.

Wagtail은 `wagtail_urls` 위치에서 페이지를 제공합니다. 위 예제에서 Wagtail은 `/pages/` 아래의 URL을 처리하고, Django 프로젝트는 루트 URL 및 기타 경로를 정상적으로 처리합니다. Wagtail이 루트 URL을 포함한 전체 URL 공간을 처리하도록 하려면 `path('', include(wagtail_urls))` 를 `urlpatterns` 목록의 끝에 배치합니다. `path('', include(wagtail_urls))` 를 `urlpatterns` 의 끝에 배치하면 더 구체적인 URL 패턴을 재정의하지 않습니다.

마지막으로, 프로젝트에서 `MEDIA_ROOT` 에서 사용자 업로드 파일을 제공하도록 설정해야 합니다. Django 프로젝트에 이미 이 설정이 있을 수 있지만, 그렇지 않은 경우 `urls.py` 에 다음 스니펫을 추가합니다:

```python
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
```

이것은 개발 모드(`DEBUG = True`)에서만 작동합니다. 프로덕션에서는 웹 서버가 `MEDIA_ROOT` 에서 파일을 제공하도록 구성해야 합니다. 자세한 내용은 Django 설명서를 참조하십시오: [개발 중 사용자 업로드 파일 제공](<inv:django#howto/static-files/index:serving files uploaded by a user during development>) 및 [정적 파일 배포](inv:django#howto/static-files/deployment).

이 구성이 완료되면 `python manage.py migrate` 를 실행하여 Wagtail에서 사용하는 데이터베이스 테이블을 생성할 준비가 된 것입니다.

## 사용자 계정

Wagtail은 기본적으로 Django의 기본 사용자 모델을 사용합니다. 슈퍼유저 계정은 Wagtail [관리 인터페이스](https://guide.wagtail.org/en-latest/concepts/wagtail-interfaces/#admin-interface)에 자동으로 접근할 수 있습니다. 아직 없는 경우 `python manage.py createsuperuser` 를 사용하십시오. Wagtail은 일부 제한 사항이 있는 사용자 정의 사용자 모델을 지원합니다. Wagtail은 Django의 권한 프레임워크를 확장하므로 사용자 모델은 최소한 `AbstractBaseUser` 및 `PermissionsMixin` 을 상속해야 합니다.

## 페이지 모델 정의 및 개발 시작

페이지를 생성하기 전에 [첫 번째 Wagtail 사이트](/getting_started/tutorial)에 설명된 대로 하나 이상의 페이지 모델을 정의해야 합니다. `wagtail start` 프로젝트 템플릿은 초기 `HomePage` 모델을 포함하는 `home` 앱과 홈페이지를 생성하고 Wagtail이 이를 사용하도록 구성하는 마이그레이션을 제공합니다. 기존 프로젝트에 Wagtail을 통합하는 경우 `python manage.py startapp` 을 통해 이 앱을 직접 생성해야 합니다. (settings.py 파일의 `INSTALLED_APPS` 에 추가하는 것을 잊지 마십시오.)

초기 "새로운 Wagtail 사이트에 오신 것을 환영합니다!" 페이지는 기본 `Page` 모델을 사용하는 플레이스홀더이며 직접 사용할 수 없습니다. 자체 홈 페이지 모델을 정의한 후 Wagtail 관리 인터페이스를 통해 루트 수준에 새 페이지를 생성하고 이를 사이트의 홈 페이지로 설정(설정 / 사이트 아래)해야 합니다. 그런 다음 플레이스홀더 페이지를 삭제할 수 있습니다.