주요 명령어
자주 사용하는 Makefile 명령어를 카테고리별로 설명합니다.
명령어 구조
모든 명령어는 다음 형식을 따릅니다:
make <command> NAME=<project> [OPTIONS]
| 요소 | 설명 | 예시 |
|---|---|---|
command | 실행할 작업 | up, down, migrate |
NAME | 대상 프로젝트 (필수) | myproject, _portal |
OPTIONS | 추가 옵션 (선택) | SUB=service, BACKUP=filename |
플랫폼 명령어 (NAME 불필요)
프로젝트와 무관하게 실행하는 명령어입니다.
make help # 전체 명령어 도움말
make process # 운영 프로세스 가이드
make list # 등록된 프로젝트 목록
make ports # 포트 할당 현황
make check-prereq # 선행 조건 검사 (Docker, Git 등)
make setup # 플랫폼 초기 설정
컨테이너 관리 (docker.mk)
기본 명령어
make up NAME=myproject # 컨테이너 시작
make down NAME=myproject # 컨테이너 중지
make restart NAME=myproject # 재시작
make status NAME=myproject # 상태 확인
특정 서비스만 실행 (SUB 옵션)
_portal처럼 여러 서비스가 있는 프로젝트에서 사용합니다.
make up NAME=_portal SUB=portal-docs # docs 서비스만 시작
make restart NAME=_portal SUB=portal-web # web 서비스만 재시작
make down NAME=_portal SUB=portal-store # store 서비스만 중지
로그 확인
make logs NAME=myproject # 전체 로그 (실시간)
make logs-app NAME=myproject # 앱(web) 로그
make logs-db NAME=myproject # PostgreSQL 로그
make logs-redis NAME=myproject # Redis 로그
개발 도구 (shell.mk)
컨테이너 접속
make shell NAME=myproject # 앱 컨테이너 bash
make shell-db NAME=myproject # PostgreSQL psql
쉘 내부 작업 예시
# 앱 쉘에서
make shell NAME=myproject
> php artisan tinker
> composer require package/name
# DB 쉘에 서
make shell-db NAME=myproject
> \dt # 테이블 목록
> SELECT * FROM users; # 쿼리 실행
데이터베이스 (database.mk)
마이그레이션
make migrate NAME=myproject # 마이그레이션 실행
make seed NAME=myproject # 시더 실행
make fresh NAME=myproject # DB 초기화 (drop + migrate + seed)
fresh 명령어 주의
make fresh는 모든 데이터를 삭제합니다. 운영 환경에서는 절대 사용하지 마세요.
안전한 마이그레이션
# 1. 백업 먼저
make backup NAME=myproject
# 2. 마이그레이션
make migrate NAME=myproject
# 3. 문제 시 롤백
make rollback NAME=myproject
빌드 및 설치 (build.mk)
새 프로젝트 생성
# 1. 템플릿 복사
make create NAME=newproject
# 2. 환경변수 설정
vi workspace/newproject/.env
# 3. 초기 설치 (build + up + migrate + seed)
make install NAME=newproject
개별 빌드
make build NAME=myproject # Docker 이미지 빌드
make copy-env NAME=myproject # .env.example → .env 복사
make setup NAME=myproject # Composer, npm 설치 + 빌드
경로 난독화
make route-obfuscate NAME=myproject # Laravel 라우트 경로 난독화
배포 (deploy.mk)
릴리즈 생성
make release NAME=myproject # 새 릴리즈 스냅샷 생성
make release-list NAME=myproject # 릴리즈 목록 확인
운영 모드 전환
make live NAME=myproject # 릴리즈 + live 심볼릭 링크 설정
make live NAME=myproject DATETIME=250110-1430 # 특정 버전으로 전환
배포 및 롤백
make deploy NAME=myproject # 릴리즈 → live 적용 + restart
make rollback NAME=myproject # 이전 릴리즈로 롤백
배포 검증
make verify-deployment NAME=myproject # APP_URL, Vite, 경로 확인
백업 및 복원 (backup.mk)
백업 생성
make backup NAME=myproject # PostgreSQL + Redis + uploads 백업
make backup-list NAME=myproject # 백업 목록
make backup-info NAME=myproject BACKUP=250110-1430 # 백업 상세 정보
복원
make restore NAME=myproject BACKUP=250110-1430 # 특정 백업 복원
.env 복원
백업 복원 시 .env는 .env.restored로 생성됩니다. 수동 확인 후 적용하세요.
민감 정보 (secrets.mk)
암호화
make encrypt NAME=myproject # 프로젝트 .env 암호화 (GPG)
make encrypt NAME=_root # 루트 .env 암호화
복호화
make decrypt NAME=myproject # .env.decrypt 파일 생성
make decrypt-all # 모든 암호화 파일 복호화
make secrets-restore # 암호화된 모든 시크릿 복원
현황 확인
make secrets-list # 암호화된 파일 목록
make secrets-scan # 민감 파일 전체 스캔
make secrets-scan NAME=myproject # 프로젝트별 스캔
유틸리티 (utils.mk)
Laravel Artisan
make artisan NAME=myproject CMD="migrate:status" # Artisan 명령 실행
make tinker NAME=myproject # Laravel Tinker (REPL)
make cache-clear NAME=myproject # 캐시 정리
make queue NAME=myproject # Queue 상태 확인
헬스체크
make health NAME=myproject # 서비스 헬스체크
테스트 (test.mk)
make test NAME=myproject # 테스트 실행 (SQLite in-memory)
make lint NAME=myproject # 코드 스타일 검사 (PHP CS Fixer)
테스트 안전성
make test는 SQLite in-memory를 강제 사용하므로 운영 DB에 영향 없습니다.
정리 (cleanup.mk)
make clean NAME=myproject # 컨테이너/이미지 정리
make clean-data NAME=myproject # 데이터 삭제 (postgres, redis)
make reset NAME=myproject # 완전 초기화 (clean + clean-data)
reset 명령어
make reset은 모든 데이터를 영구 삭제합니다. 복구 불가능합니다.
정보 조회 (info.mk)
make list # 프로젝트 목록
make ports # 포트 할당 현황
make status NAME=myproject # 프로젝트 상태
호스트 튜닝 / 자원 제한 (system.mk)
저 사양 호스트에서 multi-saas-kit + 모니터링 + 다수 컨테이너를 동시에 운영할 때, 호스트 커널 sysctl 튜닝과 AI 에이전트(claude/codex) cgroup 격리를 한 번에 다루는 모듈입니다.
# 호스트 sysctl 튜닝 적용 (sudo 1회 필요)
make tune-system
# 적용된 sysctl + 메모리/swap/load + ai-agents.slice 트리 한눈에 보기
make resource-status
# resource-limits.json 의 현재 한도 표시 (실행은 안 함)
make resource-limits-show
# 튜닝 원복
make untune-system
| 명령어 | 설명 | sudo 필요 |
|---|---|---|
make tune-system | .ai-core/config/sysctl-ai-tuning.conf → /etc/sysctl.d/99-ai-tuning.conf 설치 + sysctl --system | ✅ |
make untune-system | 위 파일 제거 + 재로드 (기본값 복원) | ✅ |
make resource-status | sysctl, free -h, /proc/swaps, load average, ai-agents.slice cgroup 트리 표시 | ❌ |
make resource-limits-show | .ai-core/config/resource-limits.json 의 현재 적용값 표시 | ❌ |
AI 에이전트 자원 격리
make claude / make codex 실행 시 자동으로 systemd-run cgroup scope (ai-agents.slice) 안에서 실행됩니다. CPU/메모리 한도 초과 시 해당 scope만 제한·종료되며, 호스트 전체에는 영향이 없습니다.
한도는 .ai-core/config/resource-limits.json에서 조정 가능 (도구별 override 지원). 자세한 내용은 .ai-core/docs/resource-management.md 참조.
튜닝이 필요한 신호
make resource-status의 swap used가 RAM의 20% 이상- load average가 CPU 코어 수에 근접/초과
- tmux/sshd 입력 지연
이런 증상이 보이면 make tune-system 먼저 적용해 보세요. 자세한 진단 가이드는 서버 관리 / 운영 시나리오에 있습니다.
권한 관리 (permissions.mk)
make check-pgadmin-permissions # pgAdmin 폴더 권한 확인
make check-laravel-permissions NAME=myproject # Laravel 폴더 권한
자동 권한 수정
권한 문제 발생 시 Makefile이 sudo로 자동 수정을 시도합니다. 실패하면 안내 메시지가 표시됩니다.
명령어 요약 표
일상 개발 (매일 사용)
| 명령어 | 설명 |
|---|---|
make up NAME=... | 시작 |
make down NAME=... | 중지 |
make logs NAME=... | 로그 |
make shell NAME=... | 쉘 접속 |
make migrate NAME=... | 마이그레이션 |
make test NAME=... | 테스트 |
배포 (배포 시 사용)
| 명령어 | 설명 |
|---|---|
make backup NAME=... | 백업 |
make live NAME=... | 릴리즈 + 운영 전환 |
make rollback NAME=... | 롤백 |
make verify-deployment NAME=... | 검증 |
관리 (필요 시 사용)
| 명령어 | 설명 |
|---|---|
make encrypt NAME=... | 암호화 |
make secrets-restore | 시크릿 복원 |
make clean NAME=... | 정리 |
호스트 튜닝 (저사양 서버 운영 시)
| 명령어 | 설명 |
|---|---|
make tune-system | sysctl 튜닝 적용 (sudo 1회) |
make resource-status | swap/메모리/load + AI agent cgroup 상태 |
make resource-limits-show | AI 에이전트 자원 한도 표시 |
make untune-system | sysctl 튜닝 원복 |