SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
95bbc90f936fedff1316799af226ac143025a408
sam-docs/specs/docker-setup.md
kent 66eac6b39f docs: [문서정리] 전체 문서 업데이트 및 admin→mng 전환 반영 
- Phase 1-3: 핵심/보조 문서 업데이트, 버전 최신화
- Phase 4: 오래된 파일 정리 및 아카이브
  - D0.8 Storyboard → history/2025-12/ 이동
  - admin 참조 4개 파일 수정 (docker-setup, git-conventions, project-launch-roadmap, remote-work-setup)
  - 빈 디렉토리 6개 삭제
- 버전 정보: React 19.2.1, Next.js 15.5.7
- remote-work-setup.md DEPRECATED 표시
2025-12-26 16:47:36 +09:00

6.7 KiB
Raw Blame History

Docker 설정 가이드

개요

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

서비스 구성

docker-compose.yml 구조

services:
  nginx:      # 리버스 프록시
  api:        # Laravel 12 API (PHP 8.4)
  mng:        # Laravel 12 관리자 패널 (PHP 8.4)
  react:      # Next.js 15 (Node 20)
  design:     # 디자인 시스템 (Storybook)
  mysql:      # MySQL 8.0

서비스별 상세

1. nginx - 리버스 프록시

이미지: nginx:latest

포트: 80

도메인 매핑:

  • api.sam.kr → Laravel API 서버
  • mng.sam.kr, admin.sam.kr → Laravel 관리자 패널
  • 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. mng - Laravel 12 관리자 패널

이미지: php:8.4-fpm

기술 스택:

  • PHP 8.4-fpm
  • Pure Blade + Tailwind CSS
  • Composer 2
  • Supervisor (nginx + php-fpm)

환경 변수: api와 동일

볼륨:

  • ../mng:/var/www/mng - 소스 코드
  • ../docker/mng/nginx.conf - Nginx 설정
  • ../docker/mng/supervisord.conf - Supervisor 설정
  • ../docker/mng/uploads.ini - PHP 업로드 설정

작업 디렉토리: /var/www/mng

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
  • mng.sam.kr → mysql:3306
  • nginx → api:9000 (PHP-FPM)
  • nginx → mng:9000 (PHP-FPM)
  • nginx → react:3000 (Next.js)

사용 방법

초기 설정

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

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

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

개발 워크플로우

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

# 로그 확인
docker-compose logs -f

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

# 서비스 중지
docker-compose down

컨테이너 내부 작업

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

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

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

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

환경 변수 설정

.env 파일

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

api/.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

mng/.env 예시:

APP_NAME=SAM MNG
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://mng.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 예시:

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 파일에 다음을 추가:

127.0.0.1 api.sam.kr
127.0.0.1 mng.sam.kr
127.0.0.1 admin.sam.kr
127.0.0.1 dev.sam.kr

트러블슈팅

포트 충돌

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

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

볼륨 권한 문제

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

컨테이너 재빌드

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

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

로그 확인

# 모든 서비스 로그
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

데이터베이스 초기화

# 볼륨 삭제 (주의: 모든 데이터 삭제)
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. 로그 관리: 로그 로테이션 설정

관련 문서

업데이트: 2025-12-26 (admin→mng 전환, design 서비스 추가)