installation

설치

deb 파일 다운로드부터 라이센스 인증 · 설치 마법사까지의 전 과정.

최근 확인 버전: v5.0.0

Easy Trainer는 Ubuntu 22.04 이상에서 동작하는 Debian 패키지(.deb) 형태로 배포됩니다. 설치는 3단계로 끝납니다.

  1. deb 파일 다운로드 · 설치 — 파일 매니저에서 더블클릭
  2. 런처 첫 실행 — 애플리케이션 메뉴에서 클릭, 라이센스 키 입력
  3. 설치 마법사 — 학습 서버 옵션 선택, Docker 이미지 빌드

시스템 요구사항

항목최소권장비고
OSUbuntu 22.04 LTSUbuntu 22.04 / 24.04 LTS다른 배포판은 미지원
RAM8 GB16 GB+학습 시 더 많이 권장
저장 공간20 GB50 GB+Docker 이미지(~12 GB) + 데이터셋
GPUNVIDIA, VRAM 4 GB+NVIDIA, VRAM 8 GB+학습·추론 모두 GPU 필수
네트워크인터넷 연결5 Mbps+모듈 다운로드, OAuth 인증

설치

    1. deb 파일을 다운로드합니다.

      다운로드 페이지 또는 GitHub Releases에서 easytrainer_<버전>_amd64.deb를 받습니다.

      다운로드 페이지에서 easytrainer_*.deb 받기

    2. 파일 매니저에서 deb 파일을 더블클릭합니다.

      Ubuntu의 기본 패키지 인스톨러(Software Install)가 열립니다. 우클릭이 필요하다면 Open With Other Application → Software Install을 선택하세요.

      Ubuntu Software Install — 설치 버튼

      Install 버튼을 누르고 사용자 비밀번호를 입력하면 설치가 진행됩니다.

런처 첫 실행

    1. 애플리케이션 메뉴에서 Easy Trainer를 실행합니다.

      키보드의 Super 키(보통 Windows 로고)를 누르거나 Activities를 클릭한 뒤 Easy Trainer로 검색해서 아이콘을 클릭합니다.

      Activities에서 Easy Trainer 검색

      런처가 시작되면서 자동으로 다음 3가지를 점검합니다.

      • 데이터/프로젝트 경로 권한 (/opt/easytrainer/)
      • 라이센스 인증
      • Docker 설치 여부

      하나라도 실패하면 빨간 다이얼로그를 띄우고 종료합니다.

    2. 라이센스 키를 입력합니다.

      ET-XXXX-XXXX-XXXX 형태의 키입니다. 홈페이지에 로그인해 내 정보 → 내 라이센스 에서 확인하고 [복사] 버튼으로 복사할 수 있습니다.

      스크린샷 누락/docs/installation/04-license-dialog.png

      Easy Trainer 라이센스 인증 다이얼로그

      브라우저나 Google 로그인은 필요하지 않습니다. 대소문자와 하이픈은 자동으로 맞춰지므로 붙여넣기만 해도 됩니다.

설치 마법사

처음 실행이면 5단계 설치 마법사가 자동으로 열립니다.

    1. 소프트웨어 사용권 계약 (EULA)

      설치 마법사 EULA 페이지

      본문을 읽고 동의함 체크박스를 켠 뒤 다음.

    2. 설치 준비 — 저장 공간 확인

      저장 공간 확인 페이지

      현재 여유 공간이 20 GB 이상이어야 진행됩니다. 부족하면 다음 버튼이 비활성화됩니다.

    3. 학습 서버 옵션 선택

      학습 서버 옵션 선택

      학습을 어디서 돌릴지 선택합니다. 기본값은 원격 모드입니다.

      • 원격 모드 (기본값) — 이 PC에 학습 서버를 설치하지 않습니다. Easy Trainer가 제공하는 원격 학습 서버를 사용해 학습 작업을 실행합니다. 자체 GPU가 학습에 부족하거나 별도 학습 PC를 두기 부담스러울 때 권장됩니다.
      • 로컬 모드 — 같은 PC에 학습 서버까지 함께 설치됩니다. 외부 통신 없이 모든 학습이 로컬에서 처리됩니다. 자체 GPU가 충분하고 데이터를 외부로 보내고 싶지 않을 때 선택하세요.

    4. 설치 진행

      설치 진행률

      다음 작업이 순차로 진행됩니다.

      • [INSTALL] docker compose build --no-cache — Docker 이미지 빌드
      • [GPU] NVIDIA Container Toolkit 설치/구성 (GPU 자동 구성)
      • [POST] Running DB migrations — SQLite 스키마 생성
      • [POST] Bringing up service — backend / frontend / ros2 컨테이너 기동
      • [MODULE] (i/N) <module_name> 다운로드 중 — 필수 모듈 자동 설치
      • [TRAIN-SERVER] ... — 학습 서버 다운로드/설치 (로컬 모드일 때)

      평균 진행 시간은 10–15분입니다. 네트워크 / 디스크 속도에 따라 차이가 납니다.

    5. 완료

      설치 완료

      Easy Trainer 실행하기 체크박스를 그대로 두고 완료를 누르면 메인 런처가 뜹니다.

