12분 읽기 2026년 6월 22일

Odysseus AI Docker 설정: 워크스페이스를 공개하기 전 7가지 확인

Odysseus AI 저장소 복제, .env 생성, Compose 실행, 첫 관리자 비밀번호 확인, 호스트 Ollama 연결, 데이터 유지, 내부 서비스를 비공개로 두는 방법을 정리한 실전 가이드입니다.

Odysseus AI Wiki
Odysseus AI Wiki
공개 Odysseus README, Docker Compose 동작, 로컬 모델 라우팅, 커뮤니티 문제 사례를 바탕으로 한 비공식 편집 노트입니다.
Odysseus AI Docker 설정을 위한 저장소, 환경 파일, Docker Compose, 로컬 브라우저 흐름 그림
Docker 설정은 저장소, 환경값, Compose 서비스, 로컬 브라우저를 나누어 확인할 때 문제를 찾기 쉽습니다.

짧은 답: 처음 설치하는 대부분의 사용자는 Docker Compose 경로가 가장 깔끔합니다. 공식 저장소를 clone하고 .env.example을 .env로 복사한 뒤 docker compose up -d --build를 실행하고 localhost:7000을 엽니다. 첫 관리자 비밀번호는 docker compose logs odysseus에서 확인합니다. 인증, HTTPS, 포트, 모델 endpoint를 이해하기 전에는 공개하지 마세요.

이 가이드의 내용

Docker 경로는 호스트 운영체제에 모든 의존성을 설치하지 않고도 반복 가능한 로컬 Odysseus AI 스택을 만들 수 있다는 장점이 있습니다. 대신 컨테이너의 localhost, 볼륨 유지, 보조 서비스 포트 공개 같은 경계를 반드시 이해해야 합니다.

Docker를 선택할 때

Docker 경로는 호스트 운영체제에 모든 의존성을 설치하지 않고도 반복 가능한 로컬 Odysseus AI 스택을 만들 수 있다는 장점이 있습니다. 대신 컨테이너의 localhost, 볼륨 유지, 보조 서비스 포트 공개 같은 경계를 반드시 이해해야 합니다.

점검 순서는 앱 컨테이너, 모델 endpoint, 네트워크 공개입니다. 명령어는 번역하지 말고 주변 설명만 현지화합니다.

처음 설치하는 대부분의 사용자는 Docker Compose 경로가 가장 깔끔합니다. 공식 저장소를 clone하고 .env.example을 .env로 복사한 뒤 docker compose up -d --build를 실행하고 localhost:7000을 엽니다. 첫 관리자 비밀번호는 docker compose logs odysseus에서 확인합니다. 인증, HTTPS, 포트, 모델 endpoint를 이해하기 전에는 공개하지 마세요.

짧은 답

처음 설치하는 대부분의 사용자는 Docker Compose 경로가 가장 깔끔합니다. 공식 저장소를 clone하고 .env.example을 .env로 복사한 뒤 docker compose up -d --build를 실행하고 localhost:7000을 엽니다. 첫 관리자 비밀번호는 docker compose logs odysseus에서 확인합니다. 인증, HTTPS, 포트, 모델 endpoint를 이해하기 전에는 공개하지 마세요.

검증 가능한 순서로 Docker Compose 실행하기

복사한 명령어보다 공식 저장소에서 시작하세요. 브랜치, GPU 옵션, 포트, 서비스 이름은 빠르게 바뀔 수 있습니다.

Docker Desktop 또는 Docker daemon이 켜져 있고 저장소 폴더 권한 문제가 없는지 먼저 확인합니다.

1. 올바른 저장소 복제

공식 저장소를 사용하고 파일을 수정하기 전에 main 또는 개발 브랜치를 명확히 선택합니다.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

2. 환경 파일 생성

Compose와 앱이 명시적인 로컬 기본값을 읽도록 예제 파일을 복사합니다. .env는 공유하지 않습니다.

cp .env.example .env

3. 스택 빌드와 시작

첫 빌드는 이미지와 의존성을 내려받기 때문에 시간이 걸릴 수 있습니다. 완료 후 디버깅합니다.

docker compose up -d --build

4. 상태와 첫 인증 정보 확인

컨테이너가 정상일 때만 로컬 UI를 엽니다. 첫 관리자 비밀번호는 Odysseus 로그에 표시됩니다.

docker compose ps
docker compose logs odysseus

.env, 7000 포트, 실제 접근 대상을 이해하기

브라우저에서 필요한 것은 보통 웹 UI입니다. 공개 quick start는 http://localhost:7000을 기준으로 합니다.

Compose 보조 서비스는 UI가 동작한다고 해서 공개 진입점이 되면 안 됩니다.

설정 또는 점검 확인되는 것 피해야 할 것
.env를 예제에서 복사 앱이 명시적인 로컬 값을 읽는지 확인합니다. 알 수 없는 상속 환경변수로 실행하지 않습니다.
localhost:7000 브라우저가 예상 로컬 포트의 웹 UI에 접근합니다. 보조 서비스를 앱으로 착각하지 않습니다.
docker compose ps 각 서비스가 실행 중인지 또는 실패했는지 보입니다. 컨테이너가 정상 전 모델 설정을 바꾸지 않습니다.
logs odysseus 시작 경로와 첫 인증 정보가 보입니다. 비밀번호나 토큰이 있는 로그를 공유하지 않습니다.

컨테이너 localhost를 혼동하지 않고 호스트 Ollama 연결하기

Ollama는 대개 별도 모델 서버입니다. Odysseus가 컨테이너에 있고 Ollama가 호스트에 있으면 컨테이너의 localhost는 호스트가 아닙니다.

호스트에서 Ollama를 확인하고, 컨테이너에서 접근을 확인한 뒤 Odysseus AI에 endpoint를 저장하세요.

Odysseus AI Docker 컨테이너가 호스트 Ollama에 연결되는 다이어그램
가장 흔한 실수는 Ollama가 호스트에 있는데 컨테이너 localhost를 쓰는 것입니다.
Docker에서 호스트 Ollama로 가는 일반 endpoint
http://host.docker.internal:11434/v1
Odysseus 위치 Ollama 위치 먼저 테스트할 endpoint
Docker 컨테이너 호스트 머신 http://host.docker.internal:11434/v1
Docker 컨테이너 같은 Compose 네트워크 Compose 서비스 이름과 내부 포트를 사용합니다.
호스트 native 프로세스 같은 호스트 http://127.0.0.1:11434/v1
원격 서버 다른 머신 노출된 raw port 대신 HTTPS 또는 private network를 사용합니다.

리빌드, 업데이트, 재시작 후 남는 것을 파악하기

계정, 문서, 설정이 들어간 workspace는 더 이상 임시가 아닙니다.

Compose 명령은 결과가 다릅니다. 재시작과 볼륨 삭제는 전혀 다릅니다.

동작 사용 시점 위험
docker compose restart 스택이 이미 빌드되어 서비스만 재시작할 때. 낮음; 상태는 보통 유지됩니다.
docker compose pull && docker compose up -d --build 이미지를 갱신하고 현재 source로 rebuild할 때. 중간; 먼저 README를 읽습니다.
docker compose down 볼륨은 유지하고 컨테이너를 중지/제거할 때. 대체로 안전하지만 Compose를 확인합니다.
docker compose down -v 의도적으로 볼륨을 삭제해 reset할 때. 높음; workspace 상태가 삭제될 수 있습니다.

첫 부팅 문제 해결 표

빌드, 컨테이너 상태, 브라우저 접근, 인증 정보, 모델 라우팅을 분리해서 가장 먼저 실패한 층을 고칩니다.

증상 가능한 원인 첫 조치
Docker 명령을 찾을 수 없음 Docker Desktop 또는 daemon이 없거나 실행 중이 아니거나 shell에서 사용할 수 없습니다. Docker를 시작하고 docker version을 확인합니다.
빌드 성공 후 localhost:7000이 열리지 않음 컨테이너 시작 중, 다른 포트, 또는 서비스 비정상입니다. docker compose ps와 logs odysseus를 확인합니다.
첫 admin password가 보이지 않음 로그가 지나갔거나 기존 상태 또는 .env 설정이 있습니다. logs odysseus와 .env를 확인합니다.
Ollama는 호스트에서 되지만 Odysseus에서 실패 컨테이너가 host gateway 대신 localhost를 씁니다. host.docker.internal:11434/v1을 같은 실행층에서 테스트합니다.
정리 후 데이터가 사라짐 볼륨이 삭제되었습니다. 백업을 복원하고 의도 없는 down -v를 피합니다.

LAN, 터널, 리버스 프록시 전에 확인할 보안 목록

자가 호스팅 AI workspace는 파일, 프롬프트, 문서, 모델, 도구에 접근할 수 있습니다.

필요한 UI만 공개하고 내부 서비스는 숨기며, 인증 정보를 바꾸고 원격 접근에는 HTTPS를 사용합니다.

  1. 외부 접근 전 관리자 인증 정보를 변경합니다.
  2. Compose의 모든 host port binding을 확인합니다.
  3. ChromaDB, 모델 서버, 보조 서비스를 공개하지 않습니다.
  4. HTTPS와 신뢰할 수 있는 프록시를 사용합니다.
  5. .env, 로그, 비밀번호가 보이는 스크린샷을 공개하지 않습니다.
  6. 업데이트나 파괴적 정리 전 볼륨을 백업합니다.
안전한 기본값

인증, 포트, HTTPS, 방화벽, 모델 endpoint를 확인하기 전에는 localhost에 둡니다.

FAQ

깔끔한 첫 설치에는 보통 그렇습니다. GPU나 개발 작업은 네이티브 경로가 나을 수 있습니다.

.env에서 바꾸지 않았다면 http://localhost:7000입니다.

docker compose logs odysseus에서 확인합니다.

둘 다 가능하지만 Docker에서 호스트 Ollama로 갈 때는 host.docker.internal:11434/v1을 자주 씁니다.

아니요. 인증, HTTPS, 방화벽, 보조 서비스를 먼저 확인하세요.

볼륨을 백업하고 README를 확인한 뒤 의도적으로 rebuild하세요.

참고 자료

  1. Official Odysseus AI GitHub repository - Current README, Docker quick start, feature list, and security notes.
  2. Docker Compose documentation - Reference for Compose commands, services, networks, and volumes.
  3. Docker Desktop networking documentation - Host-to-container and container-to-host networking behavior.
  4. Ollama API documentation - Endpoint checks for local model server connectivity.

관련 가이드

최종 업데이트: 2026년 6월 22일

Odysseus AI Wiki로 돌아가기