빠른 시작

​

전제 조건

​

개발 환경 실행

• PostgreSQL - 데이터베이스
• API 서버 - 백엔드 REST API (Sonamu UI 포함)
• Web 서버 - 프론트엔드 애플리케이션

1

데이터베이스 시작

프로젝트의 api 디렉토리로 이동하여 PostgreSQL 컨테이너를 시작합니다:

복사

cd my_app/api
pnpm docker:up

docker:up 실행 후 성공 메시지 및 컨테이너 시작 로그

이 명령어는 Docker Compose를 사용하여 PostgreSQL 데이터베이스를 백그라운드에서 실행합니다.

데이터베이스가 정상적으로 실행되었는지 확인하려면 docker ps 명령어로 컨테이너 상태를 확인할 수 있습니다.

docker ps 실행 결과 (PostgreSQL 컨테이너가 Up 상태)

2

API 서버 실행

같은 api 디렉토리에서 개발 서버를 시작합니다:

복사

pnpm dev

pnpm dev 실행 후 서버 시작 로그

서버가 성공적으로 시작되면 다음과 같은 메시지가 표시됩니다:

복사

🌲 Server listening on http://localhost:1028

이 명령어 하나로 다음이 모두 실행됩니다:

• Web 앱: http://localhost:1028
• API 엔드포인트: http://localhost:1028/api
• Sonamu UI: http://localhost:1028/sonamu-ui

API 서버는 Hot Module Replacement(HMR)을 지원하므로 코드 변경 시 자동으로 재시작됩니다.

로컬 개발 환경에서는 API 서버가 Web 앱까지 통합하여 제공합니다. Web 디렉토리의 Vite Dev Server를 API 서버에 middleware로 연결하여 하나의 포트로 모든 것을 실행할 수 있습니다.

이 터미널 창은 계속 열어두어야 합니다. API 서버가 실행 중인 상태를 유지합니다.

3

Web 서버 실행 (선택사항)

Web 개발에 집중하거나 Vite의 전체 기능을 활용하고 싶다면, 새 터미널 창을 열고 web 디렉토리에서 별도로 개발 서버를 시작할 수 있습니다:

복사

cd my_app/web
pnpm dev

web 디렉토리에서 pnpm dev 실행 후 Vite 시작 로그

Vite 개발 서버가 시작되면 다음과 같은 메시지가 표시됩니다:

복사

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:3028/
  ➜  Network: http://192.168.x.x:3028/

Web 서버를 별도로 실행하면 http://localhost:3028 로 접속하여 프론트엔드를 확인할 수 있습니다. Web 서버는 /api/* 경로 요청을 자동으로 API 서버(localhost:1028)로 프록시합니다.

두 가지 개발 방식

• 통합 모드 (권장): API 서버만 실행 → localhost:1028로 모든 것에 접근
• 분리 모드: API + Web 별도 실행 → API는 localhost:1028, Web은 localhost:3028

대부분의 경우 통합 모드로 충분하며, Web 개발에 집중할 때만 분리 모드를 사용하세요.

​

접속 확인

​

통합 모드 (API 서버만 실행한 경우)

​

분리 모드 (API + Web 서버 모두 실행한 경우)

​

Sonamu UI 기능

• 엔티티 생성 및 편집
• 데이터베이스 마이그레이션 관리
• API 엔드포인트 확인
• 데이터베이스 스키마 시각화

​

서버 중지

1. API 서버 (그리고 Web 서버가 실행 중이라면): 각 터미널에서 Ctrl + C 키를 눌러 중지합니다.
2. 데이터베이스: api 디렉토리에서 다음 명령어를 실행합니다:

pnpm docker:down

​

다음 단계