news-project/HOMEBREW_SETUP.md

🍺 Homebrew 기반 개발환경 설정 가이드

📋 개요

macOS에서 Homebrew를 사용하여 산업 전문 정보 수집 시스템의 개발환경을 설정하는 단계별 가이드입니다.

---

🔧 사전 요구사항

시스템 요구사항

• macOS: 12.0+ (Monterey 이상 권장)
• 메모리: 8GB 이상 (16GB 권장)
• 저장공간: 20GB 이상 여유 공간
• 네트워크: 인터넷 연결 (패키지 다운로드용)

개발자 도구

# Xcode Command Line Tools 설치 (Homebrew 설치 전 필수)
xcode-select --install

---

🍺 1단계: Homebrew 설치

Homebrew 설치

# Homebrew 설치 스크립트 실행
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 설치 확인
brew --version

# PATH 설정 (M1/M2 Mac의 경우)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Homebrew 업데이트

# Homebrew 자체 업데이트
brew update

# 설치된 패키지 업그레이드
brew upgrade

---

🐍 2단계: Python 환경 설정

Python 설치

# Python 3.11 설치 (최신 안정 버전)
brew install python@3.11

# 설치 확인
python3 --version
pip3 --version

# 심볼릭 링크 설정 (선택사항)
brew link python@3.11

가상환경 도구 설치

# virtualenv 설치
pip3 install virtualenv

# 또는 pyenv 사용 (Python 버전 관리)
brew install pyenv
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

프로젝트 가상환경 생성

# 프로젝트 디렉토리로 이동
cd /Users/hyungi/news-project

# 가상환경 생성
python3 -m venv venv

# 가상환경 활성화
source venv/bin/activate

# 가상환경 활성화 확인 (프롬프트에 (venv) 표시됨)
which python

---

🟢 3단계: Node.js 환경 설정

Node.js 설치

# Node.js 18 LTS 설치
brew install node@18

# 설치 확인
node --version
npm --version

# 글로벌 패키지 업데이트
npm install -g npm@latest

선택적: Node 버전 관리자 설치

# nvm 설치 (Node Version Manager)
brew install nvm

# nvm 설정
mkdir ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/share/nvm/nvm.sh" ] && \. "/opt/homebrew/share/nvm/nvm.sh"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/share/nvm/bash_completion" ] && \. "/opt/homebrew/share/nvm/bash_completion"' >> ~/.zshrc
source ~/.zshrc

# Node.js 18 설치 및 사용
nvm install 18
nvm use 18
nvm alias default 18

---

🗄️ 4단계: 데이터베이스 설치

PostgreSQL 설치

# PostgreSQL 설치
brew install postgresql@15

# 서비스 시작
brew services start postgresql@15

# 데이터베이스 생성
createdb industrial_info

# 연결 테스트
psql industrial_info
# \q 로 종료

PostgreSQL 설정

# 사용자 생성 (선택사항)
createuser --interactive --pwprompt industrial_user

# 데이터베이스 권한 부여
psql -c "GRANT ALL PRIVILEGES ON DATABASE industrial_info TO industrial_user;"

Redis 설치

# Redis 설치
brew install redis

# 서비스 시작
brew services start redis

# 연결 테스트
redis-cli ping
# PONG 응답 확인

---

🔍 5단계: Elasticsearch 설치

Elasticsearch 설치

# Elasticsearch 설치
brew install elasticsearch

# 설정 파일 위치 확인
brew --prefix elasticsearch

# JVM 메모리 설정 (8GB Mac 기준)
echo 'export ELASTICSEARCH_JAVA_OPTS="-Xms512m -Xmx1g"' >> ~/.zshrc
source ~/.zshrc

# 서비스 시작
brew services start elasticsearch

# 연결 테스트 (약 30초 후)
curl http://localhost:9200

Elasticsearch 한국어 분석기 설치

# nori 분석기 설치
/opt/homebrew/bin/elasticsearch-plugin install analysis-nori

# 서비스 재시작
brew services restart elasticsearch

---

🐳 6단계: Docker 설치

Docker Desktop 설치

# Docker Desktop 설치
brew install --cask docker

# Docker 실행 확인 (GUI에서 Docker Desktop 실행 필요)
docker --version
docker-compose --version

