Infrastructure Setup

프로젝트 정보

• 작성자: 이선민
• 초기 세팅 날짜: 2025-12-23

개요

HandsomFourGuys 프로젝트의 데이터베이스 인프라 설정입니다. PostgreSQL (PostGIS 지원)과 Redis를 Docker Compose로 구성했습니다.

구성 서비스

서비스명	DB 종류	이미지 (버전)	설명	포트 매핑
postgres	PostgreSQL	postgis/postgis:17-3.5	공간/좌표 데이터 처리를 위한 PostGIS 확장 포함, SQL/JSON 표준 지원	5432:5432
redis	Redis	redis:7.2-alpine	세션 및 캐시 저장소	6379:6379

사용 방법

1. 환경 변수 설정

.env 파일을 확인하고 없다면 생성해야 합니다.

# .env 파일 확인
cat .env

2. Docker Compose 명령어

# 컨테이너 시작 (백그라운드)
docker compose -f docker-compose-db.yml up -d

# 컨테이너 상태 확인
docker compose -f docker-compose-db.yml ps

# 로그 확인 (실시간)
docker compose -f docker-compose-db.yml logs -f

# 특정 서비스 로그만 확인
docker compose -f docker-compose-db.yml logs -f postgres
docker compose -f docker-compose-db.yml logs -f redis

# 컨테이너 중지
docker compose -f docker-compose-db.yml stop

# 컨테이너 중지 및 삭제 (데이터는 유지)
docker compose -f docker-compose-db.yml down

# 컨테이너 + 볼륨 전체 삭제 (⚠️ 데이터 삭제됨)
docker compose -f docker-compose-db.yml down -v

# 재시작
docker compose -f docker-compose-db.yml restart

서비스 상세 설명

PostgreSQL (PostGIS)

버전: PostgreSQL 17 + PostGIS 3.5

주요 기능:

• PostGIS: 공간/좌표 데이터 저장 및 처리 (GIS 기능)
• SQL/JSON: JSON 데이터 처리 표준 지원
• 고성능: PostgreSQL 17의 I/O 성능 개선 및 병렬 쿼리 최적화

접속 정보:

Host: localhost
Port: 5432
Database: handsomfourguys
User: postgres
Password: postgres (변경 권장)

확장 기능:

• postgis: 공간 데이터 타입 및 함수
• postgis_topology: 토폴로지 기능

초기화: 컨테이너 첫 실행 시 postgres/init-postgis.sql 스크립트가 자동 실행되어 PostGIS 확장이 설치됩니다.

데이터 저장 위치: ./postgres/data/

---

Redis

버전: Redis 7.2 (Alpine)

주요 기능:

• 세션 관리
• 캐싱
• Pub/Sub 메시징

접속 정보:

Host: localhost
Port: 6379

설정 파일: redis/redis.conf

주요 설정:

• 메모리 제한: 256MB
• 메모리 정책: allkeys-lru (LRU 알고리즘으로 가장 오래된 키 삭제)
• 영속성: RDB 스냅샷 (900초마다 1개 이상 변경 시 저장)

데이터 저장 위치: ./redis/data/

---

플랫폼 호환성

모든 서비스는 platform: linux/amd64로 설정되어 다음 환경에서 동일하게 작동합니다:

• Windows
• macOS (Intel)
• macOS (Apple Silicon - M1/M2/M3) - Rosetta 2를 통한 에뮬레이션

---

추가 작업 필요

Nginx

현재 Nginx 설정은 구성되지 않았습니다. 향후 리버스 프록시 및 로드 밸런싱 설정이 추가될 예정입니다.

---

트러블슈팅

Apple Silicon Mac에서 이미지 pull 실패

platform: linux/amd64 설정으로 해결됩니다. (이미 적용됨)

환경 변수 오류

.env 파일이 infra/ 디렉토리에 있는지 확인하세요.

포트 충돌

다른 서비스가 5432 또는 6379 포트를 사용 중이면 .env 파일에서 포트를 변경하세요.