메인 콘텐츠로 건너뛰기
이 가이드는 Sonamu 프로젝트를 설치한 후 개발 환경을 실행하는 방법을 단계별로 안내합니다.

​
전제 조건

설치하기 가이드를 완료하고 프로젝트가 생성되어 있어야 합니다.

​
개발 환경 실행

Sonamu 개발 환경은 다음 세 가지 서버로 구성됩니다:
  • 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 메시지 포함)

서버가 성공적으로 시작되면 다음과 같은 메시지가 표시됩니다:
🌲 Server listening on http://localhost:1028
이 명령어 하나로 다음이 모두 실행됩니다: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 시작 로그 (Local: http://localhost:3028 메시지 포함)

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 서버만 실행한 경우)

브라우저에서 다음 URL로 접속할 수 있습니다:
서비스URL설명
Web 앱http://localhost:1028프론트엔드 애플리케이션
API 서버http://localhost:1028/apiREST API 엔드포인트
Sonamu UIhttp://localhost:1028/sonamu-ui엔티티 관리 인터페이스

📸 필요: 브라우저에서 localhost:1028 접속한 화면 (기본 Web 앱 홈페이지)

📸 필요: 브라우저에서 localhost:1028/api 접속한 화면 (404 또는 API 응답)

📸 필요: 브라우저에서 localhost:1028/sonamu-ui 접속한 화면 (Sonamu UI 대시보드)

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

서비스URL설명
Web 앱http://localhost:3028프론트엔드 애플리케이션
API 서버http://localhost:1028/apiREST API 엔드포인트
Sonamu UIhttp://localhost:1028/sonamu-ui엔티티 관리 인터페이스
Web 앱에 접속하여 Sonamu 애플리케이션이 정상적으로 실행되는지 확인하세요.

​
Sonamu UI 기능

브라우저에서 http://localhost:1028/sonamu-ui 로 접속하면 다음 작업을 수행할 수 있습니다:
  • 엔티티 생성 및 편집
  • 데이터베이스 마이그레이션 관리
  • API 엔드포인트 확인
  • 데이터베이스 스키마 시각화

📸 필요: Sonamu UI 메인 화면 (Entity 탭, Migration 탭 등이 보이는 전체 UI)

​
서버 중지

개발을 마치고 서버를 중지하려면:
  1. API 서버 (그리고 Web 서버가 실행 중이라면): 각 터미널에서 Ctrl + C 키를 눌러 중지합니다.
  2. 데이터베이스: api 디렉토리에서 다음 명령어를 실행합니다: 
pnpm docker:down
docker:down 명령어는 컨테이너를 중지만 하며, 데이터는 보존됩니다. 데이터베이스를 완전히 초기화하려면 데이터베이스 관리 문서를 참고하세요.

​
다음 단계

개발 환경이 준비되었습니다! 이제 다음 가이드를 통해 Sonamu의 핵심 기능을 배워보세요:

첫 엔티티 만들기

Sonamu UI를 사용하여 첫 번째 엔티티를 생성하고 데이터베이스 스키마를 정의하세요.

API 개발하기

엔티티 기반으로 REST API를 생성하고 비즈니스 로직을 구현하세요.

프론트엔드 통합

자동 생성된 서비스 레이어를 사용하여 프론트엔드에서 API를 호출하세요.

프로젝트 구조

Sonamu 프로젝트의 디렉토리 구조와 주요 파일들을 이해하세요.