ezfunlab

EZFUNLAB 번역버튼
🌐

그누보드6 Windows 설치 가이드

이 가이드는 Windows 환경에서 그누보드6를 설치하고 실행하는 과정에서 마주칠 수 있는 복잡한 Python, Rust, C/C++ 컴파일, 그리고 패키지 의존성 충돌 문제들을 해결하는 노하우를 담고 있습니다. 이대로 따라오시면 성공적으로 그누보드6를 구동할 수 있을 것입니다.

기본 설치 가이드는
https://sir.kr/manual/g6/install/#1-git-clone
참조
기본으로 python 설치 되어 있어야함

1단계: Python 가상 환경 활성화

그누보드6 설치의 첫걸음은 격리된 Python 가상 환경을 활성화하는 것입니다.

  1. 명령 프롬프트(CMD) 또는 PowerShell을 엽니다.
  2. 그누보드6 프로젝트 폴더(예: D:\gnuboard\g6)로 이동합니다
    D:\gnuboard\g6
  3. 다음 명령어를 사용하여 가상 환경을 활성화합니다.
    venv\Scripts\activate
  4. 명령 프롬프트 맨 앞에 (venv)가 표시되면 성공입니다.

2단계: Rust 및 Cargo 설치 (Python 확장 모듈 빌드 오류 해결)

그누보드6가 사용하는 일부 Python 패키지(예: cryptography, pydantic-core)는 Rust 언어로 작성된 확장 모듈을 포함하고 있습니다. 이들을 컴파일하려면 Rust 컴파일러와 패키지 관리자인 Cargo가 필요하며, 이들이 없으면
Cargo, the Rust package manager, is not installed or is not on PATH
와 같은 오류가 발생합니다.

  1. Rustup 다운로드 및 설치:
    • 웹 브라우저에서 https://rustup.rs/ 로 이동합니다.
    • “Download rustup-init.exe for Windows 64-bit” 버튼을 클릭하여 설치 파일을 다운로드합니다.
    • 다운로드한
      rustup-init.exe
      를 실행하고, 설치 과정에서 기본 옵션
      (1) Proceed with installation (default))
      을 선택하여 진행합니다.
  2. 명령 프롬프트 재시작:
    Rust 설치 후에는 모든 명령 프롬프트(또는 PowerShell) 창을 닫고 다시 열어 시스템 환경 변수가 제대로 적용되도록 합니다.
  3. 설치 확인 및 업데이트:
    새로 연 명령 프롬프트에서 다음 명령어를 입력하여 Rust와 Cargo가 정상적으로 설치되었는지 확인하고 최신 상태로 업데이트합니다.
    rustc --version
    cargo --version
    rustup update
  4. 버전 정보가 출력되고
    up to date
    메시지가 나타나면 성공입니다.

3단계: psycopg2 관련 오류 해결 (pg_config 오류)

그누보드6가 PostgreSQL 데이터베이스를 사용하는 경우,
Python의 psycopg2 패키지 설치 시
Error: pg_config executable not found
와 같은 오류가 발생할 수 있습니다.

  • psycopg2-binary 설치 (권장):
    psycopg2 대신 미리 컴파일된 바이너리 버전인
    psycopg2-binary를 설치하는 것이 가장 간단합니다.
    pip install psycopg2-binary
    • requirements.txt 수정:
      만약 requirements.txt에 psycopg2로 명시되어 이로 인해 문제가 지속된다면, 해당 라인을 psycopg2-binary로 직접 수정하고 저장하세요.
      이미 설치된 psycopg2-binary 버전이 있다면
      pip install --upgrade psycopg2-binary
      로 업데이트하거나,
      requirements.txt에 명시된 버전을 현재 시스템에 설치된 버전과 일치시키세요.

4단계: lxml, pydantic-core, pydantic 의존성 충돌 및 빌드 오류 해결

이 패키지들은 Python 3.13과 같은 최신 버전에서
ImportError (예: lxml.html.clean 분리),
TypeError (ForwardRef._evaluate() 변경),
또는 버전 간 충돌(pydantic과 pydantic-core 간 불일치)을 일으키는 주범입니다.

  1. pip 업그레이드:
    가장 먼저 pip 자체를 최신 버전으로 업데이트하여 의존성 해결 능력을 향상시킵니다.
    python.exe -m pip install --upgrade pip
  2. requirements.txt 파일 수정 (가장 중요):
    D:\gnuboard\g6\requirements.txt 파일을 열어서 다음 패키지들의 라인을 찾고 수정합니다.
    • lxml: lxml.html.clean 모듈 분리 오류가 발생한다면,
      lxml의 추가 기능인 html_clean을 설치하거나 별도 패키지를 설치해야 합니다.
      가장 쉬운 방법은 requirements.txt에 lxml_html_clean을 추가하는 것입니다.
      lxml_html_clean
      # 이 줄을 추가합니다.
    • pydantic 및 pydantic-core: 이 두 패키지는 서로 강력한 의존성을 가지며, Python 3.13 환경에서 버전 호환성 문제가 자주 발생했습니다.
      • 가장 권장하는 방법 (성공 사례 바탕):
        서로 호환되는 버전을 requirements.txt에 명시하는 것입니다.
        이전에 pydantic==2.11.7과 pydantic-core==2.33.2가 정상적으로 설치되었음을 확인했으므로, 이 조합을 사용합니다.
        pydantic==2.11.7
        pydantic-core==2.33.2
  3. requirements.txt 저장: 변경한 내용을 저장합니다.

5단계: 모든 패키지 최종 설치 및 Uvicorn 실행

이제 모든 준비와 수정이 완료되었으니, requirements.txt를 사용하여 필요한 모든 패키지를 설치하고 그누보드6 서버를 실행합니다.

  1. 가상 환경이 활성화되어 있는지 다시 한번 확인합니다.Bash(venv) D:\gnuboard\g6>venv\Scripts\activate
  2. 모든 패키지 설치를 시도합니다:
    pip install -r requirements.txt
    이 과정에서 이미 설치된 패키지들은 Requirement already satisfied 메시지를 출력하며 건너뛸 것입니다.
  3. Uvicorn으로 그누보드6 실행: 패키지 설치가 성공적으로 완료되면, 다음 명령어로 그누보드6 서버를 실행합니다.
    uvicorn main:app --reload
    • INFO: Uvicorn running on http://127.0.0.1:8000과 같은 메시지가 보이면 성공입니다. 웹 브라우저에서 해당 주소로 접속해 보세요.*

버전이 다르다 보니 버전에 정확하게 하는 것이 중요합니다.