[Fix] 새 PC에서 README 빠른 실행이 MinIO 이미지와 JWT_SECRET 누락으로 멈추는 문제

[Gimini-3]

🔍️ 작업 내용

• Closes [Fix] 새 PC에서 README 빠른 실행이 MinIO 이미지 수급 실패로 멈추는 문제 #502

README 「빠른 실행」을 새 PC에서 그대로 따라 하면 두 곳에서 멈추던 문제를 고칩니다. 애플리케이션 코드와 Spring 설정은 바꾸지 않고 .env.example, docker-compose.yml, README만 바꿉니다.

• 3단계: 공식 minio/minio 이미지를 새로 받을 수 없어 docker compose up이 pull access denied로 실패
• 5단계: jwt.secret: ${JWT_SECRET}은 기본값이 없는데 .env.example·README에 없어 bootRun이 Context 초기화에 실패

✨ 상세 설명

MinIO를 기본 실행 경로에서 분리

• .env.example: STORAGE_TYPE=minio → STORAGE_TYPE=local. 앱 기본값(${STORAGE_TYPE:local})과 같고, MinIO Adapter·Client는 STORAGE_TYPE=minio일 때만 생성됩니다.
• docker-compose.yml: minio 서비스에 profiles: ["minio"]. 서비스는 남겨 두어 이미지를 가진 환경은 docker compose --profile minio up -d minio로 계속 씁니다. 명령줄에서 minio를 직접 지정하는 「테스트」의 E2E 명령도 Profile이 자동 활성화되어 그대로 동작합니다.
• README: 3단계 명령·제목, MinIO Health Check, 종료 명령에서 minio를 빼고, 개요·기술 스택·환경 선택 표의 "MinIO 기본" 설명을 Local Filesystem 기본, 선택형 MinIO로 고쳤습니다. 라이선스 표 MinIO 행에 2026-10-15 확인 결과(Docker Hub 저장소 API 404)를 반영했습니다.

JWT_SECRET 생성 단계 추가

• README 2단계에 echo "JWT_SECRET=$(openssl rand -base64 32)" >> .env를 추가했습니다. 서명 키를 저장소에 두지 않고 각자 생성합니다. JwtProvider가 요구하는 32바이트 이상(44자)을 만족합니다.
• .env.example에는 값 없이 생성 방법만 주석으로 안내합니다.

새 PC 재현 검증

• 기존 Docker 이미지·볼륨·Cache를 쓰지 않도록 Lima VM의 빈 Docker 데몬과 빈 npm·Gradle Cache에서, 별도 디렉터리에 새로 클론해 README 명령을 그대로 실행했습니다.
• 수정 전 develop: 3단계가 3초 만에 pull access denied for minio/minio로 실패하고 컨테이너가 하나도 생성되지 않았습니다.
• 수정 후: 회원가입 → PDF 업로드 → INDEXED(Embedding Job 10초) → AI 검색(근거 유사도 81.1%) → RAG 답변 SUCCESS(qwen2.5:7b, 100% GPU, 13.5초) → 종료 명령까지 성공했습니다.
• 단계별 소요 시간(약 2MB/s 회선): compose up 7분 7초, BGE-M3 준비까지 42분 31초, ollama pull 약 60분(DNS 실패 1회 후 이어받기), 빈 Gradle Cache bootRun 3분 19초. 상세 표는 설계 문서에 있습니다.

🛠️ 추후 리팩토링 및 고도화 계획

• RAG 답변이 문장 중간에서 잘리고 "답변이 길어 일부 내용이 생략됐을 수 있습니다" 안내가 붙는 현상을 관찰했습니다(출력 291 Token, num-predict 400 미만). 별도 작업으로 조사합니다.
• README 2단계의 "인덱싱 Worker는 기본값으로 꺼져 있습니다" 문구가 application-local.yml의 기본값 true와 맞지 않습니다.
• embedding-server는 모델을 받는 동안 진행 로그가 없고 start_period 900초 뒤 unhealthy로 표시됩니다.
• MinIO 대상 개발용 E2E(storageWorkerE2eTest 등)는 새 PC에서 여전히 minio Pull에서 실패합니다.

💬 리뷰 요구사항

• #454에서 "팀 협의 후 별도 이슈"로 남긴 기본 경로 분리입니다. MinIO를 쓰는 로컬 환경은 기존 .env가 그대로라 영향이 없지만, Profile 방식이 팀 개발 흐름에 맞는지 봐 주세요.
• JWT_SECRET을 .env.example 고정값 대신 생성 명령으로 둔 판단을 봐 주세요. Windows PowerShell에는 openssl이 기본으로 없습니다(Git Bash에는 있음).

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Repository: DocGrid/docgrid/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 566a74f3-96ff-4ce3-8de8-663b05a792d1

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}