설치하기
운영체제에 맞는 설치 방법을 선택하세요. 아래 링크를 누르면 이 문서의 해당 설치 절로 이동합니다.
패키지 선택하기
| 운영체제 | 설치방법 | 실행엔진 |
|---|---|---|
| Apple Silicon · macOS 27 이상 | DMG 다운로드 설치 · Homebrew 설치 | 네이티브 ROS 2 · Gazebo · Metal |
| Ubuntu 26.04 · x86-64 | APT 저장소 · DEB 다운로드 설치 | Docker의 Linux 엔진 |
| Windows · x86-64 | Windows 설치 | Docker Desktop · WSL2 |
Windows 설치
WSL2 준비하기
WSL이 없다면 시작 메뉴에서 터미널 또는 PowerShell을 관리자 권한으로 열고 실행하세요.
wsl --install --no-distribution
안내에 따라 컴퓨터를 다시 시작하세요. 다시 연 터미널에서 다음 명령을 실행하세요.
wsl --update
wsl --set-default-version 2
wsl --status
기본 버전이 2인지 확인하세요. 가상화 오류가 발생하면 펌웨어의 하드웨어 가상화 설정과 Microsoft WSL 설치 안내를 확인하세요. Docker Desktop은 자체 WSL2 환경을 사용하므로, 설치형 앱을 실행하기 위해 Ubuntu 배포판을 따로 설치할 필요는 없습니다. 별도의 ROS 환경이 필요한 경우에만 Ubuntu를 추가하세요.
Docker Desktop과 앱 설치하기
- Docker Desktop을 설치하세요. WSL2 설정 안내를 따르고, 재시작을 요청하면 컴퓨터를 재시작하세요. Docker는 시뮬레이터에 필요한 Linux 환경을 제공합니다.
- Docker Desktop을 열고 엔진 실행이 끝날 때까지 기다리세요.
- Windows 설치 프로그램을 내려받아 열고 설치 안내를 따르세요. Windows의 PC 보호 안내가 나오면 공식 WWW-POSIM 파일인지 확인한 뒤 추가 정보(More info) → 실행(Run anyway)을 선택하세요. 현재 Windows 패키지에는 Authenticode 서명이 없으며, 공개된 SHA-256 체크섬으로 배포 파일을 확인할 수 있습니다.
- 시작 메뉴에서 WWW-POSIM을 여세요. 앱의 첫 실행에서도 같은 안내가 나오면 추가 정보 → 실행을 다시 선택하세요. 로그인하고 Start simulator를 누르세요.
- 브라우저에 내 컴퓨터에서 실행 중인 시뮬레이터의 조작 화면이 열립니다. 작업공간 익히기를 따라 하세요.
앱을 사용하는 동안 Docker Desktop을 계속 실행하세요. 앱이 버전에 맞는 시뮬레이터 이미지를 자동으로 선택하고 내려받습니다.
DMG 다운로드 설치
Apple Silicon Mac과 macOS 27 이상이 필요합니다. 모델과 macOS 버전은 Apple 메뉴 → 이 Mac에 관하여에서 확인하세요.
- Mac DMG를 내려받으세요.
- 파일을 열고 WWW-POSIM을 응용 프로그램으로 드래그하세요.
- 응용 프로그램에서 WWW-POSIM을 열어 보세요. 앱은 임시 서명을 사용하며 Apple 공증은 없습니다.
- macOS가 첫 실행을 차단하면 시스템 설정 → 개인정보 보호 및 보안에서 보안 항목까지 아래로 이동하세요. WWW-POSIM 옆의 그래도 열기(Open Anyway)를 누르고 확인 창에서 열기를 선택하세요. macOS가 인증을 요청하면 직접 진행하세요. Apple의 첫 실행 안내에서도 확인할 수 있습니다.
- 로그인하고 Start simulator를 누르세요. 처음에는 일치하는 시뮬레이터 파일을 512 MiB 조각으로 내려받고 검증한 뒤 엔진의 압축을 풉니다. 다운로드가 중단되면 이어받을 수 있습니다. 다운로드와 압축 해제 진행률을 확인하세요.
- 브라우저가 열리면 작업공간 익히기를 따라 하세요.
Mac 앱은 지정된 ROS 환경을 한 번 내려받고 그래픽에 Metal을 사용합니다. 설치 파일과 각 데이터 조각은 모두 2 GiB 미만입니다. 다운로드 파일과 설치된 엔진은 앱 밖에 저장하여 다음 실행에서 재사용합니다.
앱 실행이 차단되거나 멈추면 Mac 앱 실행 문제 해결을 확인하세요.
Homebrew 설치
Homebrew가 없다면 공식 설치 안내에 따라 먼저 설치하세요. 다음 명령으로 WWW-POSIM을 설치합니다.
brew tap ioes-lab/www-posim
brew trust --cask ioes-lab/www-posim/www-posim
brew install --cask ioes-lab/www-posim/www-posim
Homebrew의 trust 명령은 지정한 저장소에서 이 앱의 Cask를 읽도록 허용합니다.
packages.arm64_dunno.jws.json을 요청하다 HTTP 404가 나오면, 현재 Homebrew가 macOS 27을 알아보지 못한 것입니다. 패키지 API를 우회하여 Homebrew를 갱신한 뒤 설치를 다시 진행합니다.
HOMEBREW_NO_INSTALL_FROM_API=1 brew update
HOMEBREW_NO_AUTO_UPDATE=1 brew tap ioes-lab/www-posim
HOMEBREW_NO_AUTO_UPDATE=1 brew trust --cask ioes-lab/www-posim/www-posim
HOMEBREW_NO_AUTO_UPDATE=1 brew install --cask ioes-lab/www-posim/www-posim
환경 변수는 각 명령에만 적용됩니다. 자세한 의미는 Homebrew 환경 옵션을 참고하세요. 계속 실패하면 위의 DMG로 같은 앱을 설치할 수 있습니다.
앱을 열고 웹사이트와 같은 이메일 계정으로 로그인합니다.
- 계정 서버: 자동 연결
- 첫 실행: 엔진 조각 다운로드·검증·결합 후 Library에 설치
- 실행 상태: 로그인, 파일 검증, 압축 해제 용량 / 전체 용량, 진행률과 예상 남은 시간, 서비스 시작
- 시뮬레이션: Mac에서 Gazebo·ROS 2·Autopilot 실행
- 렌더링: Metal로 Mac GPU 사용
- 업데이트: Update to 버전에서 선택
업데이트가 있어도 설치된 엔진을 계속 사용할 수 있습니다. 업데이트 안내가 실행 중인 시뮬레이션을 중단하지는 않습니다.
로컬 ROS 코드로 제어하려면 터미널마다 앱의 환경을 불러옵니다.
eval "$(/Applications/WWW-POSIM.app/Contents/MacOS/WWW-POSIM --ros-env)"
이어서 설치형 작업공간에서 제어를 확인하세요. 연결 도구·표준 ROS 메시지·RViz2는 앱에 포함됩니다. 앱의 ROS 터미널 열기와 RViz 열기를 사용하세요. 알고리즘에 필요한 추가 패키지는 호환 환경에 준비합니다.
Ubuntu의 Docker 준비하기
먼저 Docker와 다운로드 도구를 준비하세요. 계정에 Docker 사용 권한을 추가한 뒤 로그아웃하고 다시 로그인하세요.
sudo apt update
sudo apt install -y docker.io curl
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
APT 저장소
플랫폼의 고정 주소로 서명된 APT 저장소를 등록합니다.
SERVER=https://www-posim.vercel.app
curl -fSL "$SERVER/guide/packages/apt/www-posim-archive-keyring.gpg" | \
sudo tee /usr/share/keyrings/www-posim-archive-keyring.gpg >/dev/null
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/www-posim-archive-keyring.gpg] $SERVER/guide/packages/apt stable main" | \
sudo tee /etc/apt/sources.list.d/www-posim.list
sudo apt update
sudo apt install www-posim
www-posim
DEB를 내려받아 sudo apt install ./www-posim_*_amd64.deb로 설치할 수도 있습니다.
- Docker: 로그인한 사용자 계정에서 실행 가능해야 함
- 엔진 이미지: 설치된 앱 버전에 맞게 자동 선택
- GPU 렌더링: 이미지와 호환되는 드라이버·컨테이너 런타임
DEB 다운로드 설치
Linux 설치형 앱은 x86-64 컴퓨터의 Ubuntu 26.04를 지원합니다. Ctrl+Alt+T로 터미널을 여세요. 아래 블록을 복사해 붙여 넣고 Enter를 누르세요.
sudo apt update
sudo apt install -y docker.io curl
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
mkdir -p ~/Downloads
cd ~/Downloads
curl -fL -o www-posim.deb https://www-posim.vercel.app/guide/packages/latest/linux-amd64.deb
sudo apt install ./www-posim.deb
sudo가 물으면 컴퓨터 비밀번호를 입력하세요. 입력하는 동안 글자가 보이지 않는 것이 정상입니다.- Ubuntu에서 로그아웃한 뒤 다시 로그인하세요. 내 계정에 Docker 사용 권한이 적용됩니다.
- 앱 메뉴에서 WWW-POSIM을 열거나 새 터미널에서
www-posim을 실행하세요. - 로그인하고 Start simulator를 누르세요.
- 브라우저가 열리면 작업공간 익히기를 따라 하세요.
Docker를 쓸 때 Ubuntu 26.04가 필요한가요?
Docker 엔진 자체는 Ubuntu 24.04와 22.04에서도 지원됩니다. 컨테이너 안의 Ubuntu·ROS 버전이 호스트와 같을 필요는 없습니다. 다만 현재 배포하는 WWW-POSIM DEB와 설치 스크립트는 Ubuntu 26.04용입니다. 실행기 바이너리의 시스템 라이브러리 요구 사항도 있으므로, 이 DEB의 지원 범위를 이전 Ubuntu까지 넓혀 안내할 수는 없습니다. 24.04·22.04의 Docker 지원과 WWW-POSIM 설치 패키지의 호환성은 구분해서 확인하세요. Docker의 Ubuntu 지원 목록을 참고하세요.
계정 인증하고 실습 시작하기
설치하기에서 계정을 만드세요. 인증메일의 Verify email을 누른 뒤 앱에 로그인하세요. 메일이 없으면 스팸함도 확인하세요. 인증된 계정으로 로그인에 성공하면 앱이 운영체제의 자격 증명 저장소에 비밀번호를 저장할 수 있습니다.
로그인과 주기적인 사용 권한 확인에는 인터넷이 필요합니다. 엔진·지도·모델을 저장할 디스크 공간도 준비하세요.
작업공간 익히기를 마친 뒤 설치형 작업공간에서 제어를 따라 하세요. Create Python project는 기억된 작업 폴더에 예제를 추가합니다. 기본 위치는 문서 폴더의 WWW-POSIM입니다. Open ROS terminal, Open working directory, Open in VS Code로 같은 폴더에서 준비된 ROS 도구를 사용하세요.
그래픽 장치 선택하기
로컬 설정의 Graphics 기본값은 Automatic (recommended)입니다. 앱이 엔진 컨테이너에서 실제 EGL 그래픽 장치를 확인합니다. Windows NVIDIA 환경에서는 WSL의 D3D12 경로를 사용합니다. 하드웨어 렌더러를 확인하지 못하면 CPU 렌더링으로 실행하고 이유를 표시합니다.
GPU required는 GPU 확인에 실패하면 실행을 중단합니다. Software (CPU)는 CPU 렌더링을 선택합니다. Linux NVIDIA 환경은 호환 드라이버와 NVIDIA Container Toolkit이 필요합니다. Mac 기본 엔진은 Metal을 사용합니다.
Windows의 Docker 엔진은 WSL2 백엔드를 사용합니다. 앱의 시뮬레이터·ROS 터미널 열기·RViz 열기는 준비된 환경을 사용합니다. 별도 Ubuntu 배포판과 ROS 설치는 ROS 터미널과 연결을 쓸 때만 필요합니다. NVIDIA 드라이버는 Windows에 설치합니다.
설치형 작업공간의 장면은 로컬 Gazebo Ogre2가 렌더링합니다. 관찰용 카메라를 드래그하면 회전하고 스크롤하면 확대·축소합니다. 영상이 수신되지 않거나 오래되면 대기 상태를 표시합니다.
계정과 저장 공간 준비하기
플랫폼에서 이메일로 계정을 만듭니다. 설치형 앱도 실행 시간 권한을 확인하므로 로그인과 주기적인 갱신에 인터넷 연결이 필요합니다. 엔진, 지형 캐시와 사용자 모델을 저장할 디스크 공간을 준비하세요. 계정의 업로드 한도와 내 컴퓨터의 남은 공간은 별개입니다.
로그인한 뒤 작업공간 익히기에서 지역과 로봇을 선택합니다. 세션을 끝내면 서버 실행 공간을 반환하거나 로컬 엔진을 종료합니다.
업데이트하기
새 버전이 있으면 실행기와 설치형 앱의 시뮬레이터에 빨간 업데이트 안내가 표시됩니다. 설치된 버전과 새 버전을 확인할 수 있습니다. 지금 업데이트를 누르면 시뮬레이터에서는 설치 안내를 열고, 실행기에서는 검증된 파일을 내려받습니다. 시뮬레이터 안내의 ×를 누르면 해당 브라우저 탭에서 숨겨집니다. 더 새 버전이 나오면 다시 표시됩니다.
시뮬레이션을 끝내고 다음 방법으로 업데이트합니다.
- 앱: Update to 버전 선택
- Homebrew:
brew upgrade --cask www-posim - APT:
sudo apt update && sudo apt upgrade - 직접 설치: 현재 패키지 다운로드·설치
Mac 앱은 다운로드와 서명을 확인한 뒤 교체합니다. 엔진이 같으면 앱 파일만 내려받습니다. 앱 밖에 저장한 모델·지형 캐시·프로젝트는 유지됩니다.
별도의 ROS 컴퓨터는 연결 패키지와 호환 ROS 환경을 준비하세요. 설치 방법은 설치형 작업공간에서 제어를 참고하세요.
배포 엔진 이미지
설치형 앱은 설치된 버전에 맞는 엔진과 작업 화면 이미지를 Docker Hub에서 자동으로 내려받습니다. 레지스트리 로그인이나 이미지 URL 입력은 필요하지 않습니다. 네이티브 Mac 앱은 일치하는 엔진을 검증된 배포 파일 조각으로 내려받으며 Docker 이미지를 사용하지 않습니다. 이미지를 미리 내려받을 수도 있습니다.
docker.io/ioeslab/www-posim-engine:0.6.15-amd64
docker.io/ioeslab/www-posim-web:0.6.15-amd64
docker pull docker.io/ioeslab/www-posim-engine:0.6.15-amd64
docker pull docker.io/ioeslab/www-posim-web:0.6.15-amd64
Mac 앱 실행 문제 해결
이 배포본에는 Apple 공증이 없으므로 앱을 내려받거나 교체한 뒤 첫 실행 경고가 나올 수 있습니다. 위 안내에 따라 그래도 열기를 선택하세요. 버튼이 반응하지 않거나 앱이 Dock에만 표시되고 창이 열리지 않으면 macOS 앱 검증 서비스의 복구가 필요할 수 있습니다.
복구하기 전에 WWW-POSIM을 종료하세요. 시뮬레이션이 실행 중이지 않고 실행 창만 멈춘 경우에만 Apple 메뉴 → 강제 종료를 사용하세요. Mac을 재시작한 뒤 앱을 다시 여는 것이 가장 간단한 복구 방법입니다.
Mac을 재시작하지 않고 복구하려면 위의 공식 링크에서 받은 DMG인지 확인하고 공개된 SHA-256 체크섬과 비교하세요. shasum -a 256 뒤에 내려받은 DMG 경로를 입력하면 체크섬을 계산할 수 있습니다. 임시 서명(ad-hoc)은 파일 무결성을 확인하며, 배포자의 신원을 보증하지는 않습니다.
Mac 복구 도구를 다운로드 폴더에 저장하세요. 터미널을 열고 설치된 앱을 점검하세요.
bash "$HOME/Downloads/recover_macos_launch.command"
기본 점검은 앱 식별자와 서명을 확인하고 다운로드 격리 속성을 표시합니다. 차단된 실행을 복구하려면 다음 명령을 사용하세요.
bash "$HOME/Downloads/recover_macos_launch.command" --repair --restart-validation
안내를 읽고 TRUST WWW-POSIM을 입력하면 Apple 검증 경고가 있는 앱의 실행을 허용합니다. 도구는 선택한 앱의 격리 속성을 해제하고 macOS 앱 검증 서비스를 재시작한 뒤 앱을 엽니다. sudo가 요청하면 Mac 비밀번호를 직접 입력하세요. Gatekeeper는 켜진 상태로 유지됩니다. 실행 요청이 끝나면 실제로 앱 창이 나타나는지 확인하세요.
그래도 열기가 정상적으로 반응하고 검증 서비스를 재시작할 필요가 없으면 --repair만 사용하세요. Dev 앱에는 --app "/Applications/WWW-POSIM Dev.app"을 추가하세요. DMG의 README 옆에도 같은 도구가 있습니다. 별도로 내려받는 대신 bash 뒤에 해당 파일의 경로를 입력해 실행할 수 있습니다.
같은 실행 차단 문제를 수동으로 복구하려면 앱을 종료하고 공식 DMG의 체크섬을 확인한 뒤 터미널에서 아래 명령을 실행하세요. 무결성 검사가 성공하고 신뢰하는 앱일 때만 다음 단계로 진행하세요.
codesign --verify --deep --strict "/Applications/WWW-POSIM.app"
xattr -dr com.apple.quarantine "/Applications/WWW-POSIM.app"
sudo /usr/bin/killall -TERM syspolicyd
open -a "/Applications/WWW-POSIM.app"
검증 서비스를 재시작하면 다른 앱에서 대기 중인 보안 검사에도 영향을 줍니다. 해당 앱은 다시 열어야 할 수 있습니다. 복구되지 않으면 Mac을 재시작하세요. 서명 검사가 실패하면 공식 설치 파일을 새로 내려받으세요.