환경 설정 및 사용법#
이 글은 Django Ninja 입문 가이드의 6번째 글이에요.
이전 글에서는 전체 프로젝트에서 사용하는 Python 개발 도구에 대해 알아보았어요.
이번 글에서는 예제 프로젝트의 환경 설정을 단계별로 안내할 거예요. Python 및 Poetry 설치, 로컬로 프로젝트 클론, Python 가상 환경 구축부터 Django 서버의 성공적인 실행까지 다룰 거예요.
이러한 도구를 처음 접하더라도 이 가이드를 따라가면 문제없이 환경 설정을 완료하고 실행할 수 있을 거예요.
참고로 저는 오랫동안 Mac을 사용해 와서 Windows 환경에는 익숙하지 않지만, 가능한 한 관련 대안이나 지침을 제공해 드릴게요.
자, 시작해 볼까요!
GitHub 예제 프로젝트#
1. Python 3.12 설치#
모든 사람의 환경에서 pyenv를 쉽게 설치할 수 있는 것은 아니므로 (특히 Windows는 지원하지 않아요), 여기서는 pyenv가 없는 대안만 설명할게요.
pyenv를 통해 Python을 설치하고 싶다면 이전 글에서 언급한 튜토리얼을 참고해 주세요.
우리는 Python 공식 웹사이트에서 직접 Python 3.12를 다운로드하여 설치할 거예요.
Windows 사용자#
- Python 공식 다운로드 페이지로 이동하여 Python 3.12의 Windows 설치 프로그램을 다운로드해요.
- 다운로드한 설치 파일을 실행하고, 반드시 'Add Python 3.12 to PATH' 옵션을 체크해 주세요.
- 설치가 완료되면 명령 프롬프트를 열고
python --version을 입력하여 성공적으로 설치되었는지 확인해요.
macOS 사용자#
macOS 사용자의 경우 Python 3.12를 설치하는 몇 가지 방법이 있어요:
- pyenv 사용: 제가 개인적으로 추천하는 방식이에요.
- 마찬가지로 공식 설치 프로그램 사용: Python 공식 웹사이트로 이동하여 macOS 버전의 설치 프로그램을 다운로드하고 지침에 따라 설치를 완료해요.
- Homebrew 사용: 이미 Homebrew를 설치했다면 터미널에서
brew install python@3.12를 실행하여 Python 3.12를 설치할 수 있어요.
설치가 완료되면 터미널에 python3 --version을 입력하여 설치가 성공했는지 확인해요.
어떤 방법으로 설치하든 위의 명령어로 Python 버전이 정확한지 반드시 확인해 주세요. 3.12.x 버전이면 돼요.
2. Poetry 설치 및 설정#
프로젝트의 모든 Python 패키지는 Poetry로 관리되므로 먼저 Poetry를 설치해야 해요. 공식 명령어를 통해 직접 설치할 수 있어요: (아래 명령어는 macOS 및 Linux 사용자에게 적용돼요)
설치가 완료되면 Poetry 실행 파일 경로를 시스템의 PATH에 추가해요: (Zsh 사용자)
Bash 사용자:
설치가 성공했는지 확인해요:
Windows에서 Poetry 설치 및 설정#
Windows 사용자는 JetBrains의 Poetry 설정 튜토리얼을 참고할 수 있어요. 설명이 아주 명확하게 잘 되어 있다고 생각해요.
Poetry config 수정하여 .venv 가상 환경 사용하기#
기본값은 false로, Poetry는 별도의 디렉토리에 가상 환경을 생성하며 그 이름이 아주 길어요!
이를 true로 변경하면 프로젝트 루트 디렉토리에 직접 가상 환경을 생성하고 이름이 항상 .venv로 고정돼요.
가상 환경을 프로젝트 내에 두는 것, 이것이 제가 더 선호하는 방식이에요.
Poetry를 사용하지 않는 대안#
pip 사용이 익숙한 독자들을 위해 프로젝트 내에 requirements.txt를 준비했어요. Poetry를 설치하고 설정하는 번거로움을 덜 수 있어요.
3. GitHub에서 프로젝트 다운로드 및 가상 환경 생성#
다음은 프로젝트 자체의 설정이에요.
1. 프로젝트 클론#
이것은 프로젝트 링크예요. git clone 명령어를 사용해요:
git clone https://github.com/kyomind/Django-Ninja-Tutorial.git
# 또는
git clone git@github.com:kyomind/Django-Ninja-Tutorial.git
2. 가상 환경 생성 및 패키지 설치#
프로젝트 디렉토리로 들어가서 Poetry를 사용하여 가상 환경을 생성해요:
이때 프로젝트 루트 디렉토리에 .venv 폴더가 생성될 텐데, 이것이 프로젝트의 가상 환경이며 현재는 비어 있어요.
poetry shell을 사용하여 가상 환경을 활성화해요.
poetry install을 통해 패키지를 설치해요: Poetry는 pyproject.toml과 poetry.lock 내용을 바탕으로 프로젝트에 필요한 모든 패키지를 자동으로 다운로드하고 설치할 거예요.
pip 사용자#
pip 사용자는 다음 단계를 통해 가상 환경을 생성할 수 있어요: (전체 과정은 프로젝트 루트 디렉토리에서 진행돼요)
- Python 내장 venv 모듈을 사용하여 가상 환경 생성:
python -m venv .venv - 가상 환경 활성화:
- Windows:
.venv\Scripts\activate - macOS/Linux:
source .venv/bin/activate
- Windows:
- 패키지 설치:
pip install -r requirements.txt
4. pre-commit 초기화#
가상 환경을 생성하고 poetry install을 사용한 후, pre-commit 패키지는 이미 가상 환경에 설치되어 있어요.
보시다시피 프로젝트 내에 .pre-commit-config.yaml 파일이 있어요. 이 파일은 매 커밋 전에 실행할 검사 항목(Git Hooks)을 정의해요.
다음 명령어를 통해 Git Hooks를 설치하기만 하면 돼요:
이 명령어는 프로젝트의 Git 디렉토리에 Git Hooks를 생성하며, 각 프로젝트당 한 번만 실행하면 돼요.
5. VS Code 확장 프로그램 설치#
IDE로 VS Code를 사용하신다면, Ruff와 Mypy VS Code 확장 프로그램을 설치하는 것을 강력히 추천해요. 현재 코드 상태(문제가 있는지 여부)를 즉시 알 수 있게 해줘요.
프로젝트 내에 이미 관련 설정 파일이 존재하기 때문에, 원칙적으로 이 둘은 설치 후 따로 설정할 필요가 없어요:
- Ruff:
pyproject.toml - Mypy:
mypy.ini(프로젝트의 최신 진행 상황에서는pyproject.toml에 병합되었어요)
또한 이들은 모두 CLI 도구이므로 수동으로 실행할 수도 있어요. 예를 들어 Ruff 검사를 실행하려면:
또는 Mypy 검사를 실행하려면:
하지만 역시 VS Code 확장 프로그램을 사용하는 것이 가장 편리해요.
6. Django 프로젝트 시작하기#
필요한 모든 도구 설정을 마쳤으니 이제 Django 서버를 시작할 수 있어요.
1. 데이터베이스 마이그레이션 수행#
이것은 처음에 반드시 거쳐야 할 단계예요:
사실 프로젝트에 Makefile도 준비되어 있어서 다음 명령어로 마이그레이션을 실행할 수도 있어요:
Makefile에 대한 소개와 튜토리얼은 샤오커의 글 〈웹 개발에서도 Makefile을 사용할 수 있다: 환경 흐름을 잘 관리하자〉를 참고해 주세요.
2. 개발 서버 시작#
다음 명령어를 실행하여 Django 개발 서버를 시작해요:
그런 다음 브라우저를 열고 http://127.0.0.1:8000/에 접속하면 Django의 기본 환영 페이지가 보일 거예요. 프로젝트가 성공적으로 시작되었다는 뜻이에요!
소결#
위의 단계를 통해 프로젝트의 개발 환경 설정을 성공적으로 완료하고 예제 Django 프로젝트를 시작했어요.
설정 과정에서 문제가 발생하면 도구의 공식 문서를 확인하거나 제 블로그의 튜토리얼을 참고하세요. 이러한 리소스는 일반적인 문제를 해결하거나 도구의 기능을 더 깊이 이해하는 데 도움이 될 거예요.
프로젝트 브랜치 및 PR#
프로젝트 개발 과정에서 우리는 Git 브랜치와 GitHub의 PR(Pull requests)을 사용하여 다양한 장의 예제 코드 변경 사항을 관리할 거예요.
이렇게 하면 기능별 코드 변경이 섞여 이해를 방해하는 것을 방지하고 학습 맥락을 명확하고 체계적으로 유지할 수 있어요.
주의할 점은, 어떤 장은 코드 변경 없이 개념 설명만 다루기 때문에 모든 글에 자체 브랜치와 PR이 있는 것은 아니라는 점이에요.
CodeGPT 추천#
또한 본 프로젝트의 거의 모든 커밋 메시지는 우다(吳大)가 개발한 CodeGPT와 GPT-4o mini API를 사용하여 자동 생성되었어요.
아무리 예제 프로젝트라도 모든 커밋 메시지의 내용을 고민하는 것은 쉽지 않으니까요. 이런 자동화 도구가 있으니 정말 훨씬 편리해요! 게다가 스타일의 일관성이 높아서 저 같은 완벽주의자에게 아주 적합해요☺️
CodeGPT에 대해서는 GitHub 페이지 소개 외에도 우다의 글 〈생성형 AI CodeGPT 개발 경험담 - 타이베이 ModernWeb〉을 참고할 수 있으며, 프레젠테이션 슬라이드도 포함되어 있어요.
사용 튜토리얼은 바오거(保哥)의 〈유용한 도구 소개: CodeGPT (GPT를 사용하여 Git 커밋 로그 메시지 자동 생성)〉를 참고해 주세요.
이제 모든 준비가 끝났으니 본격적으로 Django Ninja의 세계로 들어가 볼까요.