설치하기

1. 설치 명령 받기

1. 공급자 승인을 받은 계정으로 콘솔에 로그인합니다.
2. 「서버 관리」에서 「노드 추가」를 엽니다. 노드 이름은 내 노드끼리 겹치지 않게 정하고, 지역은 비워 둬도 됩니다.
3. 설치 명령이 한 번 표시됩니다. 복사해 두세요 — 이 화면을 벗어나면 다시 볼 수 없습니다.

• 명령 안의 등록 토큰은 서버 한 대에 한 번만 쓸 수 있고, 24시간 뒤 만료됩니다.
• 명령을 잃어버렸거나 만료됐다면 그 노드의 상세 화면에서 등록 토큰을 재발급받습니다.
• 재발급한 새 토큰으로 재설치가 성공하는 순간 그 서버의 기존 연결 키가 무효가 됩니다. 재설치가 실패하면 기존 등록은 그대로입니다.

실행 전에 선행 조건 확인하기 — 시작하기 전에

2. 실행하기

등록할 서버의 터미널에 콘솔에서 복사한 명령을 그대로 붙여넣습니다. 명령의 모양은 아래와 같습니다.

curl -fsSL <공개 사이트 주소>/install.sh | sudo bash -s -- --token=wwe_…

필요하면 명령 끝에 아래 인자를 덧붙입니다.

• --port-range=START-END — 인스턴스에 쓸 포트 범위입니다. 기본은 30000-31000이고, GPU 1장당 3개 이상이어야 합니다(1024~65535).
• --yes — 방화벽 적용 · 재등록 확인을 묻지 않고 진행합니다.
• --accept-hold — XFS 프로젝트 쿼터가 없어도 등록합니다. 서버가 등록을 보류합니다.
• --node-name=NAME — 진단용 노드 이름입니다. 기본은 서버의 호스트 이름입니다.
• --help — 도움말을 출력합니다.

curl -fsSL <공개 사이트 주소>/install.sh | sudo bash -s -- --token=wwe_… --port-range=30000-30099

지원하는 환경은 아래 한 줄입니다.

지원: Ubuntu 22.04 · 24.04 LTS · x86_64 · systemd

3. 스크립트가 하는 일

스크립트는 0 ~ 14 단계를 차례로 출력하며 진행합니다. 크게 다섯 덩어리입니다.

1. 검사 (0 ~ 7 단계) — 인자와 root 권한 · OS · 필요한 도구 · 드라이버 · Docker · Container Toolkit · ufw/firewalld · 포트 범위 · 디스크 XFS 쿼터 · 컨트롤 플레인 연결. 문제가 있으면 여기서 멈춥니다. 새로 설치하는 서버에서 Docker · Container Toolkit 이 없으면 설치하지만, NVIDIA 드라이버가 없으면 설치 명령을 안내하고 멈춥니다(종료 코드 18) — 「이 스크립트는 NVIDIA 드라이버를 설치하지 않습니다 — 아래 명령을 직접 실행해 주세요.」 안내한 명령을 직접 실행하고 재부팅한 뒤 같은 명령을 그대로 다시 실행하면 이어서 진행합니다. Docker 를 새로 깔면 스토리지 드라이버를 overlay2 로 고정합니다(이미지 · 컨테이너가 없는 빈 Docker 도 같습니다) · 이미지나 컨테이너가 있는 Docker 가 containerd 이미지 스토어면 멈추고 안내합니다(종료 코드 17).
2. 설치 (8 ~ 11 단계) — 에이전트를 받아 SHA-256을 확인하고 /usr/local/bin/wattworks-agent에 둡니다. 설정 파일(/etc/wattworks/agent.env) · 방화벽 규칙 · 서비스 유닛을 설치합니다.
3. 등록 (12 단계) — 등록 토큰을 딱 한 번 써서 노드를 등록합니다. 자동으로 다시 시도하지 않습니다.
4. 기동 (13 단계) — wattworks-agent.service를 켜고 계속 켜져 있는지 확인합니다.
5. 결과 (14 단계) — 등록 결과 · 포트 포워딩 안내 · 콘솔 주소를 출력합니다.

4. 확인 질문

10 단계에서 스크립트는 적용할 방화벽 규칙을 요약해 보여 주고 「이 규칙을 적용할까요?」라고 묻습니다. 이미 등록된 서버에 새 토큰으로 실행하면 11 단계에서 「재등록할까요?」도 묻습니다. y를 입력해야 진행합니다.

