Skip to main content

Docker 환경 설정

multi-saas-kit의 Docker 환경 구성을 이해합니다.

2파일 체계​

아키텍처별로 2개의 Docker Compose 파일을 제공합니다:

파일아키텍처
docker-compose.amd64.ymlIntel/AMD (x86_64)
docker-compose.arm64.ymlApple Silicon (ARM64)
dev/prod 분리 없음

서버 분리로 환경을 구분합니다. 동일한 설정으로 모든 환경에서 일관성을 유지합니다.

Makefile이 시스템 아키텍처를 자동 감지하므로 수동 선택 불필요!

서비스 구성​

┌─────────────────────────────────────┐
│            localhost:8080           │
│                 ↓                   │
│     ┌─────────────────────┐         │
│     │       nginx         │         │
│     │     (웹서버)         │         │
│     └──────────┬──────────┘         │
│                ↓                    │
│     ┌─────────────────────┐         │
│     │        web          │         │
│     │   (Laravel + PHP)   │         │
│     └──────────┬──────────┘         │
│                │                    │
│     ┌──────────┴──────────┐         │
│     ↓                     ↓         │
│ ┌────────┐          ┌─────────┐     │
│ │postgres│          │  redis  │     │
│ └────────┘          └─────────┘     │
└─────────────────────────────────────┘

서비스 목록​

서비스역할
nginx웹서버, 정적 파일 서빙
webLaravel 애플리케이션 (PHP-FPM)
postgresPostgreSQL 데이터베이스
redis캐시, 세션, 큐

파일 위치​

workspace/{project}/
├── _docker/
│   ├── docker-compose.amd64.yml    # Intel/AMD
│   ├── docker-compose.arm64.yml    # Apple Silicon
│   └── conf/
│       ├── nginx/
│       │   └── default.conf
│       ├── php/
│       │   ├── Dockerfile
│       │   └── php.ini
│       ├── postgres/
│       │   └── init.sql
│       └── redis/
│           └── redis.conf
└── .env

데이터 저장 위치​

데이터는 프로젝트 외부에 저장됩니다:

multi-saas-kit/
├── workspace/{project}/     # 소스 코드 (Git 관리)
└── data/projects/{project}/ # 데이터 (Git 제외)
    ├── postgres/
    └── redis/

장점:

  • 릴리즈 스냅샷이 가벼움
  • 백업/복원 단순화
  • 소스와 데이터 완전 분리

.env 설정​

필수 변수​

# 프로젝트 식별
PROJECT_NAME=myapp

# 포트 설정
APP_PORT=8080
DB_PORT=5432
REDIS_PORT=6379

# Laravel
APP_ENV=local
APP_DEBUG=true
APP_KEY=base64:...

# Database
DB_CONNECTION=pgsql
DB_DATABASE=myapp_db
DB_USERNAME=postgres
DB_PASSWORD=secret

# Redis
REDIS_CLIENT=phpredis

포트 충돌 시​

여러 프로젝트 동시 실행 시 포트 변경:

# 프로젝트 A
APP_PORT=8080
DB_PORT=5432
REDIS_PORT=6379

# 프로젝트 B
APP_PORT=8081
DB_PORT=5433
REDIS_PORT=6380

컨테이너 이름​

프로젝트별로 고유한 컨테이너 이름:

{PROJECT_NAME}-web
{PROJECT_NAME}-postgres
{PROJECT_NAME}-redis
{PROJECT_NAME}-nginx

예: myapp-web, myapp-postgres

자주 쓰는 명령어​

모든 명령어는 루트 폴더에서 NAME 파라미터로 실행합니다.
# 시작
make up NAME=myapp

# 중지
make down NAME=myapp

# 상태 확인
make status NAME=myapp

# 로그 확인
make logs NAME=myapp

# 컨테이너 쉘 접속
make shell NAME=myapp      # 앱
make shell-db NAME=myapp   # PostgreSQL

문제 해결​

컨테이너가 시작되지 않음​

# 선행조건 검사
make check-prereq

# 로그 확인
make logs NAME=myapp

DB 연결 실패​

# DB 컨테이너 상태 확인
docker ps | grep postgres

# DB 로그 확인
make logs-db NAME=myapp

포트 충돌​

Error: port 8080 is already in use

→ .env에서 APP_PORT 변경

다음 단계​