본문으로 건너뛰기

문제 해결

Makefile 실행 중 발생할 수 있는 문제와 해결 방법입니다.

NAME 필수 에러​

증상​

❌ NAME is required
Usage: make up NAME=<project>

Available projects:
  _portal
  _template
  myproject

원인​

프로젝트 명령어에 NAME 파라미터가 누락되었습니다.

해결​

# ❌ 잘못된 사용
make up

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

프로젝트를 찾을 수 없음​

증상​

❌ Project 'unknown' not found in workspace/

원인​

지정한 프로젝트가 workspace/ 폴더에 없습니다.

해결​

# 1. 사용 가능한 프로젝트 확인
make list

# 2. 올바른 프로젝트 이름 사용
make up NAME=myproject

# 3. 새 프로젝트 생성
make create NAME=newproject

.env 파일 없음​

증상​

❌ .env file not found: workspace/myproject/.env
Run: make copy-env NAME=myproject

원인​

환경변수 파일이 생성되지 않았습니다.

해결​

# .env 파일 생성
make copy-env NAME=myproject

# .env 편집
vi workspace/myproject/.env

포트 충돌​

증상​

Error response from daemon: Ports are not available:
  exposing port TCP 0.0.0.0:8080 -> 0.0.0.0:0

원인​

다른 프로세스가 해당 포트를 사용 중입니다.

해결​

# 1. 사용 중인 포트 확인
make ports
lsof -i :8080

# 2. .env에서 포트 변경
vi workspace/myproject/.env
# APP_PORT=8081

# 3. 컨테이너 재시작
make down NAME=myproject
make up NAME=myproject

Docker 소켓 권한 오류​

증상​

permission denied while trying to connect to the Docker daemon socket

원인​

현재 사용자가 Docker 그룹에 속하지 않습니다.

해결​

# 1. Docker 그룹에 사용자 추가
sudo usermod -aG docker $USER

# 2. 로그아웃 후 다시 로그인 (또는 재부팅)
# 또는 새 터미널에서:
newgrp docker

# 3. 확인
docker ps

pgAdmin 권한 오류​

증상​

pgAdmin 폴더 권한 문제
UID 5050으로 실행되어야 합니다.

원인​

pgAdmin 컨테이너는 UID 5050으로 실행되지만, 데이터 폴더의 소유자가 다릅니다.

해결​

# Makefile이 안내하는 명령 실행
sudo chown -R 5050:5050 data/platform/pgadmin

# 다시 시작
make platform-up
자동 수정 시도

Makefile은 sudo 권한이 있으면 자동으로 수정을 시도합니다. 실패 시 안내 메시지가 표시됩니다.

Laravel 권한 오류​

증상​

The stream or file ".../storage/logs/laravel.log" could not be opened
Permission denied

원인​

storage/ 또는 bootstrap/cache/ 폴더의 쓰기 권한이 없습니다.

해결​

# 권한 수정
make check-laravel-permissions NAME=myproject

# 또는 수동으로
chmod -R 775 workspace/myproject/web/storage
chmod -R 775 workspace/myproject/web/bootstrap/cache

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

진단​

# 1. 상태 확인
make status NAME=myproject

# 2. 로그 확인
make logs NAME=myproject

# 3. 특정 서비스 로그
make logs-app NAME=myproject
make logs-db NAME=myproject

일반적인 원인​

원인해결
포트 충돌.env에서 포트 변경
이미지 없음make build NAME=myproject
.env 오류make copy-env NAME=myproject
Docker 미실행Docker Desktop 시작

DB 연결 실패​

증상​

SQLSTATE[08006] Connection refused
Could not connect to host: postgres

진단​

# 1. DB 컨테이너 상태
docker ps | grep postgres

# 2. DB 로그
make logs-db NAME=myproject

# 3. 연결 테스트
make shell-db NAME=myproject

해결​

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

# DB 초기화 (데이터 손실 주의!)
make fresh NAME=myproject

마이그레이션 오류​

증상​

Migration table not found
Nothing to migrate

해결​

# 마이그레이션 상태 확인
make artisan NAME=myproject CMD="migrate:status"

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

# 캐시 정리 후 재시도
make cache-clear NAME=myproject
make migrate NAME=myproject

빌드 실패​

증상​

error during build: failed to build

해결​

# 1. Docker 캐시 정리 후 재빌드
docker system prune -f
make build NAME=myproject

# 2. Dockerfile 오류 확인
cat workspace/myproject/_docker/conf/php/Dockerfile

테스트 실패​

증상​

Tests\Unit\...Test > test_something
Failed asserting that...

진단​

# 특정 테스트만 실행
make artisan NAME=myproject CMD="test --filter=test_something"

# 자세한 출력
make artisan NAME=myproject CMD="test -v"
SQLite 사용

make test는 SQLite in-memory를 사용합니다. 운영 DB와 무관하게 안전합니다.

선행 조건 검사​

문제가 지속되면 선행 조건을 검사하세요:

make check-prereq

검사 항목:

  • Docker 설치 및 실행 상태
  • Docker Compose 버전
  • Git 설치
  • 필수 폴더 존재

도움 요청​

위 방법으로 해결되지 않으면:

  1. make logs NAME=myproject로 전체 로그 수집
  2. make status NAME=myproject로 상태 확인
  3. GitHub Issues에 로그와 함께 문의

관련 문서​