Multitap은 ToTBVDI의 새 이름입니다. 이 가이드는 현재 설치 파일의 이름인 ToTBVDI 1.0.0을 기준으로 합니다. 화면과 주소는 예시입니다.

2. 서버 설치와 기본 설정 — Docker

목표: 내 PC의 브라우저에서 ToTBVDI 관리자 화면에 로그인합니다. 준비된 Linux x64 서버에 설치합니다. 처음에는 Windows VM 한 대를 연결하는 데 집중하세요.

서버 공개 배포는 준비 중입니다. 이 장은 설치 구조를 살펴보거나 관리자가 배포본을 받은 경우에 쓰는 안내입니다. 공개 이미지·소스 배포가 확인되기 전에는 구성 예시만으로 설치를 완료할 수 없습니다.

먼저, 명령을 어디에 입력하나요?

이 장의 표시	열어 둘 곳
Linux 서버	서버에 SSH로 접속한 터미널, 또는 Proxmox에서 해당 Linux VM → Console
내 PC	지금 사용하는 PC의 브라우저나 PowerShell

Proxmox 노드의 Shell과 Linux VM의 Console은 다릅니다. 이 장의 Docker 명령은 ToTBVDI를 설치할 Linux 안에서 실행하세요.

명령 상자의 내용만 복사하세요. sh, powershell 같은 설명 글자는 입력하지 않습니다. 비밀번호를 입력할 때 글자나 *가 보이지 않아도 입력되고 있습니다.

192.0.2.10과 vdi.example.com은 예시입니다. 실제로 접속할 수 있는 주소가 아닙니다. 자신의 서버 IP와 도메인으로 바꾸세요. 처음 설정은 믿을 수 있는 내부망에서 진행하세요.

서버 설치

먼저 Linux에 ToTBVDI 서버를 설치하고 실행합니다. 서버가 실행되면 아래의 서버 기본 설정으로 넘어갑니다.

1단계. Linux 서버와 Docker 확인

작업 위치: Linux 서버

서버의 IP 주소를 확인하세요.
```
hostname -I
```
내 PC에서 접속할 수 있는 서버 IP를 메모하세요.
서버 배포판에 맞는 Docker 공식 안내를 여세요.
공식 안내의 저장소 설치 방식으로 Docker Engine을 설치하세요.
Compose 플러그인도 설치하세요.
Docker가 실행되는지 확인하세요.
```
sudo docker version
```
Compose가 있는지 확인하세요.
```
sudo docker compose version
```

완료 확인: Docker의 Client와 Server 정보가 나오고, Compose 버전도 나옵니다. 이 장의 sudo 비밀번호는 Linux 계정의 비밀번호입니다.

IP가 여러 개이거나 Docker 명령이 안 돼요

SSH로 접속했다면 그때 사용한 서버 IP와 대조하세요. Docker 내부 주소나 127.0.0.1을 서버 주소로 쓰지 마세요.
IP를 아직 모르겠으면 Linux를 설치한 관리자에게 내 PC에서 접속할 Linux 서버의 IP를 확인하세요.
docker: command not found: Docker 설치가 끝났는지 확인하세요.
Cannot connect to the Docker daemon: Docker 서비스가 시작됐는지 공식 설치 안내를 확인하세요.
docker: 'compose' is not a docker command: Compose 플러그인을 설치하세요.
sudo 권한이 없으면 서버 관리자에게 설치를 요청하세요.

기존 서버에서 다른 서비스가 Docker를 쓰고 있다면, 패키지 삭제·재설치를 임의로 진행하지 마세요.

2단계. 파일 두 개를 Linux 서버에 준비

작업 위치: Linux 서버

전용 폴더를 만드세요.
```
mkdir -p ~/totbvdi
```
그 폴더로 이동하세요.
```
cd ~/totbvdi
```
같은 ToTBVDI 배포본의 compose.yaml과 .env.example을 이 폴더에 넣으세요.

파일이 아직 내 PC에만 있어요 — 다운로드하고 서버로 옮기기

내 PC의 브라우저에서 진행하세요.

