PostGIS & pgRouting 로컬 환경 구축기

프로젝트: no1delivery 백엔드 팀 프로젝트

---

1. Docker, 뭘 설치해야 할까?

Windows 노트북에서 Docker를 처음 접하면 "Linux용 Docker를 설치해야 하나?" 하는 의문이 생긴다.
결론부터 말하면 Docker Desktop for Windows를 설치하면 된다.

💡 Docker Desktop은 내부적으로 WSL2(Windows Subsystem for Linux 2)를 사용해 Linux 컨테이너를 실행한다.
"Desktop"은 서버용과 구분되는 개인 PC/노트북용 버전을 의미할 뿐이다.

# Docker 설치 확인
docker version
# → Docker version 29.2.0, build 0b9d198

---

2. pgrouting 컨테이너 실행

프로젝트 가이드에 따라 docker/pgrouting/ 경로로 이동 후 컨테이너를 실행했다.
--env-file ../../.env 옵션은 두 단계 위 폴더의 .env 파일을 참조한다.

# docker/pgrouting/ 경로로 이동
cd C:\Users\한소연\Desktop\백엔드\sparta\no1delivery\docker\pgrouting

# 컨테이너 실행
docker compose --env-file ../../.env up -d

트러블슈팅 — .env 파일 없음

couldn't find env file: C:\Users\...\백엔드\.env

docker-compose.yml을 확인하니 DB_NAME, DB_USERNAME, DB_PASSWORD 세 가지가 모두 필요했다.
sparta/ 폴더 아래 .env 파일을 만들어 세 값을 채워 넣었다.

DB_NAME=no1delivery
DB_USERNAME=postgres
DB_PASSWORD=******
DB_URL=jdbc:postgresql://localhost:5432/no1delivery

컨테이너가 정상 실행되면 아래처럼 출력된다.

✔ Image pgrouting/pgrouting:15-3.3-3.4.1  Pulled
✔ Network pgrouting_no1-delivery-network   Created
✔ Volume  pgrouting_no1_delivery_db        Created
✔ Container pgrouting                      Created

---

3. PostGIS & pgRouting 활성화

컨테이너 실행 후 psql에 접속해 익스텐션을 활성화했다.

-- 1. 컨테이너 psql 접속
docker exec -it pgrouting psql -U postgres

-- 2. DB 연결
\c no1delivery

-- 3. 익스텐션 활성화
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS pgrouting;

두 명령 모두 CREATE EXTENSION으로 응답 — 활성화 완료. ✅

---

4. 서버 실행 중 만난 에러들

PostGIS 설정 후 ./gradlew bootRun을 실행하자 세 가지 에러가 순서대로 터졌다.

ERROR 1 — ReviewerCheck 클래스 없음

cannot find symbol: class ReviewerCheck

원인: 브랜치에서 아직 merge되지 않은 클래스.
해결: dev 브랜치 최신화 후 해결.

---

ERROR 2 — JWT 환경변수 불일치

Illegal base64 character: '_'
Could not resolve placeholder 'TOSS_SECRET_KEY'

원인: application.yml은 ${JSON_WEB_TOKEN_SECRET}을 참조하는데 .env에는 JWT_SECRET_KEY로 잘못 등록되어 있었다.
해결: 변수명을 맞추고 Base64 인코딩된 값으로 교체.

# Base64 키 생성
[Convert]::ToBase64String(
  [System.Text.Encoding]::UTF8.GetBytes("mysupersecretkey1234567890abcdef")
)
# → bm8xZGVsaXZlcnlzdXBlcnNlY3JldGtleTEyMzQ1Njc=

JSON_WEB_TOKEN_SECRET=bm8xZGVsaXZlcnlzdXBlcnNlY3JldGtleTEyMzQ1Njc=

---

5. Git 작업 흐름

오늘 작업 중 Git에서 자주 마주쳤던 상황을 정리했다.

⚠️ 브랜치 이동 실패
커밋하지 않은 변경 파일이 있으면 git switch가 막힌다.
항상 add → commit → 브랜치 이동 순서를 지킬 것.

# 변경사항 커밋 후 브랜치 이동
git add .
git commit -m "fix: ReviewOrderInfo, ReviewOrderItem 수정"
git switch dev

# 또는 임시 저장(stash) 후 이동
git stash
git switch dev

# PR용 push
git push origin feature/review

💡 충돌 없이 merge가 완료되면 커밋 메시지 작성 창이 뜬다.
vim이면 :wq, IntelliJ면 창 닫기로 완료.

---

6. 마무리 — 서버 정상 기동 확인

모든 트러블슈팅을 마치고 최종적으로 서버가 정상 기동됐다.

Tomcat started on port 8080 (http)
Started No1deliveryApplication in 6.297 seconds

💡 ./gradlew bootRun 실행 후 시간 카운터가 올라가는 것은 서버가 계속 실행 중이라는 정상 상태다. 종료하려면 Ctrl + C.

Docker 설치 의문에서 시작해 PostGIS 활성화, 환경변수 트러블슈팅까지 — 환경 구축은 언제나 예상보다 많은 시간이 걸린다. 하지만 하나씩 에러를 잡아나가며 서버가 뜨는 순간의 쾌감은 언제나 그만한 가치가 있다.
오늘도 한 단계 성장했다!🚀