bada-terminal / windows-setup.html
VanyaJ's picture
Upload windows-setup.html with huggingface_hub
552fc38 verified
Raw
History Blame Contribute Delete
25 kB
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>BADA Terminal — Windows Setup & Air-gap Build Manual</title>
<meta name="description" content="BADA Terminal의 윈도우 환경 구축, 개발/빌드 환경 설정 및 에어갭 오프라인 배포 패키지 구성 가이드">
<!-- Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&family=Outfit:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
<!-- Styling -->
<style>
:root {
--bg: #1e1e2e;
--mantle: #181825;
--crust: #11111b;
--text: #cdd6f4;
--subtext: #a6adc8;
--mauve: #cba6f7;
--blue: #89b4fa;
--lavender: #b4befe;
--green: #a6e3a1;
--yellow: #f9e2af;
--red: #f38ba8;
--peach: #fab387;
--teal: #94e2d5;
--surface0: #313244;
--surface1: #45475a;
--surface2: #585b70;
--overlay0: #6c7086;
--border: rgba(255, 255, 255, 0.06);
--glass-bg: rgba(24, 24, 37, 0.75);
--glass-border: rgba(255, 255, 255, 0.05);
--card-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.3);
--transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
}
body.light-theme {
--bg: #eff1f5;
--mantle: #e6e9ef;
--crust: #dce0e8;
--text: #4c4f69;
--subtext: #5c5f77;
--mauve: #8839ef;
--blue: #1e66f5;
--lavender: #7287fd;
--green: #40a02b;
--yellow: #df8e1d;
--red: #d20f39;
--peach: #fe640b;
--teal: #179287;
--surface0: #ccd0da;
--surface1: #bcc0cc;
--surface2: #acb0be;
--overlay0: #8c8fa1;
--border: rgba(0, 0, 0, 0.06);
--glass-bg: rgba(230, 233, 239, 0.85);
--glass-border: rgba(0, 0, 0, 0.08);
--card-shadow: 0 8px 24px 0 rgba(0, 0, 0, 0.08);
}
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
html, body {
width: 100%;
height: 100%;
background-color: var(--bg);
color: var(--text);
font-family: 'Outfit', -apple-system, BlinkMacSystemFont, sans-serif;
overflow: hidden;
transition: background-color 0.3s ease, color 0.3s ease;
}
#app-layout {
display: flex;
width: 100vw;
height: 100vh;
overflow: hidden;
}
/* Sidebar Navigation */
#sidebar {
width: 320px;
height: 100%;
background: var(--mantle);
border-right: 1px solid var(--border);
display: flex;
flex-direction: column;
flex-shrink: 0;
}
#sidebar-header {
padding: 24px;
border-bottom: 1px solid var(--border);
display: flex;
flex-direction: column;
gap: 12px;
}
.brand-title {
font-size: 20px;
font-weight: 800;
background: linear-gradient(135deg, var(--blue), var(--teal));
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
letter-spacing: -0.5px;
}
.brand-subtitle {
font-size: 11px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 1.5px;
color: var(--subtext);
}
#sidebar-menu {
flex: 1;
overflow-y: auto;
padding: 16px 12px;
}
.menu-group {
margin-bottom: 20px;
}
.menu-group-title {
font-size: 11px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 1.5px;
color: var(--overlay0);
padding-left: 12px;
margin-bottom: 8px;
}
.menu-item {
display: flex;
align-items: center;
gap: 10px;
padding: 10px 12px;
border-radius: 8px;
color: var(--subtext);
text-decoration: none;
font-size: 14px;
font-weight: 500;
cursor: pointer;
transition: var(--transition);
margin-bottom: 2px;
}
.menu-item:hover {
background: var(--surface0);
color: var(--text);
}
.menu-item.active {
background: rgba(137, 180, 250, 0.15);
color: var(--blue);
font-weight: 600;
}
.menu-item-icon {
font-size: 16px;
width: 20px;
text-align: center;
}
#sidebar-footer {
padding: 16px 20px;
border-top: 1px solid var(--border);
display: flex;
align-items: center;
justify-content: space-between;
background: var(--crust);
}
.theme-toggle-btn {
background: var(--surface0);
border: 1px solid var(--surface1);
color: var(--text);
width: 32px;
height: 32px;
border-radius: 6px;
cursor: pointer;
display: flex;
align-items: center;
justify-content: center;
transition: var(--transition);
}
.theme-toggle-btn:hover {
background: var(--surface1);
border-color: var(--blue);
color: var(--blue);
}
.version-tag {
font-size: 11px;
font-family: 'JetBrains Mono', monospace;
color: var(--overlay0);
background: var(--surface0);
padding: 3px 8px;
border-radius: 4px;
}
/* Main Content */
#content-container {
flex: 1;
height: 100%;
overflow-y: auto;
background: var(--bg);
padding: 40px 60px;
scroll-behavior: smooth;
}
.doc-section {
display: none;
animation: fadeIn 0.3s cubic-bezier(0.4, 0, 0.2, 1) forwards;
max-width: 900px;
margin: 0 auto;
}
.doc-section.active {
display: block;
}
@keyframes fadeIn {
from { opacity: 0; transform: translateY(12px); }
to { opacity: 1; transform: translateY(0); }
}
.section-header {
margin-bottom: 32px;
border-bottom: 1px solid var(--border);
padding-bottom: 20px;
}
.section-badge {
display: inline-block;
font-size: 11px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 1.5px;
color: var(--blue);
background: rgba(137, 180, 250, 0.12);
padding: 4px 10px;
border-radius: 99px;
margin-bottom: 12px;
}
h1 {
font-size: 32px;
font-weight: 800;
color: var(--text);
letter-spacing: -0.8px;
}
p.section-desc {
font-size: 15px;
color: var(--subtext);
margin-top: 8px;
line-height: 1.5;
}
h2 {
font-size: 20px;
font-weight: 700;
color: var(--text);
margin-top: 36px;
margin-bottom: 16px;
display: flex;
align-items: center;
gap: 10px;
}
h2::before {
content: '';
display: inline-block;
width: 4px;
height: 18px;
background: var(--blue);
border-radius: 2px;
}
h3 {
font-size: 16px;
font-weight: 600;
color: var(--text);
margin-top: 24px;
margin-bottom: 10px;
}
p {
font-size: 14.5px;
line-height: 1.7;
color: var(--subtext);
margin-bottom: 16px;
}
/* Tables */
table {
width: 100%;
border-collapse: collapse;
margin: 20px 0;
font-size: 14px;
text-align: left;
}
th {
background: var(--mantle);
color: var(--text);
font-weight: 600;
padding: 12px 16px;
border: 1px solid var(--border);
}
td {
padding: 12px 16px;
border: 1px solid var(--border);
color: var(--subtext);
}
tr:nth-child(even) td {
background: rgba(255, 255, 255, 0.01);
}
/* Code Block styling */
pre {
background: var(--crust);
border: 1px solid var(--border);
border-radius: 8px;
padding: 16px;
overflow-x: auto;
margin: 16px 0;
font-family: 'JetBrains Mono', monospace;
font-size: 13px;
line-height: 1.5;
}
code {
font-family: 'JetBrains Mono', monospace;
font-size: 12.5px;
background: var(--mantle);
color: var(--peach);
padding: 2px 5px;
border-radius: 4px;
border: 1px solid var(--border);
}
pre code {
background: transparent;
color: var(--text);
padding: 0;
border: none;
}
.callout {
border-left: 4px solid var(--blue);
background: rgba(137, 180, 250, 0.04);
padding: 18px;
border-radius: 0 8px 8px 0;
margin: 20px 0;
display: flex;
gap: 14px;
}
.callout.warning {
border-left-color: var(--yellow);
background: rgba(249, 226, 175, 0.04);
}
.callout.danger {
border-left-color: var(--red);
background: rgba(243, 139, 168, 0.04);
}
.callout-icon {
font-size: 20px;
line-height: 1;
}
.callout-content {
flex: 1;
}
.callout-title {
font-size: 14.5px;
font-weight: 700;
color: var(--text);
margin-bottom: 4px;
}
.callout-text {
font-size: 13.5px;
color: var(--subtext);
margin: 0;
line-height: 1.5;
}
/* Step UI */
.step-list {
display: flex;
flex-direction: column;
gap: 16px;
margin: 20px 0;
}
.step-list-item {
background: var(--mantle);
border: 1px solid var(--border);
border-radius: 8px;
padding: 18px;
display: flex;
gap: 16px;
}
.step-num {
width: 28px;
height: 28px;
border-radius: 50%;
background: var(--blue);
color: var(--crust);
font-weight: 700;
display: flex;
align-items: center;
justify-content: center;
flex-shrink: 0;
font-size: 13px;
}
.step-content {
flex: 1;
}
.step-title-inline {
font-size: 15px;
font-weight: 700;
color: var(--text);
margin-bottom: 6px;
}
.step-body {
font-size: 13.5px;
color: var(--subtext);
line-height: 1.5;
}
</style>
</head>
<body>
<div id="app-layout">
<!-- Sidebar -->
<aside id="sidebar">
<div id="sidebar-header">
<div class="brand-title">⚙️ Windows Setup Guide</div>
<div class="brand-subtitle">BADA Deployment Platform</div>
</div>
<nav id="sidebar-menu">
<div class="menu-group">
<div class="menu-group-title">일반 윈도우 설정</div>
<div class="menu-item active" data-target="win-runtime">
<span class="menu-item-icon">📦</span> 1. 런타임 환경 설정
</div>
<div class="menu-item" data-target="win-build">
<span class="menu-item-icon">🛠️</span> 2. 개발 및 빌드 환경
</div>
</div>
<div class="menu-group">
<div class="menu-group-title">에어갭 (망분리) 배포</div>
<div class="menu-item" data-target="airgap-packages">
<span class="menu-item-icon">🗂️</span> 3. 오프라인 패키지 구성
</div>
<div class="menu-item" data-target="airgap-install">
<span class="menu-item-icon">🚀</span> 4. 에어갭 서버 설치 절차
</div>
</div>
</nav>
<div id="sidebar-footer">
<button class="theme-toggle-btn" id="theme-toggle">🌓</button>
<span class="version-tag">Windows x64</span>
</div>
</aside>
<!-- Content -->
<main id="content-container">
<!-- Section: Runtime Setup -->
<section id="win-runtime" class="doc-section active">
<div class="section-header">
<span class="section-badge">Runtime Setup</span>
<h1>런타임 환경 구성 (Windows)</h1>
<p class="section-desc">BADA Terminal과 Claude Code CLI를 정상 구동하기 위해 필요한 기본 런타임 환경을 설정합니다.</p>
</div>
<h2>필수 런타임 종속성</h2>
<table>
<thead>
<tr>
<th>소프트웨어</th>
<th>권장 버전</th>
<th>설치 유형</th>
<th>역할</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Node.js</strong></td>
<td>v20.x 또는 v22.x (LTS)</td>
<td>Installer (.msi) 또는 Binary (.zip)</td>
<td>애플리케이션 구동 및 PTY 브릿지 엔진</td>
</tr>
<tr>
<td><strong>Git for Windows</strong></td>
<td>v2.40.0 이상</td>
<td>Windows Installer (.exe)</td>
<td>작업 디렉토리 체크아웃 및 Worktree 격리 제어</td>
</tr>
<tr>
<td><strong>Claude CLI</strong></td>
<td>최신 공식 릴리스</td>
<td>글로벌 npm 모듈 (<code>@anthropic-ai/claude-code</code>)</td>
<td>PTY의 명령 처리를 맡는 AI 에이전트 브레인</td>
</tr>
</tbody>
</table>
<h2>환경 변수 (System Environment Variables)</h2>
<p>BADA가 외부 바이너리를 올바르게 찾을 수 있도록 윈도우 환경 변수에 경로들을 마운트해야 합니다.</p>
<h3>1. PATH 등록</h3>
<p><code>제어판 > 시스템 및 보안 > 시스템 > 고급 시스템 설정 > 환경 변수 > 시스템 변수 > Path</code> 에 아래 항목들이 포함되어야 합니다.</p>
<pre><code># Node.js 전역 모듈 경로
%APPDATA%\npm
# Git 바이너리 경로
C:\Program Files\Git\cmd
# Node.js 설치 경로 (기본 설정)
C:\Program Files\nodejs\</code></pre>
<div class="callout warning">
<span class="callout-icon">⚠️</span>
<div class="callout-content">
<h5 class="callout-title">PowerShell 권한 설정</h5>
<p class="callout-text">BADA의 PTY 및 쉘 연동 스크립트가 PowerShell 세션에서 실행을 거부당하지 않도록 관리자 권한 콘솔에서 다음 명령어를 실행하여 실행 정책을 완화하십시오: <br><code>Set-ExecutionPolicy RemoteSigned -Scope LocalMachine</code></p>
</div>
</div>
</section>
<!-- Section: Dev/Build Setup -->
<section id="win-build" class="doc-section">
<div class="section-header">
<span class="section-badge">Development & Build</span>
<h1>개발 및 빌드 환경 상세 설정</h1>
<p class="section-desc">BADA Terminal 소스 코드를 편집하고 Electron 패키징 또는 C++ 네이티브 모듈 컴파일 환경을 구성합니다.</p>
</div>
<h2>네이티브 C++ 바인딩을 위한 빌드 도구</h2>
<p>BADA는 PTY 인터페이스를 위한 <code>node-pty</code>와 데이터베이스 핸들링을 위한 <code>better-sqlite3</code> 모듈을 사용합니다. 이 모듈들은 C++ 바인딩을 포함하므로 윈도우에서는 컴파일 환경이 필수적입니다.</p>
<div class="step-list">
<div class="step-list-item">
<div class="step-num">1</div>
<div class="step-content">
<div class="step-title-inline">Visual Studio Build Tools 설치</div>
<div class="step-body">
Visual Studio Build Tools 2022 이상 버전을 다운로드하고, 설치 시 반드시 <strong>"C++를 사용한 데스크톱 개발"</strong> 워크로드를 체크하여 C++ 컴파일러(MSVC) 및 MSBuild를 획득해야 합니다.
</div>
</div>
</div>
<div class="step-list-item">
<div class="step-num">2</div>
<div class="step-content">
<div class="step-title-inline">Python 설치 및 환경 변수 바인딩</div>
<div class="step-body">
<code>node-gyp</code> 컴파일에 사용되는 Python 3.10 또는 3.11을 설치합니다. 시스템 환경 변수에 <code>PYTHON</code> 키를 등록하고 설치된 <code>python.exe</code>의 절대경로를 값으로 바인딩합니다.
</div>
</div>
</div>
<div class="step-list-item">
<div class="step-num">3</div>
<div class="step-content">
<div class="step-title-inline">npm 글로벌 컴파일 셋팅</div>
<div class="step-body">
관리자 권한 콘솔에서 아래 명령을 통해 msvs 컴파일러 버전을 명시적으로 지정합니다.
<pre><code>npm config set msvs_version 2022</code></pre>
</div>
</div>
</div>
</div>
<h2>네이티브 모듈 및 Electron 리빌드 구동</h2>
<p>개발 버전 구동 시, Node.js 기본 빌드 모듈을 Electron 런타임 아키텍처에 맞게 리빌드합니다.</p>
<pre><code># 패키지 설치
npm install
# electron-rebuild를 통한 C++ 바이너리 재생성
npm run rebuild</code></pre>
<h2>패키징 빌드</h2>
<pre><code># NSIS 인스톨러 및 ZIP 파일 빌드
npx electron-builder --win --x64</code></pre>
</section>
<!-- Section: Air-gap Packages -->
<section id="airgap-packages" class="doc-section">
<div class="section-header">
<span class="section-badge">Air-gap Packaging</span>
<h1>에어갭(망분리) 오프라인 패키지 구성 가이드</h1>
<p class="section-desc">인터넷 연결이 완전히 차단된 윈도우 서버 환경에 배포하기 위해 수집해야 할 파일 및 패키지 목록입니다.</p>
</div>
<h2>오프라인 설치용 수집 패키지 목록</h2>
<p>인터넷이 연결된 일반 PC에서 다음 바이너리 및 모듈들을 미리 다운로드하여 이동식 매체(USB 등)로 수집해야 합니다.</p>
<h3>1. 인프라 실행 및 컴파일러 바이너리</h3>
<ul>
<li><strong>Node.js LTS MSI Installer</strong>: <code>node-v20.11.0-x64.msi</code></li>
<li><strong>Git for Windows Installer</strong>: <code>Git-2.43.0-64-bit.exe</code></li>
<li><strong>Python Windows Installer</strong>: <code>python-3.11.8-amd64.exe</code></li>
<li><strong>VS Build Tools 2022 오프라인 레이아웃 패키지</strong>:
<br>인터넷 컴퓨터에서 다음 명령어로 약 3~4GB 분량의 오프라인 미디어를 만듭니다.
<pre><code>vs_BuildTools.exe --layout C:\VSBuildToolsLayout --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --lang ko-KR</code></pre>
</li>
</ul>
<h3>2. Claude Code CLI 글로벌 캐시 패키징</h3>
<p>글로벌 설치 모듈을 오프라인 서버로 옮기기 위해 인터넷 컴퓨터에서 tarball 파일로 패키징합니다.</p>
<pre><code># 글로벌 캐싱 다운로드 및 패키징
npm pack @anthropic-ai/claude-code</code></pre>
<p>생성된 <code>anthropic-ai-claude-code-x.x.x.tgz</code> 파일을 배포 매체에 수집합니다.</p>
<h3>3. BADA 소스코드 및 Prebuilt 모듈 번들링</h3>
<p>C++ 컴파일러 빌드가 막힐 경우를 방지하여, 인터넷 PC에서 C++ 네이티브 모듈 빌드가 완성된 <code>node_modules</code>를 ZIP 형태로 일괄 묶어 준비합니다.</p>
<pre><code># 윈도우 OS의 인터넷 PC에서 소스 다운로드 및 컴파일 완료 후 압축
npm install
npm run rebuild
tar -czf bada-node-modules.tar.gz node_modules/</code></pre>
</section>
<!-- Section: Air-gap Install -->
<section id="airgap-install" class="doc-section">
<div class="section-header">
<span class="section-badge">Installation Workflow</span>
<h1>에어갭 윈도우 서버 설치 및 실행 절차</h1>
<p class="section-desc">오프라인 서버에 수집한 패키지를 정렬하고 환경을 최종 셋업하여 구동하는 로드맵입니다.</p>
</div>
<h2>오프라인 설치 시나리오 1: BADA 전용 빌드 패키지 배포 (권장)</h2>
<p>가장 단순하고 오류가 없는 방법으로, 개발 컴퓨터에서 완전히 컴파일 및 번들링된 배포판 설치 파일(<code>BADA Terminal Setup X.X.X.exe</code>) 또는 <code>ZIP 포터블</code> 번들을 망분리 서버로 직접 복사해 실행하는 것입니다.</p>
<div class="step-list">
<div class="step-list-item">
<div class="step-num">1</div>
<div class="step-content">
<div class="step-title-inline">배포판 복사 및 실행</div>
<div class="step-body">
<code>C:\Users\jkb\Desktop\claude-cli-v2</code> 등의 경로에 <code>BADA Terminal Setup.exe</code> 파일을 이동시키고 더블클릭하여 설치를 마칩니다.
</div>
</div>
</div>
<div class="step-list-item">
<div class="step-num">2</div>
<div class="step-content">
<div class="step-title-inline">Git portable / Git for Windows 설치</div>
<div class="step-body">
워크플로우 격리를 위해 서버 내부에서 Git 명령이 동작해야 합니다. <code>Git-2.43.0-64-bit.exe</code>를 실행하여 설치하고 cmd 경로를 PATH에 등록합니다.
</div>
</div>
</div>
</div>
<h2>오프라인 설치 시나리오 2: 서버 소스 컴파일 및 기동</h2>
<p>서버 내부에서 자체 컴파일 및 핫 패치를 동반한 셋업을 원할 경우의 수동 복구 흐름입니다.</p>
<div class="step-list">
<div class="step-list-item">
<div class="step-num">1</div>
<div class="step-content">
<div class="step-title-inline">인프라 파일 순차 설치</div>
<div class="step-body">
1) Node.js MSI 실행 <br>
2) Git EXE 실행 <br>
3) Python AMD64 실행 및 <code>Add python.exe to PATH</code> 체크 필수!
</div>
</div>
</div>
<div class="step-list-item">
<div class="step-num">2</div>
<div class="step-content">
<div class="step-title-inline">C++ 빌드 도구 오프라인 구축 (VS Build Tools)</div>
<div class="step-body">
이동해 온 레이아웃 디렉토리에서 오프라인 모드로 실행합니다.
<pre><code>vs_BuildTools.exe --nocache --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended</code></pre>
</div>
</div>
</div>
<div class="step-list-item">
<div class="step-num">3</div>
<div class="step-content">
<div class="step-title-inline">Claude Code CLI 오프라인 설치</div>
<div class="step-body">
수집한 tgz 파일을 글로벌 모듈 경로로 설치합니다.
<pre><code>npm install -g .\anthropic-ai-claude-code-x.x.x.tgz --offline</code></pre>
</div>
</div>
</div>
<div class="step-list-item">
<div class="step-num">4</div>
<div class="step-content">
<div class="step-title-inline">BADA 소스코드 복사 및 모듈 해제</div>
<div class="step-body">
BADA 소스 디렉토리를 복사하고, 미리 압축해 온 <code>bada-node-modules.tar.gz</code>를 소스 루트에 압축 해제합니다. 또는 직접 컴파일을 수행합니다.
<pre><code># 압축 해제
tar -xzf bada-node-modules.tar.gz
# 또는 오프라인 컴파일 실행
npm install --offline
npm run rebuild</code></pre>
</div>
</div>
</div>
</div>
</section>
</main>
</div>
<script>
// Navigation switching
const menuItems = document.querySelectorAll('.menu-item');
const sections = document.querySelectorAll('.doc-section');
const content = document.getElementById('content-container');
menuItems.forEach(item => {
item.addEventListener('click', () => {
menuItems.forEach(i => i.classList.remove('active'));
item.classList.add('active');
sections.forEach(s => s.classList.remove('active'));
const target = item.getAttribute('data-target');
const targetSec = document.getElementById(target);
if (targetSec) {
targetSec.classList.add('active');
content.scrollTop = 0;
}
});
});
// Theme toggle
const themeToggle = document.getElementById('theme-toggle');
themeToggle.addEventListener('click', () => {
document.body.classList.toggle('light-theme');
});
</script>
</body>
</html>