다운로드 페이지를 여세요.
compose.yaml과 .env.example의 예시 파일을 받으세요.
파일을 같은 폴더에 모으세요. .env.example로 저장되었는지 확인하세요.

이 파일은 구성 예시입니다. 서버 이미지와 소스의 공개 배포는 준비 중입니다. 관리자에게 실제 사용할 배포본과 버전을 받은 뒤 설치를 계속하세요.

이제 내 PC의 PowerShell에서 파일을 옮깁니다. Linux 서버에 SSH 접속이 가능해야 합니다. 리눅스아이디는 위에서 ~/totbvdi 폴더를 만든 계정과 같아야 합니다.

파일 탐색기에서 compose.yaml이 있는 폴더를 여세요.
탐색기 주소 표시줄에 powershell을 입력하세요.
Enter를 누르세요.
아래 명령의 리눅스아이디와 서버IP를 실제 값으로 바꾸세요.

바꾼 명령을 실행하세요.

scp .\compose.yaml .\.env.example "리눅스아이디@서버IP:totbvdi/"

Linux 계정의 비밀번호를 입력하세요.

처음 연결하는 서버라면 SSH 지문을 서버 콘솔의 정보와 비교한 뒤 승인하세요. 지문이 다르다는 경고가 나오면 검증을 끄지 말고 서버 관리자에게 확인하세요.

scp가 없다고 나오면 Windows OpenSSH 안내의 Get started with OpenSSH에서 클라이언트 설치를 확인하세요. scp는 SSH 연결로 파일을 복사하는 도구입니다(공식 설명).

Linux 서버의 터미널로 돌아와 파일을 확인하세요.

cd ~/totbvdi
ls -la compose.yaml .env.example

완료 확인: 두 파일의 이름이 모두 나옵니다. No such file or directory가 나오면 파일을 옮긴 위치를 먼저 확인하세요.

3단계. 설정 파일에 실제 서버 IP 입력

작업 위치: Linux 서버, ~/totbvdi 폴더

처음 설치라면 예시 파일을 복사하세요.
```
cp .env.example .env
```
설정 파일을 여세요.
```
nano .env
```
TOTBVDI_SERVER_ADDRESS= 줄을 찾으세요.
= 뒤에 1단계에서 확인한 실제 서버 IP를 넣으세요.
Ctrl+O를 눌러 저장하세요.
Enter를 눌러 파일명을 확인하세요.
Ctrl+X로 편집기를 닫으세요.

예를 들어 아래 줄의 192.0.2.10 자리를 실제 서버 IP로 바꿉니다.

TOTBVDI_SERVER_ADDRESS=192.0.2.10

이미 설치했던 서버라면 기존 .env를 열어 수정하세요. 예시 파일로 덮어쓰지 마세요. nano가 없다면 서버의 다른 편집기를 사용하세요. Ubuntu·Debian에서는 sudo apt install nano로 설치할 수도 있습니다.

완료 확인: 아래 명령을 실행했을 때 오류가 없으면 다음으로 갑니다. 정상일 때는 출력이 없습니다.

sudo docker compose config --quiet

4단계. 서버 시작

작업 위치: 먼저 Linux 서버

ToTBVDI 서버 프로그램을 받으세요.
```
sudo docker compose pull
```
서버를 시작하세요.
```
sudo docker compose up -d
```
상태를 확인하세요.
```
sudo docker compose ps
```

완료 확인: broker가 실행 중이고, 잠시 후 healthy가 표시됩니다. pull에서 실패하면 다음 단계로 넘어가지 말고 인터넷 연결과 배포 이미지의 버전을 확인하세요.

서버 기본 설정

서버 설치가 끝났습니다. 이제 관리자 계정 → 접속 주소 순서로 설정합니다. 이 설정까지 끝나야 Host와 클라이언트를 연결할 수 있습니다.

1단계. 첫 관리자 계정 설정

작업 위치: 내 PC의 브라우저

http://서버IP:18480을 주소 표시줄에 넣으세요.
아이디에 admin을 입력하세요.
비밀번호에 admin을 입력하세요.
로그인을 누르세요.