메인 런처

메인 런처 floating bar

floating bar의 5개 버튼:

버튼의미
UI화면 켜기 / 끄기
서버서버 켜기 / 끄기
ROSROS 2 켜기 / 끄기
✕ 서비스 종료종료 / 재실행
🗑 완전 삭제Easy Trainer를 이 PC에서 완전히 제거

위쪽 3개는 상태등을 겸합니다. 글자가 초록색이면 실행 중, 빨간색이면 중지된 상태이고, 누르면 그 하나만 켜지거나 꺼집니다. 셋 다 초록색이 되면 브라우저에서 http://localhost:5173으로 접속해 운영자 UI를 사용할 수 있습니다.

floating bar에 마우스를 올리면 오른쪽으로 패널이 펼쳐지고, 각 줄에서 실행 중 / 중지됨 상태와 시작 / 중지 버튼을 확인할 수 있습니다. 한 번에 하나씩만 처리되므로, 처리 중일 때는 끝날 때까지 기다렸다가 다음 버튼을 누르세요.

다음으로 빠른 시작 가이드를 따라 첫 데이터를 수집하고 학습까지 진행해 보세요.

자주 마주치는 문제

deb 파일을 GUI로 열 수 없을 때

App Center가 deb 파일을 처리하지 못하면 터미널에서 직접 설치할 수 있습니다.

sudo apt install ./easytrainer_<버전>_amd64.deb

런처가 "Docker가 설치되어 있지 않습니다"로 종료될 때

deb 패키지가 의존성 자동 설치에 실패한 경우입니다. 터미널을 열어 다음을 실행하세요.

sudo apt install -y docker.io docker-compose-plugin
sudo usermod -aG docker "$USER"

그리고 로그아웃 후 다시 로그인한 뒤 런처를 다시 실행합니다.

GPU가 컨테이너에서 안 보임

설치 마법사가 GPU 모드를 자동 구성하지만, 호스트의 NVIDIA 드라이버가 너무 오래되었거나 누락된 경우가 있습니다. 터미널에서 다음으로 확인합니다.

nvidia-smi

GPU 정보가 안 나오면 NVIDIA 드라이버를 설치한 뒤 PC를 재부팅합니다 (Software & Updates → Additional Drivers에서 GUI로 가능).

라이센스 키가 거부될 때

안내 문구뜻해결
이미 다른 PC에 설치되어 있습니다그 라이센스가 다른 PC에 묶여 있음홈페이지 내 정보 → 내 라이센스에서 [PC 해제] 후 재시도
이 PC에는 이미 다른 라이센스가 설치되어 있습니다이 PC가 다른 키로 활성화됨그 라이센스의 [PC 해제] 후 재시도
등록되지 않은 라이센스 키입니다오타이거나 없는 키홈페이지에서 키를 다시 복사
사용이 중지된 라이센스입니다관리자가 사용 중지함관리자에게 문의
만료된 라이센스입니다유효기간이 지남갱신 후 재시도
입력 시도가 너무 많습니다오타를 여러 번 반복함10분 뒤 재시도

화면 위에 노란 라이센스 안내 띠가 뜰 때

라이센스가 만료·중지됐거나, 라이센스 서버에 오랫동안 연결하지 못한 상태입니다. 이때는 새 수집·학습·실행을 시작할 수 없습니다. 다만 이미 돌고 있는 작업은 그대로 계속되므로, 진행 중인 학습이 있으면 끝날 때까지 기다려도 됩니다.

인터넷 연결이 끊겼던 경우에는 다시 연결되면 자동으로 풀립니다. 인터넷 없이도 14일까지는 정상 동작합니다.

5173 / 5000 포트 충돌

다른 프로세스가 같은 포트를 점유 중이면 컨테이너가 뜨지 않습니다. 가장 간단한 해결책은 PC 재부팅입니다.

재설치 / 제거

가장 단순한 방법은 런처 floating bar의 🗑 완전 삭제 버튼입니다. 누르면 확인 다이얼로그가 뜨고, 실수 방지를 위해 마지막에 삭제를 직접 입력해야 진행됩니다. Docker 컨테이너·이미지·볼륨, 데스크톱 아이콘, 설치된 패키지까지 한 번에 제거되고 런처가 종료됩니다.

확인 다이얼로그의 사용자 데이터 유지 체크박스를 켜면 데이터셋·학습된 모델·DB·설정을 보관소에 옮겨 두었다가 나중에 재설치할 때 런처가 자동으로 복원합니다.

관련 문서