본문으로 건너뛰기

설치 가이드

📝 초안 (Draft)

이 문서는 검토 중입니다. 내용이 변경될 수 있습니다.

Multi-SaaS Kit의 상세 설치 및 설정 방법을 안내합니다. 5분 내 빠른 시작은 빠른 시작을, 시스템 요구사항은 시스템 요구사항을 참조하세요.

설치 전 준비​

요구사항 확인​

# Docker 버전 (24.0+ 권장)
docker --version

# Docker Compose 버전 (2.20+ 권장)
docker compose version

# Git 버전 (2.30+)
git --version

# Make 버전 (4.0+)
make --version

아키텍처 확인​

Multi-SaaS Kit은 **AMD64(x86_64)**와 ARM64(Apple Silicon) 모두 지원합니다. Makefile이 자동으로 감지하지만, 확인하려면:

uname -m
# x86_64      → AMD64 (Intel/AMD)
# aarch64/arm64 → ARM64 (Apple Silicon, AWS Graviton)

설치 단계​

1단계: 저장소 클론​

git clone https://github.com/your-org/multi-saas-kit.git
cd multi-saas-kit

2단계: 플랫폼 환경 설정 (선택)​

플랫폼 레벨 설정이 필요한 경우:

cp .env.example .env

.env에서 설정 가능한 항목:

변수기본값설명
PLATFORM_NAMEmsk플랫폼 식별자 (컨테이너 네트워크 접두사, 소문자 권장)

대부분의 경우 기본값으로 충분합니다.

3단계: 프로젝트 생성​

템플릿에서 새 프로젝트를 생성합니다:

# 템플릿 복사
cp -r workspace/_template workspace/myproject

# 프로젝트 폴더로 이동
cd workspace/myproject

# 환경 파일 생성
cp .env.example .env

4단계: 프로젝트 환경 설정​

.env 파일을 편집합니다:

nano .env  # 또는 vi .env, code .env

필수 설정 항목​

#══════════════════════════════════════════════════════════════
# 1. 프로젝트 식별자
#══════════════════════════════════════════════════════════════
PROJECT_NAME=myproject

#══════════════════════════════════════════════════════════════
# 2. 포트 설정 (포트 할당표 참조)
#══════════════════════════════════════════════════════════════
APP_PORT=8110          # 웹 접속 포트 (8100-8199)
DB_PORT=5433           # PostgreSQL 포트 (5432-5449)
REDIS_PORT=6380        # Redis 포트 (6379-6399)

#══════════════════════════════════════════════════════════════
# 3. Platform Admin 계정 (⚠️ 보안 필수)
#══════════════════════════════════════════════════════════════
PLATFORM_ADMIN_EMAIL=admin@yourcompany.com
PLATFORM_ADMIN_PASSWORD=YourSecureP@ssw0rd!
PLATFORM_ADMIN_NAME="System Admin"

#══════════════════════════════════════════════════════════════
# 4. 애플리케이션 URL
#══════════════════════════════════════════════════════════════
APP_URL=http://localhost:${APP_PORT}

데이터베이스 설정​

#══════════════════════════════════════════════════════════════
# PostgreSQL 설정
#══════════════════════════════════════════════════════════════
DB_CONNECTION=pgsql
DB_HOST=postgres              # Docker 서비스명
DB_DATABASE=myproject_db
DB_USERNAME=postgres
DB_PASSWORD=your_db_password  # 변경 권장

Redis 설정​

#══════════════════════════════════════════════════════════════
# Redis 설정
#══════════════════════════════════════════════════════════════
REDIS_HOST=redis              # Docker 서비스명
REDIS_PASSWORD=null           # 필요시 설정
REDIS_PORT=6379               # 컨테이너 내부 포트 (외부는 REDIS_PORT)

5단계: 초기 설치​

루트 폴더로 이동하여 설치 명령을 실행합니다:

# 루트 폴더로 이동
cd ../..

# 초기 설치 실행
make install NAME=myproject

설치 과정에서 수행되는 작업​

make install NAME=myproject
    │
    ├── 1. 선행 조건 검사
    │   ├── Docker 실행 상태 확인
    │   ├── 필수 포트 사용 가능 여부
    │   └── 환경 파일 존재 여부
    │
    ├── 2. Docker 이미지 빌드
    │   ├── PHP/Laravel 이미지
    │   ├── Nginx 이미지 (설정 포함)
    │   └── 기타 서비스
    │
    ├── 3. 컨테이너 시작
    │   ├── PostgreSQL 시작 + 헬스체크 대기
    │   ├── Redis 시작 + 헬스체크 대기
    │   └── 앱 컨테이너 시작
    │
    ├── 4. Laravel 설치
    │   ├── Composer 의존성 설치
    │   ├── APP_KEY 자동 생성
    │   ├── 캐시 정리
    │   └── 스토리지 링크 생성
    │
    ├── 5. 데이터베이스 설정
    │   ├── 마이그레이션 실행
    │   └── 초기 시더 실행 (Platform Admin 생성)
    │
    └── 6. 완료 메시지

