Preto-1: HR Data Analysis & Visualization

HR 데이터 분석 및 시각화를 위한 Streamlit 기반 대시보드입니다.

🚀 주요 기능

• 개발 모드: 빠른 시작을 위한 경량 데이터 (기본값)

  • 직원 20명, 2024년 7월 이후 데이터
  • 로딩 시간: ~0.5-1초 (프로덕션 대비 25-50배 빠름)

• 프로덕션 모드: 전체 데이터 분석

  • 직원 1000명, 2020년 이후 데이터
  • 로딩 시간: ~15초

요구 사항

• Docker

빌드 및 실행

1. Docker 이미지 빌드

프로젝트 루트 디렉토리에서 다음 명령어를 실행하여 Docker 이미지를 빌드합니다.

docker build -t preto-1 .

2. Docker 컨테이너 실행

🔧 개발 모드 (기본값, 빠른 시작)

추천: 개발 및 테스트 시 사용하세요. 데이터 로딩이 10-20배 빠릅니다.

# 방법 1: 그냥 실행 (자동으로 개발 모드)
docker run --name hra -d -p 8501:8501 -p 8888:8888 -v "$(pwd)":/app preto-1

# 방법 2: 명시적으로 개발 모드 지정
docker run --name hra -d -p 8501:8501 -p 8888:8888 -v "$(pwd)":/app -e ENVIRONMENT=dev preto-1

자동 설정:

• ✅ Streamlit 앱 (포트 8501)
• ✅ Jupyter Notebook (포트 8888)
• ✅ 빠른 데이터 로딩 (20명, 2024년 7월-현재)

🚀 프로덕션 모드 (전체 데이터)

전체 데이터로 분석이 필요할 때 사용하세요.

docker run --name hra -d -p 8501:8501 -v "$(pwd)":/app -e ENVIRONMENT=prod preto-1
docker run --name hra -d -p 8501:8501 -v ${pwd}:/app -e ENVIRONMENT=prod preto-1

자동 설정:

• ✅ Streamlit 앱 (포트 8501)
• ⚠️ Jupyter Notebook 비활성화 (보안)
• ⚠️ 전체 데이터 로딩 (1000명, 2020-현재, 약 15초 소요)

윈도우 사용자 참고:

Windows 환경에서는 $(pwd) 대신 다음을 사용하세요:

• Command Prompt (CMD): %cd%
• PowerShell: ${pwd}

예시:

docker run --name hra -d -p 8501:8501 -p 8888:8888 -v "%cd%":/app preto-1
docker run --name hra -d -p 8501:8501 -p 8888:8888 -v ${pwd}:/app preto-1

사용 방법

웹 인터페이스 접속

• Streamlit 앱 (대시보드)

  • URL: http://localhost:8501
  • 개발 모드/프로덕션 모드 모두 사용 가능

• Jupyter Notebook (개발 모드에만 사용 가능)

  • URL: http://localhost:8888
  • 프로덕션 모드에서는 보안상 비활성화됨

로컬 환경에서 직접 실행 (Docker 없이)

개발 모드 (기본값)

# Python 가상환경 활성화 후
streamlit run src/app.py

# 또는 환경변수 명시
STREAMLIT_DEV_MODE=true streamlit run src/app.py

프로덕션 모드

STREAMLIT_DEV_MODE=false streamlit run src/app.py

유틸리티 스크립트

• Notebook 변환 스크립트 실행

  .ipynb 파일의 변경 사항을 .py 스크립트로 변환하려면, 다음 명령어를 실행합니다.

  docker exec hra python convert_notebooks.py

컨테이너 관리

• 컨테이너 중지:

  docker stop hra

• 컨테이너 시작:

  docker start hra

• 컨테이너 재시작:

  docker restart hra

• 컨테이너 삭제:

  docker rm hra

• 컨테이너 로그 확인:

  docker logs hra

• 컨테이너 내부 접근:

  docker exec -it hra /bin/bash

📊 성능 비교

모드	직원 수	날짜 범위	예상 데이터량	로딩 시간	사용 사례
개발	20명	2024년 7월-현재	~5K 행	~0.5-1초	개발, 테스트, 빠른 확인
프로덕션	1000명	2020-현재	~2.2M 행	~15초	실제 분석, 데모, 배포

🔍 확인 방법

컨테이너 실행 시 로그에서 현재 모드를 확인할 수 있습니다:

docker logs hra

개발 모드 로그 예시

