본문으로 건너뛰기

첫 프로젝트 생성

📝 초안 (Draft)

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

Multi-SaaS Kit으로 첫 번째 SaaS 프로젝트를 생성하고 실행하는 튜토리얼입니다.

개요​

이 가이드를 완료하면:

  • 새 SaaS 프로젝트를 생성할 수 있습니다
  • 환경 설정(.env)을 이해하고 구성할 수 있습니다
  • 관리자 패널에 로그인하여 시스템을 확인할 수 있습니다

예상 소요 시간: 15-20분

사전 준비​

다음 사항을 확인하세요:

# 저장소 클론 (아직 안 했다면)
git clone https://github.com/your-org/multi-saas-kit.git
cd multi-saas-kit

Step 1: 프로젝트 생성​

make create 명령​

루트 디렉토리에서 make create 명령으로 새 프로젝트를 생성합니다.

# 새 프로젝트 생성
make create NAME=myapp

이 명령은 다음을 수행합니다:

  1. _template을 workspace/myapp으로 복사
  2. .env.example을 .env로 복사
  3. 보안 값 자동 생성 (DB 비밀번호, 관리자 비밀번호, 경로 난독화)

성공 시 출력​

🆕 Creating project: myapp
════════════════════════════════════════

➤ Copying template...
✅ Template copied

📋 Creating .env for myapp...
════════════════════════════════════════

✅ Route obfuscation: impersonate-7f3a
✅ .env created with secure random values

╔══════════════════════════════════════════════════════════════╗
║ ✅ Project 'myapp' created successfully!                      ║
╠══════════════════════════════════════════════════════════════╣
║ Next steps:                                                   ║
║   1. vi workspace/myapp/.env   # 설정 편집                    ║
║   2. make up NAME=myapp        # 시작                         ║
╚══════════════════════════════════════════════════════════════╝
프로젝트 이름 규칙
  • 언더스코어(_)로 시작하는 이름은 사용할 수 없습니다
  • 영문 소문자, 숫자, 하이픈만 사용을 권장합니다
  • 예: myapp, client-portal, shop2024

Step 2: 환경 설정 (.env)​

프로젝트 생성 후 .env 파일을 편집합니다.

vi workspace/myapp/.env

필수 변경 항목​

항목기본값변경 필요설명
PROJECT_NAMEmyapp✅ 자동 설정프로젝트명 (생성 시 자동)
APP_PORT8180✅ 확인 필요웹 서비스 포트
DB_PORT5433✅ 확인 필요PostgreSQL 포트
REDIS_PORT6380✅ 확인 필요Redis 포트
PLATFORM_ADMIN_EMAILadmin@example.com✅ 변경 필수관리자 이메일

자동 생성 항목 (변경 불필요)​

항목설명
DB_PASSWORD32자 랜덤 비밀번호
PLATFORM_ADMIN_PASSWORD24자 랜덤 비밀번호
ROUTE_IMPERSONATE경로 난독화 (예: impersonate-7f3a)

포트 설정​

포트 충돌 주의

여러 프로젝트를 동시에 실행하려면 각 프로젝트마다 다른 포트를 사용해야 합니다.

포트 할당 규칙:

서비스포트 범위예시 (첫 번째 프로젝트)
HTTP (APP_PORT)8100-81998100
PostgreSQL (DB_PORT)5433-54495433
Redis (REDIS_PORT)6380-63996380
# .env 예시 (첫 번째 프로젝트)
APP_PORT=8100
DB_PORT=5433
REDIS_PORT=6380

관리자 계정 설정​

# 실제 관리자 이메일로 변경
PLATFORM_ADMIN_EMAIL=admin@yourcompany.com

# 비밀번호는 자동 생성됨 - 첫 로그인 후 변경 권장
# PLATFORM_ADMIN_PASSWORD=자동생성됨
비밀번호 확인

생성된 관리자 비밀번호를 확인하세요:

grep PLATFORM_ADMIN_PASSWORD workspace/myapp/.env

Step 3: 프로젝트 시작​

컨테이너 시작​

make up NAME=myapp

이 명령은 다음 컨테이너를 시작합니다:

  • nginx: 웹 서버 (리버스 프록시)
  • web: Laravel PHP 애플리케이션
  • postgres: PostgreSQL 데이터베이스
  • redis: Redis 캐시/세션/큐

상태 확인​

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

모든 컨테이너가 Up 상태인지 확인합니다.

         Name                    State              Ports
────────────────────────────────────────────────────────────
saas1-myapp-nginx             Up          0.0.0.0:8100->80/tcp
saas1-myapp-web               Up          9000/tcp
saas1-myapp-postgres          Up          0.0.0.0:5433->5432/tcp
saas1-myapp-redis             Up          0.0.0.0:6380->6379/tcp

Step 4: 초기 설정​

데이터베이스 마이그레이션​

# 마이그레이션 실행
make migrate NAME=myapp

# 초기 데이터 시드
make seed NAME=myapp

Laravel 앱 키 생성​

앱 키가 없는 경우 생성합니다:

make artisan NAME=myapp CMD="key:generate"

Step 5: 첫 로그인​

관리자 패널 접속​

브라우저에서 다음 URL을 엽니다:

http://localhost:8100/platform
패널 경로

기본 패널 경로는 /platform입니다. 이 경로는 .env의 PANEL_PATH_PLATFORM에서 변경할 수 있습니다.

로그인 정보​

항목값
이메일.env의 PLATFORM_ADMIN_EMAIL 값
비밀번호.env의 PLATFORM_ADMIN_PASSWORD 값
# 로그인 정보 확인
grep -E "PLATFORM_ADMIN_(EMAIL|PASSWORD)" workspace/myapp/.env

로그인 후 화면​

로그인 성공 시 Platform Admin 대시보드가 표시됩니다:

  • 사용자 관리: SaaS Admin, Tenant 관리
  • 시스템 설정: 플랫폼 전체 설정
  • 감사 로그: 시스템 활동 기록

트러블슈팅​

컨테이너가 시작되지 않는 경우​

# 로그 확인
make logs NAME=myapp

# 특정 서비스 로그
docker logs saas1-myapp-web

포트 충돌 오류​

# 사용 중인 포트 확인
lsof -i :8100
netstat -tlnp | grep 8100

# .env에서 다른 포트로 변경
APP_PORT=8101

데이터베이스 연결 오류​

# PostgreSQL 컨테이너 상태 확인
docker logs saas1-myapp-postgres

# 컨테이너 재시작
make restart NAME=myapp

권한 오류​

# storage 폴더 권한 설정
make shell NAME=myapp
# 컨테이너 내에서:
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
exit

마이그레이션 실패​

# PostgreSQL 연결 대기 후 재시도
sleep 10 && make migrate NAME=myapp

# 또는 컨테이너 상태 확인
make status NAME=myapp

다음 단계​

프로젝트가 정상적으로 실행되면 다음을 탐색하세요:

유용한 명령어​

명령어설명
make up NAME=myapp컨테이너 시작
make down NAME=myapp컨테이너 중지
make restart NAME=myapp컨테이너 재시작
make status NAME=myapp상태 확인
make logs NAME=myapp로그 보기
make shell NAME=myapp컨테이너 쉘 접속
make migrate NAME=myappDB 마이그레이션
make seed NAME=myapp시드 데이터

관련 문서​