• --yes를 붙이면 묻지 않고 진행합니다.
• 터미널이 없는 환경에서 --yes 없이 실행하면 질문할 수 없어 멈춥니다(종료 코드 4). 토큰은 쓰이지 않습니다.
• 적용하는 규칙은 WattWorks 전용 체인뿐이고, 기존 INPUT 정책과 규칙은 바꾸지 않습니다.

규칙이 무엇을 막는지 — 보안 안내

5. 결과 읽기

끝까지 진행하면 14 단계에서 결과를 출력합니다.

• 등록 완료 — 「슬롯은 판매 일시중지 상태로 만들어졌습니다. 콘솔에서 가격을 확인하면 공개됩니다.」 콘솔 「서버 관리」에서 가격을 확인하세요.
• 보류 — 「등록됐지만 보류입니다」 아래에 사유 문장이 나오고 「고친 뒤 콘솔에서 토큰을 재발급하고 이 명령을 다시 실행하세요.」로 끝납니다.
• 정지 — 「운영팀이 정지한 노드입니다」가 나오면 운영팀에 문의하세요.
• 상태 모름 — 콘솔에서 노드 상태를 확인하세요.

이어서 포트 포워딩 안내가 나옵니다 — 인스턴스 접속용 포트 범위(기본 30000-31000)와 노드 HTTPS 30443을 공유기 · 클라우드 보안 그룹에서 이 서버로 넘기라는 내용입니다. 그 아래 「IPv6(ip6tables) 방화벽 규칙은 만들지 않았습니다.」 한 줄이 함께 나옵니다.

서비스 상태와 로그는 아래 명령으로 봅니다.

systemctl status wattworks-agent.service
journalctl -u wattworks-agent.service -f

포트 포워딩

검증 통과하기

6. 실패했을 때 — 종료 코드

스크립트는 멈출 때 마지막 줄에 「(종료 코드 N)」을 출력하고, 토큰 상태도 한 줄로 알려 줍니다. 「등록 토큰은 쓰이지 않았습니다」가 보이면 문제를 고친 뒤 같은 명령을 그대로 다시 실행하면 됩니다. 0 · 16 · 18은 실패가 아닙니다 — 16은 재부팅하고, 18은 안내한 명령으로 드라이버를 설치하고 이어서 진행하라는 뜻입니다.