🔍 Detected environment: dev
🚀 Starting in DEVELOPMENT mode...
🔧 [DEV MODE] 개발 모드 활성화:
   - 직원 수: 20명
   - 날짜 범위: 2024-07-01 ~ 현재
   - 예상 로딩 속도: 25-50배 향상
📓 Starting Jupyter Notebook on port 8888...
🎯 Starting Streamlit app on port 8501...

프로덕션 모드 로그 예시

🔍 Detected environment: prod
🚀 Starting in PRODUCTION mode...
🔧 STREAMLIT_DEV_MODE=false (1000 employees, 2020-current data)
🎯 Starting Streamlit app on port 8501...

⚙️ 고급 설정

데이터 크기 동적 조절 (환경변수)

추천 방법: 환경변수를 사용하여 코드 수정 없이 데이터 크기를 조절할 수 있습니다.

로컬 실행 예시

# 1. 최소 크기 (기본값, 가장 빠름) - 20명, 반년치
streamlit run src/app.py

# 2. 중간 크기 - 100명, 2년치
STREAMLIT_NUM_EMPLOYEES=100 STREAMLIT_DATE_START=2023-01-01 streamlit run src/app.py

# 3. 중대형 - 500명, 3년치
STREAMLIT_NUM_EMPLOYEES=500 STREAMLIT_DATE_START=2021-01-01 streamlit run src/app.py

# 4. 대용량 테스트 (프로덕션 크기) - 1000명, 전체 기간
STREAMLIT_NUM_EMPLOYEES=1000 STREAMLIT_DATE_START=2020-01-01 streamlit run src/app.py

Docker 실행 예시

# 중간 크기로 Docker 실행
docker run --name hra -d \
  -e STREAMLIT_NUM_EMPLOYEES=100 \
  -e STREAMLIT_DATE_START=2023-01-01 \
  -p 8501:8501 -p 8888:8888 \
  -v "$(pwd)":/app preto-1

# 대용량으로 Docker 실행
docker run --name hra -d \
  -e STREAMLIT_NUM_EMPLOYEES=1000 \
  -e STREAMLIT_DATE_START=2020-01-01 \
  -p 8501:8501 -p 8888:8888 \
  -v "$(pwd)":/app preto-1

데이터 크기별 성능 비교

설정	직원 수	날짜 범위	예상 데이터량	로딩 시간	사용 사례
최소 (기본)	20명	2024-07-01~	~5K 행	~0.5초	빠른 개발, UI 테스트
중간	100명	2023-01-01~	~80K 행	~2-3초	기능 검증, 중간 데이터 테스트
중대형	500명	2021-01-01~	~900K 행	~7-8초	성능 테스트, 안정성 확인
대용량	1000명	2020-01-01~	~2.2M 행	~15초	프로덕션 시뮬레이션

데이터 크기 커스터마이징 (파일 수정)

직접 src/services/config/dev_config.py 파일을 수정하여 기본값을 변경할 수도 있습니다:

if DEV_MODE:
    NUM_EMPLOYEES = int(os.getenv("STREAMLIT_NUM_EMPLOYEES", "20"))  # 기본값 변경
    DATE_RANGE_START = os.getenv("STREAMLIT_DATE_START", "2024-07-01")  # 기본값 변경

Streamlit 최적화 설정

개발 환경 성능 향상을 위한 설정이 .streamlit/config.toml에 포함되어 있습니다:

• 빠른 재실행 (fastReruns = true)
• 파일 감지 최적화 (fileWatcherType = "poll")
• 개발자 모드 툴바 활성화

사용 가능한 환경변수 목록

환경변수	기본값	설명
STREAMLIT_DEV_MODE	true	개발 모드 활성화 (true/false)
STREAMLIT_NUM_EMPLOYEES	20	DEV 모드에서 생성할 직원 수
STREAMLIT_DATE_START	2024-07-01	DEV 모드에서 데이터 시작 날짜
ENVIRONMENT	dev	Docker 컨테이너 모드 (dev/prod)

참고: 프로덕션 모드(STREAMLIT_DEV_MODE=false)에서는 NUM_EMPLOYEES와 DATE_START 환경변수가 무시되고 항상 전체 데이터(1000명, 2020-01-01~)를 생성합니다.

📚 추가 문서

• 상세 개발 모드 가이드: DEV_MODE_GUIDE.md

🚨 주의사항

1. 개발 모드는 개발/테스트 전용입니다. 데이터 크기가 작아 일부 통계가 부정확할 수 있습니다.
2. 프로덕션 배포 시 반드시 ENVIRONMENT=prod로 설정하세요.
3. 로컬 파일을 볼륨 마운트(-v)하면 코드 변경사항이 즉시 반영됩니다.