필수 프로 그램 설치하기
필수 도구를 준비한 뒤 HandStack 배포본을 구성하고 서버를 실행합니다. 브라우저에서 호스트 기동 확인 페이지가 응답하면 완료됩니다.
운영체제 별로 여러 도구를 한 번에 준비하는 설치 스크립트는 개발 도구 자동 설치에 있습니다. 수동으로 직접 설치는 공식 설치 안내 에 있는 각 공식 링크에서 확인하세요.
필요한 도구
현재 소스의 ack는 net10.0을 대상으로 합니다. 아래 구성은 배포본의 install.bat·install.sh를 사용하는 학습 경로입니다.
| 도구 | 필요한 이유와 선택 기준 | 확인 명령 |
|---|---|---|
| .NET SDK 10 정식 버전 | 서버 빌드와 .NET 전역 도구 설치. SDK에는 서버 실행용 런타임도 포함됩니다. | dotnet --list-sdks |
| Node.js·npm | 구성 스크립트의 패키지 복원과 화면 자원 처리. 프로젝트 요구사항은 20.12.2 이상이며 새 환경은 지원 중인 LTS 계열을 선택합니다. | node --version, npm --version |
| gulp-cli | HandStack 화면 자원 번들링 | gulp --version |
| curl | 구성 스크립트에서 외부 자원 다운로드 | curl --version |
| Git | 소스를 복제할 때만 필요. 배포본 실습에는 필요하지 않습니다. | git --version |
Node.js 의 최소 요구 버전과 지원 종료 여부는 다릅니다. Node.js 지원 일정을 확인하고 사용하는 HandStack 릴리스의 요구사항과 맞추세요.
SDK와 Runtime 중 무엇을 설치하나요?
이미 구성이 끝난 framework-dependent 배포본을 실행할 때는 ASP.NET Core Runtime이 필요합니다. 그러나 이 학습 경로의 구성 스크립트는 LibMan 같은 .NET 도구도 설치하므로 SDK 10을 준비합니다. 서버 소스를 빌드할 때도 SDK가 필요합니다.
install 스크립트의 자동 설치
install.bat·install.ps1·install.sh는 구성을 시작하기 전에 필수 도구를 확인하고, 없는 도구를 자동으로 설치한 뒤 중단 없이 이어서 진행합니다.
| 도구 | 확인 기준 | 자동 설치 방법 |
|---|---|---|
| .NET | 소스 저장소: SDK 10.0.x배포본: Microsoft.AspNetCore.App·Microsoft.NETCore.App 10.0.x | 없으면 SDK 10을 설치합니다. Windows는 WinGet(없으면 공식 설치 파일), Linux는 apt 패키지(없으 면 dotnet-install.sh로 ~/.dotnet), macOS는 dotnet-install.sh로 ~/.dotnet에 설치합니다. |
| Node.js·npm | v20.12.2 이상 | 없거나 24 미만이면 Node.js 24 LTS 최신 패치를 설치합니다. Windows는 공식 MSI, Ubuntu·Debian은 NodeSource, macOS는 Homebrew node@24를 사용합니다. 현재 Node.js를 nvm-windows·nvm이 관리하면 nvm으로 24.x를 설치하고 사용(기본) 버전으로 전환합니다. |
| gulp-cli | gulp 명령 | npm install --global gulp-cli |
| curl | curl 명령 | Windows는 기본 포함(없으면 WinGet), Linux는 apt, macOS는 Homebrew |
| rsync | 소스 저장소의 install.sh만 확인 | Linux는 apt, macOS는 Homebrew |
install.bat은 필수 도구 단계를install.ps1 -PrerequisitesOnly에 맡기고, 끝나면 현재 명령 프롬프트의 PATH를 다시 읽어 방금 설치한 도구를 바로 사용합니다.- Windows에서 .NET이나 Node.js를 설치해야 하면 UAC 권한 상승을 한 번만 요청합니다. gulp-cli 같은 사용자 도구는 스크립트를 실행한 계정에 설치됩니다. Linux에서는 설치 전에
sudo인증을 한 번 받고, root로 실행하면 sudo 없이 설치합니다. - 기존 Node.js가 24 미만이면 다른 프로젝트에 영향을 줄 수 있음을 안내한 뒤 24 LTS 최신 패치로 업그레이드를 시도합니다. 설치 후에도 기존 버전이 실행되면 PATH 또는 버전 관리 도구 설정을 확인하고 다시 실행하세요.
- macOS에서 Homebrew가 필요한데 Xcode Command Line Tools가 없으면
xcode-select --install을 먼저 진행하라는 안내와 함께 중단합니다. apt를 쓰지 않는 Linux 배포판 에서는 Node.js·curl·rsync를 자동 설치하지 않고 공식 안내를 표시합니다. - 필수 도구를 자동으로 설치하거나 업그레이드하지 않으려면
install.bat --check-only,./install.ps1 -CheckOnly,bash ./install.sh --check-only로 실행하거나 환경 변수HANDSTACK_SKIP_PREREQUISITES=1을 지정합니다. 이때 Node.js는 최소 요구 버전 20.12.2 이상인지 확인하며, 필수 조건이 충족되지 않으면 공식 안내를 표시하고 중단합니다. - 설치 프로그램이 재부팅을 요청하면 설치는 계속 진행하고, 완료 후 Windows를 다시 시작하라는 경고를 표시합니다.
내 PC에서 실행하기
기존 프로젝트와 분리된 실습 디렉터리를 사용하세요. 여기서는 압축 안의 handstack 디렉터리를 Windows의 C:/projects/handstack, Linux·macOS의 사용자 디렉터리 아래 projects/handstack에 둡니다.
배포본 받기
HandStack 릴리스에서 OS와 CPU에 맞는 파일을 내려받으세요. 파일명에 win, linux, osx와 x64, arm64 등의 대상이 표시됩니다. 실제 제공되는 파일과 요구사항은 해당 릴리스 설명을 따릅니다.
압축을 풀고 아래 항목이 있는 디렉터리를 찾으세요. 이 문서에서는 그 위치를 HandStack 기본 경로라고 부릅니다.
handstack/
├─ app/ # ack 실행 파일과 설정
├─ modules/ # 서버 모듈과 화면 자원
├─ install.bat
└─ install.sh
운영체제와 배포본의 아키텍처를 맞추는 방법은 지원 환경 확인을 참고하세요.
구성하고 실행하기
- Windows
- Linux
- macOS
Windows에서 실행
PowerShell에서 HandStack 기본 경로로 이동해 구성 스크립트를 실행합니다.
Set-Location C:/projects/handstack
.\install.bat
완료 메시지를 확인한 뒤 서버를 실행하세요. 오류가 나면 먼저 누락된 도구나 다운로드 실패를 해결합니다.
Set-Location C:/projects/handstack/app
.\ack.exe
Linux에서 실행
일반 사용자 터미널에서 구성합니다. 압축을 다른 위치에 풀었다면 첫 경로를 바꾸세요.
cd ~/projects/handstack
bash ./install.sh
완료 후 서버를 실행합니다.
cd ~/projects/handstack/app
chmod +x ack
./ack
배포본에 ack.dll이 있으면 dotnet ack.dll로도 실행할 수 있습니다.
macOS에서 실행
일반 사용자 터미널에서 구성합니다. Apple Silicon과 Intel용 배포본·.NET의 아키텍처가 맞는지 먼저 확인하세요.
cd ~/projects/handstack
bash ./install.sh
완료 후 서버를 실행합니다.
cd ~/projects/handstack/app
chmod +x ack
./ack
배포본에 ack.dll이 있으면 dotnet ack.dll로도 실행할 수 있습니다.
브라우저에서 확인하기
서버 터미널을 열어 둔 채 호스트 기동 확인 페이지에 접속하세요. 기본 포트는 8421이며 설정을 바꿨다면 실행 로그에 표시된 주소를 사용합니다.
기동 확인 페이지가 응답하고 서버에 기동 오류가 없으면 이 단계가 완료됩니다. 업무 화면은 /view/{ProjectID}/{화면ID}.html 경로로 엽니다.
접속되지 않으면 실행·화면·거래 문제 해결을 확인하세요.
공식 설치 안내
OS에 맞는 .NET과 Node.js를 먼저 설치한 뒤 gulp-cli를 준비하세요. 이미 정상 동작하는 도구는 다시 설치할 필요가 없습니다.
| 도구 | 공식 안내 |
|---|---|
| .NET SDK 10 | Windows 설치 · macOS 설치 · Ubuntu 설치 |
| Node.js·npm | OS별 Node.js 다운로드와 설치 |
| gulp-cli | gulp CLI 설치 |
| curl | curl 배포본과 설치 정보 |
| Git — 소스 개발 시 | Git 설치 |
패키지 관리자를 사용할 경우 WinGet·Homebrew 안내를 확인하세요. 공식 설치 프로그램을 쓴다면 패키지 관리자를 별도로 설치하지 않아도 됩니다.
설치 확인
새 터미널에서 실행합니다.
dotnet --list-sdks
dotnet --list-runtimes
node --version
npm --version
gulp --version
curl --version
- SDK 목록에 정식
10.0.x가 표시됩니다. - 런타임 목록에
Microsoft.AspNetCore.App 10.0.x가 표시됩니다. - 나머지 명령도 버전 정보를 출력합니다.
gulp --version에서 CLI 버전을 확인하세요. 프로젝트 밖에서 Local version이 없다고 나오는 것은 설치 실패가 아닙니다. - Windows PowerShell에서
npm.ps1실행 정책 오류가 나면npm.cmd --version으로 확인할 수 있습니다.
명령을 찾지 못하면 해당 도구의 설치와 PATH를 확인하세요. 설치 직후라면 먼저 터미널을 새로 여세요.
HandStack 추가 도구
install.bat·install.sh는 LibMan이 없으면 .NET 전역 도구 설치를 시도합니다. 현재 구성 단계에서는 libman restore를 실행하지 않으므로 SDK가 없거나 설치에 실패해도 경고만 남기고 계속 진행합니다. 직접 관리하려면 LibMan CLI 안내를 참고하세요.
PowerShell 스크립트(.ps1)로 빌드·운영할 때는 PowerShell 설치 안내를 확인하세요. .bat 또는 .sh로 진행하는 첫 실습의 별도 필수 단계는 아닙니다.