본문으로 건너뛰기

Makefile 개요

Multi-SaaS Kit의 Makefile 기반 자동화 시스템을 소개합니다.

핵심 원칙​

원칙설명
단일 진입점모든 인프라 작업은 make <command> NAME=project 형식
자동 감지개발/운영 모드, 아키텍처, 권한 문제 자동 감지
자동 해결sudo 권한 있으면 자동 수정, 없으면 안내 표시
멱등성반복 실행해도 안전 (이미 실행 중이면 skip)
# 기본 사용법
make up NAME=myproject        # 프로젝트 시작
make down NAME=myproject      # 프로젝트 중지
make logs NAME=myproject      # 로그 확인

# 도움말
make help                     # 전체 명령어 목록
make process                  # 운영 프로세스 가이드

16개 모듈 구조​

Multi-SaaS Kit의 Makefile은 16개의 .mk 파일로 모듈화되어 있습니다.

ops/makefile/
├── _common.mk      # 공통 변수, 매크로, 색상 정의
├── _help.mk        # help, process 메뉴
├── docker.mk       # up, down, restart, status, logs
├── shell.mk        # shell, shell-db, shell-redis
├── database.mk     # migrate, seed, fresh
├── build.mk        # create, install, copy-env, setup
├── deploy.mk       # live, release, deploy, rollback
├── backup.mk       # backup, restore, backup-list
├── secrets.mk      # encrypt, decrypt (GPG)
├── utils.mk        # health, artisan, cache-clear, tinker, queue
├── test.mk         # test, lint
├── cleanup.mk      # clean, reset
├── permissions.mk  # 권한 체크 및 자동 수정
├── info.mk         # list, ports, status
├── claude.mk       # Claude Code 연동
└── tmux.mk         # tmux 메모 표시

모듈별 역할​

카테고리모듈주요 명령어설명
기반_common.mk-공통 변수, 매크로 정의
_help.mkhelp, process도움말 및 가이드 출력
Dockerdocker.mkup, down, restart, logs컨테이너 생명주기 관리
shell.mkshell, shell-db컨테이너 접속
데이터database.mkmigrate, seed, freshDB 마이그레이션
backup.mkbackup, restore백업/복원
빌드build.mkcreate, install프로젝트 생성/설치
배포deploy.mklive, release, rollback릴리즈/배포
보안secrets.mkencrypt, decryptGPG 암호화
permissions.mk-권한 자동 수정
유틸utils.mkartisan, tinker, queueLaravel 유틸리티
test.mktest, lint테스트 실행
info.mklist, ports정보 조회
cleanup.mkclean, reset정리

핵심 변수​

Makefile에서 사용하는 주요 변수입니다.

변수설명예시 값
NAME프로젝트 이름 (필수)myproject, _portal
SUB특정 서비스만 실행 (선택)portal-docs
ARCH자동 감지된 아키텍처amd64, arm64
PLATFORM_NAME플랫폼 이름 (.env에서 로드)msk (기본값, 소문자 권장)

자동 감지 변수​

# 아키텍처 자동 감지 (x86_64 → amd64, aarch64 → arm64)
ARCH := $(shell uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')

# 플랫폼 이름 (.env에서 로드, 없으면 기본값 msk)
PLATFORM_NAME := $(shell grep -E '^PLATFORM_NAME=' .env | cut -d= -f2)

개발 모드 vs 운영 모드​

Makefile은 live/ 심볼릭 링크 존재 여부로 모드를 자동 판별합니다.

live/{project} 심볼릭 링크 존재?
├── 없음 → 개발 모드 (workspace/ 직접 사용)
└── 있음 → 운영 모드 (releases/ 스냅샷 사용)

개발 모드​

# workspace에서 직접 실행
make up NAME=myproject

# 코드 수정 후 재시작만 하면 즉시 반영
make restart NAME=myproject

운영 모드​

# 1. 릴리즈 생성 + live 심볼릭 링크 설정
make live NAME=myproject

# 2. live에서 실행
make up NAME=myproject

# 코드 변경 후
make live NAME=myproject      # 새 릴리즈 생성
make restart NAME=myproject   # 재시작

# 롤백
make rollback NAME=myproject

NAME 파라미터 필수​

대부분의 명령어는 NAME 파라미터가 필수입니다.

# ✅ 올바른 사용
make up NAME=myproject
make migrate NAME=_portal

# ❌ NAME 없이 실행 시 에러
make up
# 결과: ❌ NAME is required
#       Usage: make up NAME=<project>

이 설계는 실수 방지를 위한 것입니다. NAME 없이 실행하면 어떤 프로젝트도 영향받지 않습니다.

SUB 파라미터 (서비스 필터)​

_portal처럼 여러 서비스가 있는 프로젝트에서 특정 서비스만 실행할 때 사용합니다.

# _portal 전체 시작
make up NAME=_portal

# docs 서비스만 시작
make up NAME=_portal SUB=portal-docs

# 특정 서비스만 재시작
make restart NAME=_portal SUB=portal-web

프로젝트 디렉토리 결정​

Makefile은 다음 순서로 프로젝트 경로를 결정합니다:

# 1. live/{project} 존재 여부 확인
# 2. 있으면 live/ 사용, 없으면 workspace/ 사용
get_project_dir = $(if $(wildcard $(LIVE_DIR)/$(1)),\
    $(LIVE_DIR)/$(1),\
    $(WORKSPACE_DIR)/$(1))
조건사용 경로
live/myproject 존재live/myproject → releases/myproject/{timestamp}
live/myproject 없음workspace/myproject

관련 문서​