• 0 등록 완료 (토큰 없이 실행했다면 업데이트 완료) — 토큰: 쓰였음 · 다음: 콘솔 「서버 관리」에서 슬롯 가격을 확인하면 공개됩니다.
• 2 인자 · root 권한 · 토큰 형식 오류, 또는 등록되지 않은 서버에서 토큰 없이 실행 — 토큰: 살아 있음 · 다음: 콘솔의 명령을 그대로 붙여넣었는지, 명령에 sudo bash가 있는지 확인하고 다시 실행하세요.
• 3 지원하지 않는 OS · 필요한 도구 없음 · 다른 설치가 실행 중 — 토큰: 살아 있음 · 다음: Ubuntu 22.04 · 24.04 LTS x86_64에서 실행하세요. 도구가 없으면 화면에 나온 apt-get install 한 줄을 실행한 뒤 다시 실행하세요.
• 4 확인 질문에 「예」라고 답하지 않았거나 질문할 터미널이 없음 — 토큰: 살아 있음 · 다음: 터미널에서 직접 실행하거나, 내용을 확인했다면 명령 끝에 --yes를 붙여 다시 실행하세요.
• 5 선행 조건(NVIDIA 드라이버 · Docker · Container Toolkit · Caddy)을 갖추지 못했거나 자동 설치가 실패함(새로 설치하는 서버에서 드라이버만 없을 때는 18) — 토큰: 살아 있음 · 다음: 화면에 「선행 조건을 갖추지 못했습니다 — 없거나 자동 설치가 실패했습니다.」와 함께 원인이 나옵니다 — .run 설치 파일로 깐 드라이버 · 드라이버 판본이 하한에 못 미침 · Docker · Container Toolkit · Caddy 설치 실패 · 이미 등록된 서버(재등록)에서 드라이버 없음. 고친 뒤 같은 명령을 다시 실행하세요(24시간이 지났으면 재발급).
• 6 ufw 또는 firewalld가 켜져 있음, 또는 Docker 데몬의 IPv6가 켜져 있음 — 토큰: 살아 있음 · 다음: ufw · firewalld는 비활성화하거나 운영팀에 문의한 뒤 같은 명령을 다시 실행하세요. IPv6라면 「Docker 의 IPv6 를 끄고 같은 명령을 다시 실행하세요.」 스크립트는 둘 다 자동으로 바꾸지 않습니다.
• 7 포트 범위가 GPU 수 × 3보다 작음 — 토큰: 살아 있음 · 다음: 화면의 예시처럼 --port-range를 넓혀 다시 실행하세요. 공유기 포트 포워딩 규칙도 같은 범위로 맞춥니다.
• 8 디스크에 XFS 프로젝트 쿼터(pquota)가 없음 — 토큰: 살아 있음 · 다음: 디스크를 재구성한 뒤 같은 명령을 다시 실행하거나, 보류를 감수하고 --accept-hold를 붙여 실행하세요.
• 9 WattWorks 컨트롤 플레인에 연결하지 못함 — 토큰: 살아 있음 · 다음: DNS · 나가는 방향의 방화벽 · 프록시 · 서버 시계(date)와 CA 인증서를 확인하고 다시 실행하세요.
• 10 · 11 · 12 · 13 에이전트 받기 · 설정 파일 · 방화벽 적용 · 서비스 유닛 설치 실패 — 토큰: 살아 있음 · 다음: 화면의 문장을 확인하고 같은 명령을 다시 실행하세요. 반복되면 종료 코드와 함께 운영팀에 문의하세요.
• 14 등록은 끝났지만 에이전트 서비스가 켜지지 않음 — 토큰: 쓰였음 · 다음: journalctl -u wattworks-agent.service -n 30 --no-pager로 원인을 확인해 고친 뒤, 토큰 없이 다시 실행하세요.
• 15 토큰 없이 실행했는데 저장된 포트 범위와 --port-range가 다름 — 토큰: 쓰이지 않음 · 다음: 포트 범위를 바꾸려면 콘솔에서 등록 토큰을 재발급받아 새 명령과 함께 실행하세요.
• 16 실패가 아닙니다 — 「드라이버 패키지는 설치돼 있으나 커널 모듈이 올라오지 않았습니다 — 적용하려면 재부팅이 필요합니다.」 설치가 이어지는 중입니다 — 토큰: 살아 있음 · 다음: sudo reboot로 재부팅한 뒤 같은 명령을 그대로 다시 실행하세요. 이미 설치된 것은 건너뜁니다. 재부팅하지 않고 다시 실행하면 같은 16이 나옵니다.
• 17 「Docker 스토리지 드라이버가 overlay2 가 아니라 디스크 쿼터를 걸 수 없습니다」 — Docker 가 containerd 이미지 스토어라 인스턴스 디스크 상한이 걸리지 않음 — 토큰: 살아 있음 · 다음: 이미 깔려 있던 Docker 에 이미지나 컨테이너가 있으면 스크립트는 설정을 바꾸지 않습니다 — 화면의 안내대로 /etc/docker/daemon.json에 "features": { "containerd-snapshotter": false }를 더하고 sudo systemctl restart docker 한 뒤 같은 명령을 다시 실행하세요. 스토어를 바꾸면 기존 이미지는 다시 받아야 합니다. 스크립트가 Docker 를 새로 깔았거나 이미지 · 컨테이너가 없는 빈 Docker 라면 overlay2 로 고정한 뒤 확인까지 하므로, 이 코드가 나오면 화면의 확인 명령(docker info --format '{{.Driver}}')으로 원인을 보고 운영팀에 문의하세요.
• 18 실패가 아닙니다 — 「NVIDIA 드라이버 설치가 필요합니다 — 위에 안내한 명령을 실행하고 재부팅한 뒤, 같은 명령을 그대로 다시 실행하세요.」 스크립트는 NVIDIA 드라이버를 설치하지 않습니다 — 토큰: 살아 있음 · 다음: 화면에 안내된 두 명령 sudo apt-get update && sudo apt-get install -y ubuntu-drivers-common · sudo ubuntu-drivers --gpgpu install && sudo reboot을 서버에서 직접 실행합니다 — Ubuntu 공식 저장소의 드라이버 패키지가 설치되고 재부팅합니다. 재부팅한 뒤 같은 명령을 그대로 다시 실행하세요. 이미 설치된 것(Docker · Container Toolkit · Caddy)은 건너뜁니다. Secure Boot가 켜진 서버라면 화면에 함께 나오는 주의 줄을 따르세요(① BIOS/UEFI에서 Secure Boot를 끄거나 ② 콘솔에서 MOK을 등록). 드라이버를 설치하지 않고 다시 실행하면 같은 18이 나옵니다.
• 30 등록됐지만 보류 (pending_review) — 토큰: 쓰였음 · 다음: 화면의 보류 사유를 고친 뒤 콘솔에서 토큰을 재발급하고 다시 실행하세요.
• 31 운영팀이 정지한 노드 — 토큰: 쓰였음 · 다음: 운영팀에 문의하세요.
• 32 등록됐지만 상태를 알 수 없음 — 토큰: 쓰였음 · 다음: 콘솔 「서버 관리」에서 노드 상태를 확인하세요.
• 40 등록 토큰이 틀렸거나 만료됨 — 토큰: 쓰이지 않음 · 다음: 콘솔에서 등록 토큰을 재발급받아 새 명령으로 실행하세요.
• 41 이미 쓴 토큰 — 토큰: 쓰였음 · 다음: 이 서버가 이미 등록됐다면 토큰 없이 다시 실행하면 업데이트만 합니다. 아니라면 콘솔에서 재발급하세요.
• 42 · 44 · 45 · 46 설치 파일 · 스크립트 · 에이전트 쪽 문제로 등록 요청이 거절되거나 보내지지 않음 — 토큰: 쓰이지 않음 · 다음: 화면의 문장을 확인하세요. 다른 등록이 실행 중이거나 디스크 문제라고 나오면 고친 뒤 다시 실행하고, 그 밖에는 종료 코드와 함께 운영팀에 문의하세요.
• 43 서버가 Mock 노드 등록을 받지 않음 — 토큰: 쓰이지 않음 · 다음: 이 서버에서 NVIDIA 드라이버가 로드됐는지(/dev/nvidiactl 또는 /dev/nvidia0) 확인한 뒤 다시 실행하세요.
• 50 컨트롤 플레인의 응답을 받지 못함 — 토큰: 모름 · 다음: 자동으로 다시 시도하지 않습니다. 같은 명령을 한 번 더 실행하면 서버가 이미 등록됐는지 알려 줍니다.
• 51 등록은 됐지만 키를 저장하지 못함 — 토큰: 쓰였음 · 다음: 디스크(/etc/wattworks)를 확인하고 콘솔에서 토큰을 재발급한 뒤 다시 실행하세요.
• 59 등록 결과를 해석하지 못함 — 토큰: 모름 · 다음: 콘솔 노드 목록에서 이 서버가 보이는지 확인하고, 종료 코드와 함께 운영팀에 문의하세요.
• 130 · 143 중단 신호(Ctrl+C 등)로 멈춤 — 토큰: 모름 · 다음: 화면 마지막의 토큰 문장을 따르세요. 쓰이지 않았다면 같은 명령을 다시 실행하면 이어서 진행합니다.

