sam-docs/specs/docker-setup.md

# Docker 설정 가이드

## 개요

SAM 프로젝트는 Docker Compose를 사용하여 로컬 개발 환경을 구성합니다.

## 서비스 구성

### docker-compose.yml 구조

```yaml
services:
  nginx:      # 리버스 프록시
  api:        # Laravel 12 API (PHP 8.4)
  admin:      # Laravel 12 Admin (PHP 8.4)
  react:      # Next.js 15 (Node 20)
  mysql:      # MySQL 8.0
```

## 서비스별 상세

### 1. nginx - 리버스 프록시

**이미지**: `nginx:latest`

**포트**: 80

**도메인 매핑**:
- `api.sam.kr` → Laravel API 서버
- `admin.sam.kr` → Laravel Admin 패널
- `dev.sam.kr` → Next.js 프론트엔드

**주요 기능**:
- 보안 규칙 적용 (경로 탐색 공격 차단)
- User-Agent 필터링 (보안 스캔 도구 차단)
- WebSocket 지원 (Next.js HMR)
- 정적 자산 캐싱

**설정 파일**: `docker/nginx/nginx.conf`

### 2. api - Laravel 12 API 서버

**이미지**: `php:8.4-fpm`

**기술 스택**:
- PHP 8.4-fpm
- Composer 2
- Supervisor (nginx + php-fpm)

**PHP 확장**:
- zip
- mysqli
- pdo
- pdo_mysql
- intl

**환경 변수**:
- `DB_HOST=sam-mysql-1`
- `DB_PORT=3306`
- `DB_DATABASE=samdb`
- `DB_USERNAME=samuser`
- `DB_PASSWORD=sampass`

**볼륨**:
- `../api:/var/www/api` - 소스 코드
- `../docker/api/nginx.conf` - Nginx 설정
- `../docker/api/supervisord.conf` - Supervisor 설정
- `../docker/api/uploads.ini` - PHP 업로드 설정

**작업 디렉토리**: `/var/www/api`

### 3. admin - Laravel 12 Admin 패널

**이미지**: `php:8.4-fpm`

**기술 스택**:
- PHP 8.4-fpm
- Filament v4
- Composer 2
- Supervisor (nginx + php-fpm)

**환경 변수**: api와 동일

**볼륨**:
- `../admin:/var/www/admin` - 소스 코드
- `../docker/admin/nginx.conf` - Nginx 설정
- `../docker/admin/supervisord.conf` - Supervisor 설정
- `../docker/admin/uploads.ini` - PHP 업로드 설정

**작업 디렉토리**: `/var/www/admin`

### 4. react - Next.js 15 프론트엔드

**이미지**: `node:20-alpine`

**기술 스택**:
- Node.js 20
- Next.js 15
- React 19.2.0

**포트**: 3000 (내부)

**환경 변수**:
- `NEXT_PUBLIC_API_BASE_URL=http://api.sam.kr`
- `NEXT_PUBLIC_ADMIN_URL=http://admin.sam.kr`
- `NEXT_PUBLIC_API_KEY` (선택)
- `NEXT_PUBLIC_APP_NAME=SAM`
- `NODE_ENV=development`

**볼륨**:
- `../react:/app` - 소스 코드
- `/app/node_modules` - node_modules 격리
- `/app/.next` - Next.js 빌드 캐시

**작업 디렉토리**: `/app`

**개발 서버**: `npm run dev` (포트 3000)

### 5. mysql - MySQL 데이터베이스

**이미지**: `mysql:8.0`

**포트**: 3306

**환경 변수**:
- `MYSQL_DATABASE=samdb`
- `MYSQL_USER=samuser`
- `MYSQL_PASSWORD=sampass`
- `MYSQL_ROOT_PASSWORD=root`

**볼륨**:
- `db_data:/var/lib/mysql` - 데이터 영구 저장
- `../docker/mysql/init.sql` - 초기화 스크립트

## 네트워크

### samnet (bridge network)

모든 서비스가 `samnet` 네트워크에 연결되어 서로 통신할 수 있습니다.

**서비스 간 통신**:
- `api.sam.kr` → `mysql:3306`
- `admin.sam.kr` → `mysql:3306`
- `nginx` → `api:9000` (PHP-FPM)
- `nginx` → `admin:9000` (PHP-FPM)
- `nginx` → `react:3000` (Next.js)