작업 위치: Linux 서버의 터미널

일회용 설정 코드를 확인하세요.

sudo docker compose logs broker | grep initial_setup

가장 최근 initial_setup_code의 setupCode 값을 확인하세요.

setupCode 오른쪽의 큰따옴표 안에 있는 코드만 입력합니다. 큰따옴표와 다른 로그 내용은 입력하지 마세요.

작업 위치: 다시 내 PC의 브라우저

설정 코드에 방금 확인한 값을 입력하세요.
새 관리자 아이디를 입력하세요.
새 비밀번호를 10자 이상 입력하세요.
비밀번호 확인에 같은 비밀번호를 입력하세요.
계정 변경하고 다시 로그인을 누르세요.
새 관리자 계정으로 로그인하세요.

완료 확인: admin / admin 대신 새 계정으로 관리자 웹에 들어갑니다. 아이디와 비밀번호를 둘 다 바꿔야 합니다.

최초 설정 전에는 서버를 다시 시작할 때마다 설정 코드가 바뀝니다. 최신 코드만 사용하세요. 코드나 코드가 들어 있는 로그를 다른 사람에게 보내지 마세요.

2단계. Host와 앱이 사용할 주소 적용

지금 열린 IP 주소는 첫 설정용입니다. 접속 주소를 적용해야 Host·클라이언트 연결과 다운로드를 사용할 수 있습니다.

같은 집·회사 내부망에서 먼저 연결하기

작업 위치: 내 PC의 관리자 웹

설정 → 서버 접속 설정을 여세요.
HTTP 주소 · 같은 네트워크용에 http://서버IP:18480을 입력하세요.
복사를 누르세요.

작업 위치: Linux 서버의 터미널

nano .env로 설정 파일을 여세요.
웹에서 복사한 항목과 이름이 같은 줄을 바꾸세요.
같은 설정 이름이 두 줄씩 생기지 않았는지 확인하세요.
Ctrl+O, Enter, Ctrl+X 순서로 저장하고 닫으세요.
변경한 설정을 적용하세요.
```
sudo docker compose up -d
```

필수 설정은 다음과 같습니다. 예시 IP를 실제 IP로 바꾸세요.

TOTBVDI_HTTP_ORIGIN=http://192.0.2.10:18480
TOTBVDI_ALLOW_INSECURE_HTTP=1
TOTBVDI_PUBLISH_PORT=0.0.0.0:18480

완료 확인: 내 PC에서 같은 HTTP 주소로 다시 로그인할 수 있고, /get/host에서 Host 다운로드가 시작됩니다. 화면에서 복사만 누른 상태는 설정 적용이 끝난 상태가 아닙니다.

HTTP는 암호화하지 않습니다. 믿을 수 있는 내부망에서만 사용하세요. 공유기의 TCP 18480을 인터넷으로 포트 전달하지 마세요.

Docker의 공개 포트는 UFW 같은 방화벽 규칙을 우회할 수 있습니다. 공유기·Proxmox 방화벽의 접근 범위도 확인하세요(Docker 공식 안내).

인터넷에서 접속하기 — HTTPS

도메인·유효한 인증서·HTTPS 리버스 프록시가 필요합니다. 리버스 프록시는 HTTPS 연결을 받아 ToTBVDI 서버로 전달하는 프로그램입니다.

HTTPS 설정 순서 — 프록시가 Linux 서버와 같은 컴퓨터에 있는 경우

도메인의 DNS를 외부에서 접속할 수 있는 서버 주소로 설정하세요.
프록시의 HTTPS 인증서를 설정하세요.
프록시의 전달 주소를 http://127.0.0.1:18480으로 설정하세요.
Host, X-Forwarded-Proto: https와 WebSocket의 Upgrade·Connection 헤더를 전달하세요.
프록시의 WebSocket 읽기 제한 시간을 충분히 길게 설정하세요.

구체적인 nginx 설정은 Docker 배포 문서에 있습니다.

