본문으로 건너뛰기

로컬 개발 및 빌드 환경 가이드

Nexus Agent Platform 자체를 개조하거나 기여하기 위해 소스코드를 직접 실행하는 개발자용 가이드입니다.

플랫폼 구조는 Next.js (프론트엔드) 와 Python FastAPI (백엔드 패키지) 로 구성됩니다.

소스코드 다운로드 & 백엔드 띄우기​

의존성 격리 및 빠른 Python 패키지 관리를 위해 uv를 사용합니다.

# 레포 복제
git clone git@github.com:EJCHO-salary/track_platform.git
cd track_platform

# 초기 환경 동기화
uv sync
uv run nexus-agent init

# 백엔드 서버 개발 모드로 구동
# (CORS가 개방되며 코드 핫 리로드가 활성화됨)
uv run nexus-agent start --dev

프론트엔드 (Next.js) 띄우기​

별도의 터미널 창을 열고 frontend/ 디렉토리로 진입해야 합니다. 프론트엔드는 pnpm 기반으로 작동합니다.

cd frontend
pnpm install
pnpm dev

이제 http://localhost:3000 에서 프론트엔드를 테스트할 수 있습니다. 만약 백엔드를 기본 포트(8000)가 아닌 다른 포트로 수정하셨다면 frontend/.env.local 에 별도 환셩 변수를 명시하세요:

NEXT_PUBLIC_API_URL=http://localhost:9000

어플리케이션 통합 빌드 (Wheel 생성)​

수정 사항을 패키징해 배포판인 휠(.whl)로 묶고 싶다면 통합 빌드 스크립트를 사용합니다:

./scripts/build.sh

이 프로세스는 내부적으로 다음 작업을 일괄 수행합니다:

  1. frontend/ 구역을 Static Export 모드로 빌드합니다. (Next.js)
  2. 생성된 HTML, JS, CSS 뭉치를 python 패키지 내 nexus_agent/static/ 폴더로 복사합니다.
  3. uv build 를 통해 Python 패키지를 빌드하고 최종적으로 dist/ 폴더 내에 휠 파일을 아웃풋으로 뱉습니다.