검증 통과하기

시작하기 전에

보안 안내

포트 포워딩

디스크 준비

7. 다시 실행하기

같은 서버에서 다시 실행하면, 이미 등록됐는지와 토큰이 있는지에 따라 동작이 넷으로 나뉩니다.

• 등록 안 된 서버 · 새 토큰 — 새 설치입니다. 0 ~ 14 단계를 모두 진행합니다.
• 등록된 서버 · 토큰 없음 — 업데이트입니다. 에이전트 · 설정 · 방화벽 · 유닛을 새로 쌓고 서비스를 다시 켭니다. 선행 조건 · 포트 · 디스크 검사는 경고만 합니다. 저장된 포트 범위와 다른 --port-range를 주면 멈춥니다(종료 코드 15).
• 등록된 서버 · 새 토큰 — 재등록입니다. 확인 질문 뒤 새 토큰으로 등록합니다. 성공하면 옛 키는 무효가 되고, 실패하면 기존 등록으로 에이전트를 다시 켭니다. 포트 범위를 바꾸는 방법도 이것입니다.
• 등록 안 된 서버 · 토큰 없음 — 「이 서버는 아직 등록되지 않았습니다.」가 나오고 멈춥니다(종료 코드 2).

이미 쓴 토큰으로 다시 실행하면 「이 토큰은 이미 쓰였습니다.」가 나옵니다(종료 코드 41). 이 서버가 이미 등록됐다면 --token 없이 다시 실행하면 업데이트만 합니다.

8. 등록 토큰의 흔적

• 스크립트는 등록 토큰을 에이전트에 표준 입력으로만 넘기고, 설정 파일 · 서비스 유닛 · 로그에 쓰지 않습니다.
• 명령에 붙인 토큰은 실행 중에는 프로세스 인자로, 끝난 뒤에는 셸 히스토리에 남습니다. 스크립트가 지울 수 없습니다.
• 등록이 끝나면 결과 끝에 「등록 토큰은 이미 쓰였습니다 — 셸 히스토리에 남아도 다시 쓸 수 없습니다.」가 나옵니다.