## 사용 방법

### 초기 설정

```bash
# 1. Docker 디렉토리로 이동
cd docker

# 2. 서비스 시작
docker-compose up -d

# 3. 서비스 상태 확인
docker-compose ps
```

### 개발 워크플로우

```bash
# 서비스 시작
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 특정 서비스 재시작
docker-compose restart api

# 서비스 중지
docker-compose down
```

### 컨테이너 내부 작업

```bash
# API 컨테이너에서 마이그레이션
docker-compose exec api php artisan migrate

# Admin 컨테이너에서 Composer 설치
docker-compose exec admin composer install

# React 컨테이너에서 npm 설치
docker-compose exec react npm install

# MySQL 접속
docker-compose exec mysql mysql -u samuser -psampass samdb
```

## 환경 변수 설정

### .env 파일

각 애플리케이션 디렉토리(`api/`, `admin/`, `react/`)에 `.env` 파일을 생성해야 합니다.

**api/.env 예시**:
```env
APP_NAME=SAM API
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://api.sam.kr

DB_CONNECTION=mysql
DB_HOST=sam-mysql-1
DB_PORT=3306
DB_DATABASE=samdb
DB_USERNAME=samuser
DB_PASSWORD=sampass
```

**admin/.env 예시**:
```env
APP_NAME=SAM Admin
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://admin.sam.kr

DB_CONNECTION=mysql
DB_HOST=sam-mysql-1
DB_PORT=3306
DB_DATABASE=samdb
DB_USERNAME=samuser
DB_PASSWORD=sampass
```

**react/.env.local 예시**:
```env
NEXT_PUBLIC_API_BASE_URL=http://api.sam.kr
NEXT_PUBLIC_ADMIN_URL=http://admin.sam.kr
NEXT_PUBLIC_API_KEY=your-api-key
NEXT_PUBLIC_APP_NAME=SAM
```

## 호스트 파일 설정

로컬에서 도메인 접근을 위해 `/etc/hosts` 파일에 다음을 추가:

```bash
127.0.0.1 api.sam.kr
127.0.0.1 admin.sam.kr
127.0.0.1 dev.sam.kr
```

## 트러블슈팅

### 포트 충돌

```bash
# 포트 사용 확인
lsof -i :80
lsof -i :3306

# 포트를 사용하는 프로세스 종료
kill -9 <PID>
```

### 볼륨 권한 문제

```bash
# storage 디렉토리 권한 설정
docker-compose exec api chmod -R 775 storage
docker-compose exec admin chmod -R 775 storage
```

### 컨테이너 재빌드

```bash
# 특정 서비스 재빌드
docker-compose build --no-cache api

# 모든 서비스 재빌드
docker-compose build --no-cache
```

### 로그 확인

```bash
# 모든 서비스 로그
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f api
docker-compose logs -f react

# Nginx 에러 로그
docker-compose exec nginx tail -f /var/log/nginx/api.sam.kr_error.log
```

### 데이터베이스 초기화

```bash
# 볼륨 삭제 (주의: 모든 데이터 삭제)
docker-compose down -v

# 재시작
docker-compose up -d
```

## 보안 설정

### Nginx 보안 규칙

`docker/nginx/nginx.conf`에 다음 보안 규칙이 적용되어 있습니다:

1. **경로 탐색 공격 차단**:
   - `../`, `..\`, `etc/passwd`, `.env`, `.git` 등 차단

2. **보안 스캔 도구 차단**:
   - sqlmap, nikto, nmap, masscan 등 User-Agent 필터링

3. **정적 자산 캐싱**:
   - 30일 캐시 설정

## 프로덕션 배포

프로덕션 환경에서는 다음을 고려해야 합니다:

1. **HTTPS 설정**: SSL/TLS 인증서 적용
2. **환경 변수**: `.env` 파일 보안 관리
3. **볼륨 백업**: 데이터베이스 정기 백업
4. **리소스 제한**: 컨테이너 메모리/CPU 제한 설정
5. **로그 관리**: 로그 로테이션 설정

## 관련 문서

- [시스템 아키텍처](./02-architecture.md)
- [개발 명령어](./05-development.md)
- [보안 가이드](./08-security.md)

---

**업데이트**: 2025-11-18 (PHP 8.4, Next.js 15 반영)