Docker 설정 최적화

# Docker Desktop 설정 권장사항:
# - Memory: 4GB (8GB Mac 기준)
# - Swap: 1GB
# - Disk image size: 64GB

---

🛠️ 7단계: 개발 도구 설치

필수 개발 도구

# Git (이미 설치되어 있을 수 있음)
brew install git

# 시스템 모니터링 도구
brew install htop

# 텍스트 처리 도구
brew install jq          # JSON 처리
brew install ripgrep     # 빠른 텍스트 검색

# 네트워크 도구
brew install curl
brew install wget

IDE 및 에디터

# Visual Studio Code
brew install --cask visual-studio-code

# 또는 다른 에디터들
brew install --cask sublime-text
brew install --cask atom
brew install vim         # 터미널 에디터

선택적 도구

# 데이터베이스 GUI 도구
brew install --cask dbeaver-community    # 다중 DB 클라이언트
brew install --cask tableplus           # macOS 네이티브 DB 클라이언트

# API 테스트 도구
brew install --cask postman
brew install --cask insomnia

# 터미널 개선
brew install zsh-autosuggestions
brew install zsh-syntax-highlighting

---

🚀 8단계: 프로젝트 설정

프로젝트 클론 및 설정

# 프로젝트 디렉토리로 이동
cd /Users/hyungi/news-project

# 가상환경 활성화
source venv/bin/activate

# 환경 변수 파일 생성
cp .env.example .env

환경 변수 설정 (.env 파일)

# .env 파일 편집
cat > .env << EOF
# 데이터베이스 설정
DATABASE_URL=postgresql://industrial_user:password@localhost:5432/industrial_info
REDIS_URL=redis://localhost:6379/0
ELASTICSEARCH_URL=http://localhost:9200

# 개발 환경 설정
DEBUG=True
SECRET_KEY=your-secret-key-here

# API 키 (필요시)
PUBMED_API_KEY=your-pubmed-api-key
IEEE_API_KEY=your-ieee-api-key
EOF

Python 의존성 설치

# requirements.txt가 있는 경우
pip install -r requirements.txt

# 또는 기본 패키지 설치
pip install fastapi uvicorn sqlalchemy psycopg2-binary redis elasticsearch celery spacy beautifulsoup4 requests pandas numpy

Node.js 의존성 설치 (프론트엔드가 있는 경우)

# frontend 디렉토리가 있는 경우
cd frontend
npm install
cd ..

---

🔧 9단계: 서비스 관리

서비스 시작/중지 명령어

# 모든 서비스 시작
brew services start postgresql@15
brew services start redis
brew services start elasticsearch

# 서비스 상태 확인
brew services list

# 특정 서비스 중지
brew services stop postgresql@15
brew services stop redis
brew services stop elasticsearch

# 서비스 재시작
brew services restart postgresql@15

자동 시작 설정

# 시스템 부팅 시 자동 시작 (이미 설정됨)
# brew services start 명령어로 설치한 서비스들은 자동으로 부팅 시 시작됨

# 수동으로 자동 시작 해제하려면
brew services stop postgresql@15
# 그리고 수동으로 시작하려면
pg_ctl -D /opt/homebrew/var/postgresql@15 start

---

📊 10단계: 성능 최적화

메모리 사용량 최적화 (8GB Mac 기준)

# ~/.zshrc에 추가
cat >> ~/.zshrc << EOF

# 개발환경 메모리 최적화
export ELASTICSEARCH_JAVA_OPTS="-Xms512m -Xmx1g"
export REDIS_MAXMEMORY="256mb"
export PYTHONOPTIMIZE=1

# PostgreSQL 설정 최적화
export PGDATA="/opt/homebrew/var/postgresql@15"
EOF

source ~/.zshrc

PostgreSQL 설정 최적화

# postgresql.conf 편집
vim /opt/homebrew/var/postgresql@15/postgresql.conf

# 다음 설정 추가/수정:
# shared_buffers = 256MB
# effective_cache_size = 1GB
# maintenance_work_mem = 64MB
# checkpoint_completion_target = 0.9
# wal_buffers = 16MB
# default_statistics_target = 100

# 설정 적용을 위해 재시작
brew services restart postgresql@15

