카테고리 없음

[서버 구축 가이드 02] Mac 개발 환경 — 가상환경, 의존성 고정, 비밀값(.env) 분리

PaceMate 2026. 10. 16. 21:51

[서버 구축 가이드 02] Mac 개발 환경 — 가상환경, 의존성 고정, 비밀값(.env) 분리

서버에 올리기 전, 개발 단계에서 미리 잘 해 두면 배포가 훨씬 쉬워지는 것들을 정리합니다. 핵심은 "서버에서 그대로 재현 가능한 환경"과 "비밀값이 코드에 섞이지 않는 구조"입니다.

1. Python 가상환경(venv)

프로젝트마다 독립된 패키지 공간을 만듭니다. 시스템 Python에 패키지를 섞어 설치하면 버전 충돌이 나고, 서버에서 같은 환경을 재현하기 어렵습니다.

cd ~/WorkSpace/proj
python3 -m venv .venv          # 프로젝트 폴더 안에 .venv 생성
source .venv/bin/activate      # 이 터미널에서 .venv의 python/pip 사용
python --version               # 3.12.x 확인 (서버와 맞출 버전)

.venv/는 .gitignore에 넣습니다. 가상환경은 OS마다 다르게 만들어지므로 공유하지 않고, 각 환경에서 새로 만듭니다.

2. 의존성을 정확한 버전으로 고정

# requirements.txt (운영에 필요한 것만)
Django==6.1.1
gunicorn==26.2.0
psycopg==3.3.6
psycopg-binary==3.3.6
python-dotenv==1.2.3
weasyprint==70.0

# requirements-dev.txt (개발·테스트용 추가)
-r requirements.txt
playwright==1.63.0
pip install -r requirements-dev.txt   # 개발 PC
pip install -r requirements.txt       # 서버 (테스트 도구 제외)
pip freeze                            # 실제 설치된 버전 확인

Django>=6 처럼 범위로 쓰면 설치 시점마다 다른 버전이 깔립니다. ==로 고정하면 개발·CI·서버가 같은 버전을 씁니다. 개발용(-dev)과 운영용을 나누면 서버에 브라우저 테스트 도구 같은 무거운 패키지가 깔리지 않습니다.

3. 시스템 라이브러리가 필요한 패키지 (macOS 주의점)

PDF 생성 라이브러리(WeasyPrint)처럼 C 라이브러리(pango)를 쓰는 패키지는 pip만으로 끝나지 않습니다.

brew install pango
# Apple Silicon Mac: Homebrew 라이브러리 경로를 알려 줘야 Python이 찾음
echo 'export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib' >> ~/.zshrc
source ~/.zshrc

이걸 빠뜨리면 OSError: cannot load library 'libgobject-2.0-0' 오류가 납니다. 서버(Ubuntu)에서는 apt install libpango-1.0-0 libpangoft2-1.0-0로 해결합니다(06편). "pip 패키지 + OS 패키지" 목록을 함께 기록해 두는 것이 중요합니다.

4. 비밀값은 .env로 분리

Django의 SECRET_KEY, DB 비밀번호 등을 settings.py에 직접 쓰면 Git 기록에 영원히 남습니다. 환경변수로 읽게 바꿉니다.

# settings.py
import os
from dotenv import load_dotenv

# 서버에서는 PROJ_ENV_FILE로 다른 경로의 파일을 지정. 이미 있는 환경변수가 우선
load_dotenv(os.environ.get("PROJ_ENV_FILE") or BASE_DIR / ".env")

SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY") or "django-insecure-dev-only"
DEBUG = os.environ.get("DJANGO_DEBUG", "True") == "True"
# .gitignore
.env
.env.*
!.env.example     # 예시 파일만 커밋
db.sqlite3        # 개발 DB에도 실제 데이터가 있을 수 있음

.env.example에는 변수 이름과 설명만 적고 값은 비워 둡니다. 새 환경에서는 cp .env.example .env 후 값을 채웁니다. 서버에서는 저장소 밖 /etc/proj/proj.env를 쓰고, systemd가 PROJ_ENV_FILE로 그 위치를 알려 줍니다(09편).

5. 실제 데이터와 시험용 데이터 분리

개발 DB(db.sqlite3)에 실제로 쓰는 기록이 쌓이기 시작하면, 화면 확인이나 스크린샷은 별도 데모 DB로 합니다.

PROJ_DB_PATH=demo.sqlite3 python manage.py migrate
PROJ_DB_PATH=demo.sqlite3 python manage.py runserver

DB 파일 경로도 환경변수로 바꿀 수 있게 해 두면, 실데이터를 건드리지 않고 마음껏 시험할 수 있습니다.

6. AI 코딩 도구를 쓸 때

AI 도구(Claude Code 등)와 함께 개발한다면 도구가 .env를 읽지 못하게 막아 두고, 비밀번호·키를 채팅에 붙여 넣지 않습니다. 예: .claude/settings.json의 permissions.deny에 Read(./.env) 등을 등록하고, 예시 파일(.env.example)만 허용합니다.

체크리스트

  • .venv 생성, .gitignore 등록
  • requirements.txt(운영) / requirements-dev.txt(개발) 버전 고정
  • OS 패키지 목록 기록 (Mac: brew, 서버: apt)
  • 비밀값은 .env, 저장소에는 .env.example만
  • 실데이터 DB와 데모 DB 분리

참고