Linux 서버에서 Docker 네트워크의 게이트웨이 주소를 확인하세요.

sudo docker network inspect totbvdi_default -f '{{range .IPAM.Config}}{{.Gateway}}{{end}}'

내 PC의 관리자 웹에서 진행하세요.

설정 → 서버 접속 설정을 여세요.
HTTPS 주소 · 도메인과 인증서에 실제 HTTPS 주소를 넣으세요.
복사를 누르세요.

Linux 서버에서 진행하세요.

nano .env를 여세요.
같은 이름의 설정을 복사한 값으로 바꾸세요.
TOTBVDI_TRUSTED_PROXIES에 방금 확인한 게이트웨이 IP를 넣으세요.
HTTPS만 쓴다면 TOTBVDI_PUBLISH_PORT=127.0.0.1:18480으로 바꾸세요.
저장하고 편집기를 닫으세요.
서버 방화벽에서 프록시의 TCP 443 접속을 허용하세요.
공유기를 쓴다면 외부 TCP 443을 프록시로 전달하세요.
sudo docker compose up -d로 적용하세요.
내 PC 브라우저에서 실제 HTTPS 주소로 로그인하세요.

TOTBVDI_PUBLIC_ORIGIN=https://vdi.example.com의 도메인을 실제 도메인으로 바꿔야 합니다. 이미 사용하던 Host·앱도 새 주소에서 연결 테스트를 하고 저장해야 합니다.

프록시가 다른 컴퓨터에 있다면 127.0.0.1 전달 주소를 그대로 쓰면 안 됩니다. 브로커의 실제 주소로 전달하고, TOTBVDI_TRUSTED_PROXIES에는 브로커에서 보이는 실제 프록시 주소를 넣으세요.

HTTP도 함께 쓰면 게시 주소는 0.0.0.0:18480으로 둡니다. HTTP에는 내부망만 접근하게 제한하세요. 프록시 없이 TLS를 직접 쓰려면 Docker 배포 문서를 확인하세요.

3단계. UDP 미디어 연결 — 기본 접속 후 설정 가능

UDP는 화면·소리를 전송하는 추가 경로입니다. 설정하지 않았거나 막혀 있어도 WebSocket 경로로 연결합니다.

서버 방화벽에서 UDP 18481을 허용하세요.
외부 접속에 공유기를 쓴다면 UDP 18481을 Linux 서버로 전달하세요.
Linux 서버의 .env에 아래 항목을 넣으세요.
vdi.example.com을 Host와 앱이 접속할 수 있는 실제 주소로 바꾸세요.
저장한 뒤 sudo docker compose up -d를 실행하세요.

TOTBVDI_UDP_HOST_RELAYS=vdi.example.com:18481
TOTBVDI_UDP_CLIENT_RELAYS=vdi.example.com:18481
TOTBVDI_UDP_MEDIA=on

내부망 HTTP 전용 설치라면 두 줄 모두 실제 서버 IP와 :18481을 사용하세요. 두 주소 목록을 모두 설정해야 합니다.

TCP 443과 UDP 18481은 별개입니다. UDP는 HTTPS 프록시와 별도로 전달하세요.

완료 확인: 나중에 스트리밍으로 연결한 뒤 연결 품질에서 UDP/TCP 경로를 확인합니다. 설정 파일 저장만으로 UDP 연결 성공을 판단하지 않습니다.

다음 장으로 가기 전

새 관리자 아이디와 비밀번호로 로그인했습니다.
Host·앱이 사용할 주소를 .env에 적용했습니다.
그 주소의 /get/host에서 다운로드가 시작됩니다.

여기까지 됐다면 3장: Proxmox 연결로 이동하세요. healthy는 서버의 실행 상태이며, 원격 Windows 화면의 준비 완료를 뜻하지는 않습니다.

계정과 VM 배정은 Docker 데이터 볼륨에 저장됩니다. 업데이트할 때 docker compose down -v를 실행하거나 볼륨을 삭제하지 마세요.

ToTBVDI 1.0.0 기준 · 화면과 주소는 예시입니다.