---

🔍 11단계: 개발환경 테스트

연결 테스트 스크립트

# test_connections.py 생성
cat > test_connections.py << EOF
#!/usr/bin/env python3
import psycopg2
import redis
import requests

def test_postgresql():
    try:
        conn = psycopg2.connect(
            host="localhost",
            database="industrial_info",
            user="industrial_user",
            password="password"
        )
        print("✅ PostgreSQL 연결 성공")
        conn.close()
    except Exception as e:
        print(f"❌ PostgreSQL 연결 실패: {e}")

def test_redis():
    try:
        r = redis.Redis(host='localhost', port=6379, db=0)
        r.ping()
        print("✅ Redis 연결 성공")
    except Exception as e:
        print(f"❌ Redis 연결 실패: {e}")

def test_elasticsearch():
    try:
        response = requests.get('http://localhost:9200')
        if response.status_code == 200:
            print("✅ Elasticsearch 연결 성공")
        else:
            print(f"❌ Elasticsearch 연결 실패: {response.status_code}")
    except Exception as e:
        print(f"❌ Elasticsearch 연결 실패: {e}")

if __name__ == "__main__":
    print("🔍 개발환경 연결 테스트")
    test_postgresql()
    test_redis()
    test_elasticsearch()
EOF

# 테스트 실행
python test_connections.py

시스템 리소스 모니터링

# 시스템 리소스 확인
htop

# Docker 컨테이너 리소스 확인 (Docker 사용 시)
docker stats

# 디스크 사용량 확인
df -h

# 메모리 사용량 확인
vm_stat

---

🚨 문제 해결

일반적인 문제들

1. Homebrew 설치 실패

# 권한 문제 해결
sudo chown -R $(whoami) /opt/homebrew

# 또는 Rosetta 2 설치 (M1/M2 Mac)
softwareupdate --install-rosetta

2. PostgreSQL 연결 실패

# 서비스 상태 확인
brew services list | grep postgresql

# 로그 확인
tail -f /opt/homebrew/var/log/postgresql@15.log

# 포트 충돌 확인
lsof -i :5432

3. Elasticsearch 시작 실패

# Java 설치 확인
java --version

# 메모리 부족 시 설정 조정
export ELASTICSEARCH_JAVA_OPTS="-Xms256m -Xmx512m"

# 로그 확인
tail -f /opt/homebrew/var/log/elasticsearch.log

4. Redis 연결 문제

# Redis 서비스 확인
brew services list | grep redis

# 설정 파일 확인
cat /opt/homebrew/etc/redis.conf

# 포트 확인
lsof -i :6379

성능 문제 해결

메모리 부족 시

# 불필요한 서비스 중지
brew services stop elasticsearch  # 임시로 중지

# Swap 사용량 확인
sysctl vm.swapusage

# 메모리 정리
sudo purge

디스크 공간 부족 시

# Homebrew 캐시 정리
brew cleanup

# Docker 이미지 정리
docker system prune -a

# 로그 파일 정리
sudo rm -rf /opt/homebrew/var/log/*.log.*

---

📚 추가 리소스

유용한 명령어 모음

# 모든 Homebrew 서비스 상태 확인
brew services list

# 설치된 패키지 목록
brew list

# 패키지 정보 확인
brew info postgresql@15

# 의존성 확인
brew deps --tree postgresql@15

# 업데이트 가능한 패키지 확인
brew outdated

개발 워크플로우

# 일일 개발 시작 루틴
cd /Users/hyungi/news-project
source venv/bin/activate
brew services start postgresql@15 redis elasticsearch

# 일일 개발 종료 루틴
deactivate
brew services stop elasticsearch  # 메모리 절약을 위해

백업 및 복원

# PostgreSQL 백업
pg_dump industrial_info > backup.sql

# PostgreSQL 복원
psql industrial_info < backup.sql

# 설정 파일 백업
cp ~/.zshrc ~/.zshrc.backup
cp .env .env.backup

---

이 가이드를 따라하면 macOS에서 Homebrew를 사용하여 완전한 개발환경을 구축할 수 있습니다. 각 단계별로 진행하면서 문제가 발생하면 문제 해결 섹션을 참조하세요.