myhome-server/README.mac-mini.md

Mac Mini 홈 관리 시스템 실행 가이드

Mac Mini M4 Pro에서 홈 관리 시스템을 운영하기 위한 상세 가이드입니다.

🖥️ Mac Mini 환경 요구사항

• Mac Mini M4 Pro (64GB RAM 권장)
• macOS Sonoma 14.5+
• Docker Desktop for Mac
• Git
• 최소 50GB 여유 공간

🚀 초기 설정

1. Docker Desktop 설치

# Homebrew로 설치 (권장)
brew install --cask docker

# 또는 Docker 공식 사이트에서 다운로드
# https://www.docker.com/products/docker-desktop/

2. 프로젝트 클론

cd /Users/hyungi
git clone https://git.hyungi.net/hyungi/myhome-server.git
cd myhome-server

3. 자동 설정 실행

# 실행 권한 부여
chmod +x scripts/setup-mac-mini.sh

# 설정 실행
./scripts/setup-mac-mini.sh

📁 Mac Mini 데이터 구조

/Users/hyungi/
├── myhome-server/              # 프로젝트 소스
├── home-management-db/         # MariaDB 데이터
├── home-management-redis/      # Redis 데이터
├── home-management-data/       # 업로드 파일
└── home-management-logs/       # 로그 파일
    └── deploy.log

🌐 네트워크 설정

Mac Mini IP 확인

# 현재 IP 주소 확인
ifconfig | grep "inet " | grep -v 127.0.0.1

# 또는
ipconfig getifaddr en0

방화벽 설정 (필요시)

# 포트 3000 허용
sudo pfctl -f /etc/pf.conf

# 또는 시스템 환경설정 > 보안 및 개인정보보호 > 방화벽

🔄 배포 및 업데이트

자동 배포

# 최신 코드로 배포
./scripts/deploy-mac-mini.sh

# 특정 커밋으로 배포
./scripts/deploy-mac-mini.sh [commit-hash]

수동 배포

# 코드 업데이트
git pull origin main

# 서비스 재시작
docker-compose -f docker-compose.mac-mini.yml up -d --build

📊 모니터링 및 관리

서비스 상태 확인

# 컨테이너 상태
docker-compose -f docker-compose.mac-mini.yml ps

# 시스템 리소스
docker stats

# 로그 확인
tail -f /Users/hyungi/home-management-logs/deploy.log

데이터베이스 관리

# phpMyAdmin 접속
open http://localhost:8080

# 직접 MySQL 접속
docker exec -it home_mariadb mysql -u homeuser -p

백업 관리

# 데이터베이스 백업
docker exec home_mariadb mysqldump -u homeuser -pmac_mini_home_password home_management > backup_$(date +%Y%m%d).sql

# 데이터 디렉토리 백업
tar -czf home_management_backup_$(date +%Y%m%d).tar.gz /Users/hyungi/home-management-*

🔧 성능 최적화

Docker 설정 최적화

Docker Desktop > Settings > Resources:

• CPU: 6-8 cores
• Memory: 16-24GB
• Disk: 100GB+

MariaDB 최적화 (이미 적용됨)

# config/mariadb.cnf
innodb_buffer_pool_size = 4G
innodb_log_file_size = 512M
max_connections = 200

🔐 보안 설정

SSH 키 설정 (CI/CD용)

# SSH 키 생성
ssh-keygen -t ed25519 -C "mac-mini-home-server"

# 공개키를 Gitea에 등록
cat ~/.ssh/id_ed25519.pub

환경별 비밀키 관리

# 프로덕션 환경 변수 (docker-compose.mac-mini.yml에 설정됨)
JWT_SECRET=mac-mini-production-jwt-secret-key-2025
DB_PASSWORD=mac_mini_home_password

🚨 트러블슈팅

메모리 부족

# Docker 메모리 사용량 확인
docker system df

# 불필요한 이미지 정리
docker system prune -a

디스크 공간 부족

# 오래된 백업 이미지 정리
docker images | grep "backup" | tail -n +8 | awk '{print $1":"$2}' | xargs docker rmi

# 로그 로테이션
sudo log config --mode "rotate"

네트워크 접근 문제

# 포트 점유 확인
lsof -i :3000

# Docker 네트워크 재설정
docker network prune

📱 외부 접근 설정

홈 네트워크에서 접근

다른 기기에서 접근하려면:

• URL: http://[Mac Mini IP]:3000
• 예시: http://192.168.1.100:3000

포트 포워딩 (라우터 설정)

외부 인터넷에서 접근하려면 라우터에서:

1. 포트 3000을 Mac Mini IP로 포워딩
2. DDNS 설정 (선택사항)

📈 성능 모니터링

시스템 메트릭

# CPU 사용률
top -l 1 | grep "CPU usage"

# 메모리 사용률
vm_stat

# 디스크 I/O
iostat 1

애플리케이션 메트릭

# API 응답 시간
time curl http://localhost:3000/api/devices

# 데이터베이스 성능
docker exec home_mariadb mysql -u homeuser -pmac_mini_home_password -e "SHOW PROCESSLIST;"

🔄 정기 유지보수

일일 작업

• 시스템 상태 확인
• 로그 모니터링
• 백업 상태 확인

주간 작업

• 코드 업데이트 (git pull)
• Docker 이미지 정리
• 데이터베이스 백업

월간 작업

• 전체 시스템 백업
• 성능 리포트 생성
• 보안 업데이트 적용

📞 지원

문제 발생시:

1. /Users/hyungi/home-management-logs/deploy.log 확인
2. Docker 로그 확인: docker-compose -f docker-compose.mac-mini.yml logs
3. GitHub Issues에 로그와 함께 문의

---

Mac Mini M4 Pro의 성능을 최대한 활용하여 안정적인 홈 관리 시스템을 운영하세요! 🏠💻