Linux에 Odysseus AI 설치하기: 네이티브와 Docker 전체 가이드

설치 전에 네이티브 또는 Docker를 선택하세요

문서화된 다중 서비스 스택, 재현 가능한 컨테이너, 호스트와의 분리가 필요하면 Docker가 기본 선택입니다. Python과 Uvicorn 프로세스를 직접 확인하거나 저장소 개발을 하거나 컨테이너 네트워크 없이 호스트 도구를 쓰려면 네이티브 방식이 적합합니다.

로컬 모델을 사용한다고 반드시 네이티브로 설치할 필요는 없습니다. 두 방식 모두 Ollama, vLLM, SGLang 또는 OpenAI 호환 엔드포인트에 연결할 수 있습니다. Docker도 GPU를 자동 활성화하지 않으므로 호스트 드라이버, 런타임, Compose 오버레이를 함께 검증해야 합니다.

Linux 설치 전 점검

복제하기 전에 브랜치, Python, 포트, 저장 공간, 추론 위치를 확인하세요. 공식 저장소는 최신 변경을 받는 dev를 기본 브랜치로 사용하고 main을 더 선별된 브랜치로 설명합니다. 2026년 7월 30일 기준 GitHub Releases, 버전 태그, 공식 바이너리가 없습니다. 따라서 이 페이지는 존재하지 않는 최신 버전이나 설치 파일을 제시하지 않습니다.

네이티브 방식에는 Python 3.11 이상이 필요합니다. Docker 방식은 Docker Engine과 Compose 플러그인을 확인하세요. APP_PORT를 바꾸지 않으면 7000 포트가 비어 있어야 합니다. 네이티브 Linux에서 Cookbook의 백그라운드 모델 다운로드와 실행을 사용하려면 공식 문서가 tmux도 요구합니다.

1. dev 또는 main 선택

   최신 변경은 dev, 더 선별된 흐름은 main을 선택합니다.

2. 모델 실행 위치 결정

   같은 호스트, 다른 서버, 호스팅 API 중 하나를 정합니다.

3. 포트 확인

   7000 포트를 확인하거나 다른 APP_PORT를 정합니다.

4. 첫 실행을 비공개로 유지

   생성된 비밀번호를 변경할 때까지 127.0.0.1만 사용합니다.

python3 --version
docker --version
docker compose version
ss -ltn | grep ':7000' || true

Odysseus AI Linux 네이티브 설치

네이티브 경로는 격리된 가상 환경을 만들고 의존성을 설치한 뒤 프로젝트 설정을 실행하고 Uvicorn으로 ASGI 앱을 시작합니다. 관리하는 폴더에서 일반 사용자로 실행하세요. sudo pip는 시스템 Python과 프로젝트 패키지를 섞어 업데이트와 제거를 어렵게 하므로 피해야 합니다.

첫 시작 명령은 루프백 주소에만 바인딩합니다. 초기 검증에는 이 설정이 맞습니다. 대화형 실행, 로그인, 모델 테스트가 성공한 뒤 systemd 같은 서비스 관리자를 추가하고 같은 작업 폴더, 가상 환경, 환경 변수를 사용하세요.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py

python -m uvicorn app:app --host 127.0.0.1 --port 7000

Docker Compose로 Odysseus AI 설치

공식 빠른 시작은 Docker를 권장합니다. .env.example 복사는 선택이지만 배포 설정을 명확하게 보여 줍니다. 컨테이너를 빌드하고 시작한 뒤 상태를 확인하고 Odysseus 로그에서 임시 관리자 비밀번호를 읽으세요.

Compose는 기본적으로 웹 UI를 127.0.0.1에 바인딩합니다. 7000 포트가 사용 중이면 .env에서 APP_PORT=7001 같은 빈 포트를 설정하고 컨테이너를 다시 만드세요. APP_BIND=0.0.0.0은 포트 충돌 해결책이 아닙니다.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

docker compose ps
docker compose logs odysseus --tail=120

모델을 추가하기 전에 첫 로그인을 확인하세요

Linux 호스트에서 http://localhost:7000을 여세요. 첫 설정은 관리자 계정을 만들고 임시 비밀번호를 터미널 또는 컨테이너 로그에 출력합니다. 로그인하고 설정에서 비밀번호를 바꾼 뒤 새 브라우저 세션에서도 접속되는지 확인하고 원격 공개로 진행하세요.

그다음 알려진 모델 엔드포인트 하나만 추가하고 짧은 요청을 보내세요. 화면은 열리지만 응답만 실패한다면 설치 자체는 정상일 가능성이 큽니다. URL, 인증 정보, 모델 이름, 방화벽, 모델 런타임을 확인하세요.

1. 로컬 페이지 열기

   localhost:7000의 로그인 화면을 확인합니다.

2. 생성 비밀번호 읽기

   터미널이나 로그에서 확인하고 기본 비밀번호를 추측하지 않습니다.

3. 인증 정보 변경

   LAN, VPN, 프록시를 사용하기 전에 바꿉니다.

4. 모델 하나 테스트

   알려진 엔드포인트와 짧은 프롬프트로 확인합니다.

GPU는 주로 모델 런타임의 선택입니다

Odysseus 워크스페이스는 비교적 가볍고 GPU 수요는 대부분 로컬 추론에서 발생합니다. 네이티브 방식은 호스트 Ollama에 직접 연결할 수 있고 Docker도 Docker 소켓을 마운트하지 않고 호스트 또는 원격 엔드포인트를 사용할 수 있습니다.

컨테이너에서 NVIDIA 또는 AMD를 쓰려면 먼저 호스트 드라이버와 패스스루를 확인하세요. 공식 진단 스크립트와 오버레이가 있습니다. 컨테이너에서 nvidia-smi가 성공해도 llama.cpp, vLLM, SGLang에 필요한 CUDA 또는 ROCm 라이브러리가 맞다는 뜻은 아닙니다.

scripts/check-docker-gpu.sh

http://host.docker.internal:11434/v1

Linux에서 Odysseus를 Tailscale에 안전하게 연결

Similarweb phrase match에서 connect odysseus to tailscale linux가 낮은 난이도의 보조 검색어로 확인되었습니다. 원격 접속은 로컬 설치가 끝난 뒤의 작업이므로 이 Linux 가이드 안에서 다루는 것이 맞고, 별도의 얇은 페이지를 만들 근거는 아닙니다.

앱을 0.0.0.0 또는 적절한 인터페이스에 의도적으로 바인딩하고 인증을 유지하며 Tailscale 정책이나 호스트 방화벽으로 기기를 제한하세요. 브라우저 기능이 보안 출처를 요구하면 HTTPS를 사용하고 앱이나 모델 포트를 인터넷에 직접 포워딩하지 마세요.

python -m uvicorn app:app --host 0.0.0.0 --port 7000

APP_BIND=0.0.0.0
AUTH_ENABLED=true

존재하지 않는 릴리스 번호 없이 안전하게 업데이트

2026년 7월 30일 기준 공식 Release나 버전 태그가 없습니다. dev는 빠르게 바뀌고 main은 더 선별됩니다. 따라서 최신 버전 번호, 파일 크기, 바이너리 설치 파일, 영구 직접 다운로드 주소를 주장하지 않습니다.

업데이트 전에 현재 브랜치를 기록하고 데이터와 .env를 백업하며 변경 사항을 읽고 같은 브랜치를 업데이트하세요. 관련 없는 유지보수 중 main에서 dev로 바꾸지 마세요. 재빌드 후 로그인, 모델, 네트워크 테스트를 반복합니다.

git status --short
git branch --show-current
git pull --ff-only
# Docker
docker compose up -d --build

Linux 설치 문제 해결 표

프로세스, 포트, 로그인, 모델 엔드포인트, 선택 서비스 순서로 확인하세요. 여러 계층을 동시에 바꾸면 원인을 놓치기 쉽습니다.