6단계: 컨테이너 시작​

make up NAME=myproject

권한 문제 발생 시​

Makefile이 권한 문제를 감지하면 안내 메시지가 표시됩니다:

╔══════════════════════════════════════════════════════════════╗
║ ⚠️  Laravel 권한 설정 필요                                  ║
╠══════════════════════════════════════════════════════════════╣
║   sudo chmod -R 777 /path/to/storage                        ║
║   sudo chmod -R 777 /path/to/bootstrap/cache                ║
╚══════════════════════════════════════════════════════════════╝

표시된 명령을 실행한 후 make up NAME=myproject를 다시 실행하세요.

설치 확인​

상태 확인​

make status NAME=myproject

정상 출력 예시:

NAME                      STATUS    PORTS
myproject-nginx           running   0.0.0.0:8110->80/tcp
myproject-web             running   9000/tcp
myproject-postgres        running   0.0.0.0:5433->5432/tcp
myproject-redis           running   0.0.0.0:6380->6379/tcp

헬스체크​

make health NAME=myproject

로그 확인​

# 전체 로그
make logs NAME=myproject

# 앱 로그만
make logs-app NAME=myproject

# DB 로그만
make logs-db NAME=myproject

웹 접속 테스트​

브라우저에서 접속:

URL설명
http://localhost:8110메인 페이지
http://localhost:8110/platformPlatform Admin 패널

고급 설정​

Docker Compose 2파일 체계​

Multi-SaaS Kit은 아키텍처별로 2개의 Docker Compose 파일을 사용합니다:

workspace/myproject/_docker/
├── docker-compose.amd64.yml   # Intel/AMD
├── docker-compose.arm64.yml   # Apple Silicon, ARM
└── conf/                      # 서비스 설정
    ├── nginx/
    ├── php/
    ├── postgres/
    └── redis/

Makefile이 시스템 아키텍처를 자동 감지하여 적절한 파일을 선택합니다.

데이터 저장 위치​

소스 코드와 데이터는 분리되어 관리됩니다:

유형위치Git 관리
소스 코드workspace/myproject/O
DB 데이터data/projects/myproject/postgres/X
Redis 데이터data/projects/myproject/redis/X

Vite 개발 모드​

프론트엔드 개발 시 Vite watch 모드 활성화:

make up NAME=myproject DEV=1
  • 파일 변경 시 자동 빌드
  • /public/build/에 결과물 생성
  • 페이지 새로고침으로 변경 확인

여러 프로젝트 운영​

포트 할당 전략​

여러 프로젝트를 동시에 운영할 때는 포트 충돌을 방지해야 합니다:

프로젝트APP_PORTDB_PORTREDIS_PORT
첫 번째811054336380
두 번째812054346381
세 번째813054356382

자세한 포트 할당 규칙은 포트 할당을 참조하세요.

프로젝트 관리 명령어​

# 프로젝트 목록 확인
make list

# 모든 프로젝트 포트 현황
make ports

# 특정 프로젝트만 시작/중지
make up NAME=project-a
make down NAME=project-b

업데이트 및 유지보수​

의존성 업데이트​

# 컨테이너 접속
make shell NAME=myproject

# Composer 업데이트
composer update

# npm 업데이트
npm update

마이그레이션 실행​

make migrate NAME=myproject

캐시 정리​

make cache-clear NAME=myproject

Docker 이미지 재빌드​

설정 변경 후 이미지 재빌드가 필요한 경우:

make build NAME=myproject
make restart NAME=myproject

삭제 및 정리​

컨테이너만 중지​

make down NAME=myproject

컨테이너 + 볼륨 삭제 (데이터 삭제)​

make clean NAME=myproject
데이터 손실 주의

clean 명령은 데이터베이스 데이터를 포함한 모든 볼륨을 삭제합니다. 실행 전 백업을 권장합니다.

프로젝트 완전 삭제​

# 1. 컨테이너 중지 및 정리
make clean NAME=myproject

# 2. 소스 폴더 삭제
rm -rf workspace/myproject

# 3. 데이터 폴더 삭제
rm -rf data/projects/myproject

문제 해결​

Docker 권한 오류 (Linux)​

# 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# 변경 적용 (로그아웃 후 재로그인 또는)
newgrp docker

포트 이미 사용 중​

# 사용 중인 포트 확인
docker ps
lsof -i :8110

# 충돌하는 컨테이너 중지 또는 .env에서 포트 변경

데이터베이스 연결 실패​

# 컨테이너 상태 확인
make status NAME=myproject

# PostgreSQL 로그 확인
make logs-db NAME=myproject

# 컨테이너 내부에서 연결 테스트
make shell NAME=myproject
php artisan db:show

권한 관련 오류​

# Laravel storage/cache 권한
sudo chmod -R 777 workspace/myproject/web/storage
sudo chmod -R 777 workspace/myproject/web/bootstrap/cache

다음 단계​

설치가 완료되었습니다. 다음 문서를 참조하세요: