본문으로 건너뛰기

빠른 시작

📝 초안 (Draft)

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

5분 안에 Multi-SaaS Kit으로 첫 프로젝트를 실행해 봅니다.

사전 요구사항​

시작하기 전에 다음 도구가 설치되어 있어야 합니다:

도구최소 버전확인 명령
Docker24.0+docker --version
Docker Compose2.20+docker compose version
Git2.30+git --version
Make4.0+make --version

Windows 사용자: WSL2 환경에서 실행하세요. 네이티브 Windows는 지원하지 않습니다.

1단계: 저장소 클론​

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

플랫폼 구조를 확인합니다:

ls -la
multi-saas-kit/
├── Makefile           # 통합 관리 명령
├── CLAUDE.md          # AI 지침 (Claude Code용)
├── ops/               # 운영 스크립트
├── workspace/         # 프로젝트 소스
│   ├── _template/     # 프로젝트 템플릿
│   ├── _docs/         # 플랫폼 문서
│   └── ...
└── data/              # 런타임 데이터 (자동 생성)

2단계: 프로젝트 생성​

템플릿에서 새 프로젝트를 복사합니다:

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

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

3단계: 환경변수 설정​

.env 파일을 생성하고 필수 항목을 설정합니다:

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

.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_EMAIL=admin@mycompany.com
PLATFORM_ADMIN_PASSWORD=MySecureP@ssw0rd!
PLATFORM_ADMIN_NAME="System Admin"

#──────────────────────────────────────────────────────────────
# 4. 앱 URL (프로덕션 배포 시 실제 도메인으로 변경)
#──────────────────────────────────────────────────────────────
APP_URL=http://localhost:${APP_PORT}
보안 주의

PLATFORM_ADMIN_EMAIL과 PLATFORM_ADMIN_PASSWORD는 반드시 변경하세요! 기본값(admin@example.com, changeme123!)을 사용하면 보안 위험이 있습니다.

포트 할당 가이드​

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

상세 규칙: 포트 할당표

4단계: 설치 및 실행​

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

# 루트 폴더로 이동 (중요!)
cd ../..

# 초기 설치 (의존성 설치, 키 생성, DB 마이그레이션)
make install NAME=myproject

# 컨테이너 시작
make up NAME=myproject

설치 과정에서 일어나는 일​

make install NAME=myproject
    │
    ├── Docker 이미지 빌드
    ├── Composer 의존성 설치
    ├── APP_KEY 자동 생성
    ├── 데이터베이스 마이그레이션
    ├── 초기 데이터 시딩 (Platform Admin 계정 생성)
    └── 완료!

make up NAME=myproject
    │
    ├── 권한 체크 (자동 수정 또는 안내)
    ├── 데이터 폴더 생성 (data/projects/myproject/)
    └── Docker Compose 실행

실행 상태 확인​

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

출력 예시:

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

5단계: 접속​

브라우저에서 다음 주소로 접속합니다:

패널URL설명
Platform Adminhttp://localhost:8110/platform플랫폼 관리자 패널
앱 홈http://localhost:8110메인 페이지

로그인 정보​

  • 이메일: .env에서 설정한 PLATFORM_ADMIN_EMAIL
  • 비밀번호: .env에서 설정한 PLATFORM_ADMIN_PASSWORD
예시:
이메일: admin@mycompany.com
비밀번호: MySecureP@ssw0rd!
성공!

Platform Admin 패널에 로그인할 수 있다면 Multi-SaaS Kit이 정상적으로 설치된 것입니다! 🎉

6단계: 다음 할 일​

로그인 후 다음 작업을 진행할 수 있습니다:

즉시 할 수 있는 것​

작업위치설명
비밀번호 변경프로필 메뉴첫 로그인 후 즉시 권장
SaaS 서비스 생성Platform Panel → SaaSLevel 1 관리자 추가
테넌트 생성SaaS Panel → Tenants고객사 추가
조직 구조 설정Tenant Panel → OrganizationsLevel 0~6 계층 구조 구성

개발 모드 활용​

# 로그 확인 (실시간)
make logs NAME=myproject

# 컨테이너 접속 (artisan 명령 등)
make shell NAME=myproject

# Laravel artisan 명령 예시 (컨테이너 내부에서)
php artisan migrate:status
php artisan tinker

자주 발생하는 문제​

포트 충돌​

# 에러 메시지
Error: Port 8110 is already in use

# 해결: 다른 포트로 변경
# .env 파일에서 APP_PORT=8120으로 변경 후 재시작
make restart NAME=myproject

권한 문제​

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

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

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

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

# 로그 확인
make logs NAME=myproject

# 전체 재시작
make down NAME=myproject
make up NAME=myproject

DB 연결 실패​

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

유용한 명령어​

명령어설명
make up NAME=x프로젝트 시작
make down NAME=x프로젝트 중지
make restart NAME=x재시작
make status NAME=x상태 확인
make logs NAME=x로그 확인
make shell NAME=x컨테이너 접속
make migrate NAME=xDB 마이그레이션
make help전체 명령어 목록

다음 단계​

기본 설치를 완료했습니다. 이제 더 깊이 있는 내용을 학습하세요:

필수 읽기​

핵심 개념 이해​

개발 가이드​

도움이 필요하신가요?