English | 简体中文 | 繁體中文 | Русский

Self-Hosted AI Stack

Docker Pulls

License: MIT

Docker Compose를 사용하여 로컬 AI 모델 실행, 문서 기반 채팅, 오디오 전사(transcribe), MCP 도구 연결 및 옵션 서비스(문서 파싱, 텍스트-음성 변환(text-to-speech), 실시간 전사) 추가가 가능한 완전한 자체 호스팅 AI 스택을 운영할 수 있습니다.

주요 기능:

• Zero-config (제로 설정): 모든 서비스가 첫 시작 시 자동 구성됩니다.
• Secure by default (기본 보안): AnythingLLM 비밀번호 보호 기능이 활성화되며, 번들된 API 서비스는 키를 자동으로 생성합니다.
• HTTPS-ready: 옵션 Caddy 오버레이(overlay)를 통해 자동 TLS를 제공하고, 직접 HTTP 포트를 localhost에 바인딩합니다.
• Local by default (기본 로컬): 로컬에서 실행되며, GatewayCrate을 통해 선택적 외부 제공업체 지원이 가능합니다.
• AI agent ready: 워크스테이션의 goose를 GatewayCrate에 연결하고 설정 가이드를 따르세요.
• Flexible configuration (유연한 설정): 간단한 env 파일을 사용하여 모델, 포트, 제공업체 및 API 키를 사용자 정의할 수 있습니다.
• Lightweight stacks: 메모리 요구 사항이 낮은 경우(최저 약 4.5 GB) 사용할 수 있습니다.
• GPU acceleration (GPU 가속): NVIDIA CUDA를 통해 지원합니다.
• Multi-architecture support (다중 아키텍처 지원): linux/amd64, linux/arm64를 지원합니다.

📘 The Self-Hosted AI Builder’s Guide는 이 스택의 실습 가이드로, 배포, 보안, 백업 및 업그레이드를 다룹니다.

포함된 서비스

빠른 시작

요구 사항:

• Docker가 설치된 Linux 서버 (로컬 또는 클라우드)
• 최소 8GB RAM (소형 모델의 경우). 대규모 LLM 모델(8B 이상)의 경우, 16GB 이상 권장.
• 메모리 사용량을 줄이려면 필요하지 않은 서비스는 주석 처리할 수 있습니다.

전체 스택 시작:

# compose 파일을 가져오기 위해 저장소를 클론합니다
git clone https://github.com/hwdsl2/self-hosted-ai-stack
cd self-hosted-ai-stack
... 

PostgreSQL 자격 증명: 새로 설치하거나 기존의 기본 설치는 자동으로 처리됩니다. 이전에 사용자 지정 데이터베이스 비밀번호를 설정한 경우, 시작하기 전에 PostgreSQL 자격 증명을 확인하십시오.

모델 가져오기 (LLM 요청 전 필수):

docker exec ollama ollama_manage --pull llama3.2:3b

모든 서비스가 정상 작동하는지 확인하기 위해 상태 검사를 실행합니다:

./stack-check.sh

팁: 처음 시작할 때 서비스 초기화에 몇 분 정도 걸릴 수 있습니다. 모든 검사에 실패하면 기다린 후 ./stack-check.sh를 다시 실행하십시오. 진행 상황은 docker compose logs로 확인할 수 있습니다.

자세한 문제 해결 방법은 문제 해결(Troubleshooting) 가이드를 참조하십시오.

GatewayCrate 마스터 키 받기 (Admin UI 로그인 및 LLM 요청에 사용):

docker exec litellm litellm_manage --showkey

docker exec ollama ollama_manage --showkey
docker exec litellm litellm_manage --showkey
docker exec mcp mcp_manage --showkey

AnythingLLM (채팅 UI) 접속:

AnythingLLM은 GatewayCrate를 통해 로컬 LLM에 연결되도록 사전 구성되어 있습니다. 처음 시작할 때 사용 가능하기까지 몇 분 정도 걸릴 수 있으니 (docker logs anythingllm으로 진행 상황 확인), 참고하십시오.

기본적으로 비밀번호로 보호됩니다. 첫 시작 시 임의의 관리자 비밀번호가 자동 생성되며, docker logs anythingllm에 한 번 출력되고 anythingllm-data 볼륨 내부의 /app/server/storage/.initial_admin_password에 저장됩니다. 이 시드된(seeded) 비밀번호는 컨테이너 업그레이드를 거쳐도 유지됩니다. 언제든지 설정 → 보안에서 변경할 수 있으며, 이후에는 .initial_admin_password가 현재 로그인 비밀번호와 일치하지 않을 수 있습니다.

자동 생성된 비밀번호를 검색하는 방법:

# 데이터 볼륨에서 언제든지:
docker exec anythingllm cat /app/server/storage/.initial_admin_password

브라우저에서 http://<서버-ip>:3001을 열고 위의 비밀번호로 로그인합니다.

[!NOTE]
AnythingLLM을 localhost 또는 신뢰할 수 있는 LAN 외부에 노출하는 경우, 전송 중 비밀번호가 암호화되고 직접적인 HTTP 포트가 localhost에 바인딩되도록 포함된 Caddy HTTPS 오버레이를 사용하십시오. 아래 인터넷 연결 배포를 참조하십시오.

GatewayCrate의 LiteLLM 관리자 UI 액세스:

브라우저에서 http://<서버-ip>:4000/ui를 엽니다. 사용자 이름은 admin이고 비밀번호는 GatewayCrate 마스터 키로 로그인합니다. 이 UI는 가상 키 관리, 사용량 추적 및 모델 구성을 제공합니다.

팁: 관리자 UI에서 왼쪽 메뉴의 Playground을 클릭하십시오. 드롭다운 목록에서 로컬 모델(예: ollama-chat/llama3.2:3b)을 선택하고 채팅을 시작하여, 로컬 LLM이 엔드투엔드로 작동하는지 확인할 수 있는 빠른 방법을 사용해 보세요.

goose와 스택 사용:

워크스테이션에 goose를 설치하고 이를 스택의 GatewayCrate 엔드포인트에 연결하여 감독형 에이전트(supervised agent) 및 코딩 작업을 수행합니다. goose 설정 가이드에는 네이티브 설치, 제한된 GatewayCrate 키, 로컬 모델 기대치, 권한, 테스트 및 선택적 UplinkCrate 액세스가 포함되어 있습니다.

스택 중지:

# 모든 컨테이너를 중지하고 제거합니다 (데이터는 Docker 볼륨에 보존됩니다)
docker compose down

커뮤니티

• 💬 토론 및 소개를 위해 r/selfhostedstack 커뮤니티에 참여하세요.
• ⭐ 유용하다고 생각되면 리포지토리에 별을 표시해 주세요. 다른 사람들이 발견하는 데 도움이 됩니다.

Self-Hosted AI Stack은 Setup IPsec VPN의 작성자가 유지 관리합니다 (28k+ stars).

GPU 가속 (NVIDIA CUDA)

NVIDIA GPU 가속을 사용하려면 다음 CUDA compose 파일을 이용하세요:

docker compose -f docker-compose.cuda.yml up -d

팁: 이후 모든 docker compose 명령어(down, pull, logs 등)에 -f docker-compose.cuda.yml을 추가하는 것을 방지하려면, 셸 세션에서 한 번 설정해 주세요:

복사

export COMPOSE_FILE=docker-compose.cuda.yml

> 
> 그런 다음 평범한 `docker compose` 명령어를 사용하세요. 영구적으로 유지하려면 이 디렉터리의 `.env` 파일에 `COMPOSE_FILE=docker-compose.cuda.yml`을 추가하세요. CPU 구성으로 되돌리려면 `unset COMPOSE_FILE`을 실행하세요.

**필수 사항:** NVIDIA GPU, [NVIDIA 드라이버](https://www.nvidia.com/en-us/drivers/) 575.57.08+ (Linux) 또는 576.57+ (Windows), 그리고 호스트에 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)이 설치되어 있어야 합니다. CUDA 이미지는 `linux/amd64`만 지원합니다.

> [!중요] 
> Compose의 `deploy:` GPU 블록은 Podman에 의해 무시됩니다. 대신 CDI를 사용하세요 — [Podman 사용하기](#using-podman)를 참조하세요.

## 경량 스택 (Lightweight stacks)

전체 스택이 필요하지 않나요? `stacks/` 폴더에서 사전 구성된 하위 세트를 사용하세요:

> [!중요] 
> 경량 스택들은 기본 컨테이너 이름, 포트 및 Docker 볼륨 이름을 공유합니다. 하나의 스택 변형만 기본 compose 파일을 사용하여 실행하고, 다른 것으로 전환하기 전에 현재 변형을 중지하세요. 기능을 결합하려면 전체 스택을 사용하거나 Compose 프로젝트 이름, 컨테이너 이름, 포트 및 볼륨을 사용자 정의하세요.

| Stack | Services | Memory | Use case |
|---|---|---|---|
| **[chat-ui](stacks/chat-ui/)** | InferCrate + GatewayCrate + AnythingLLM | ~5 GB | Web-based ChatGPT-like chat interface |
| ... | 
```bash
git clone https://github.com/hwdsl2/self-hosted-ai-stack
cd self-hosted-ai-stack/stacks/chat-ui  # or voice-pipeline, voice-chat, rag-pipeline, rag-pipeline-full, code-assistant, ai-tools, chat-only
docker compose up -d

아키텍처 (Architecture)

graph LR
    A["🎤 음성 입력"] -->|transcribe| W["ScribeCrate<br/>(음성 인식 → 텍스트)"]
    D["📄 문서"] -->|parse| DC["ParseCrate<br/>(문서 → 텍스트)"]
...

참고 사항 (Notes):

• InferCrate의 포트(11434)와 UplinkCrate의 포트(3000)는 Docker 네트워크 내부용이며 기본적으로 호스트에 노출되지 않습니다. LLM에는 포트 4000을 통해 GatewayCrate로 접속하세요.
• SpeakCrate (TTS), ParseCrate (문서 파싱), 그리고 ScribeCrate Live (실시간 STT)는 메모리 사용량을 줄이기 위해 기본적으로 비활성화되어 있습니다. 이 서비스를 활성화하려면 docker-compose.yml에서 주석을 해제하세요.

Docker Compose 없이 실행하기 (Running without Docker Compose)

직접 docker run 명령어를 사용하는 것을 선호한다면, 먼저 서비스들이 통신할 수 있도록 공유 네트워크를 생성해야 합니다:

docker network create ai-stack

그런 다음 PostgreSQL 비밀번호를 생성하고 각 서비스를 공유 네트워크에 시작합니다:

참고: 수동 docker run의 경우, 먼저 PostgreSQL을 시작한 후 스택에 포함된 모델 및 도구 서비스들을 시작하세요. GatewayCrate를 시작하기 전에 종속성(dependencies)이 준비될 때까지 기다린 다음, AnythingLLM도 포함되어 있다면 시작하세요. 아래 예시는 하나의 PostgreSQL 비밀번호 변수를 생성하여 Postgres와 GatewayCrate에서 재사용합니다.

LITELLM_POSTGRES_PASSWORD=$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32)

# pgvector가 포함된 PostgreSQL (GatewayCrate에서 필요; pgvector는 RAG를 위한 벡터 저장소를 활성화함)
...

**참고:** 공유 네트워크를 사용하면 서비스들이 컨테이너 이름으로 서로 통신할 수 있습니다(예: GatewayCrate가 `http://ollama:11434`를 통해 InferCrate에 연결). 필요한 서비스만 시작할 수 있으며, 모든 서비스를 함께 실행할 필요는 없습니다.

**모델 풀링** (LLM 요청을 보내기 전에 필수):

```bash
docker exec ollama ollama_manage --pull llama3.2:3b

Podman 사용하기

이 스택은 최선의 노력(best-effort) 기준으로 Podman에서 실행됩니다. CPU compose 파일은 그대로 작동하며, GPU 가속 및 SELinux가 활성화된 호스트는 아래에 설명된 몇 가지 추가 단계가 필요합니다. Podman 4.1 이상을 권장합니다.

1. Docker CLI shim 설치. 이 README와 stack-check.sh 상태 확인 스크립트의 docker 명령이 변경 없이 작동하도록 하려면, podman-docker 패키지(‘docker’ → ‘podman’ 래퍼를 제공)를 설치합니다:

# Fedora / RHEL / CentOS Stream
sudo dnf install -y podman-docker

...

[!NOTE]
셸 별칭(alias docker=podman)은 충분하지 않습니다 — 별칭은 stack-check.sh와 같은 스크립트에서 인식되지 않습니다. 대신 podman-docker 패키지(또는 PATH 내의 ‘docker’ → ‘podman’ 심볼릭 링크)를 사용하십시오. 또는, stack-check.sh가 Podman을 자동으로 감지하므로, CONTAINER_ENGINE=podman ./stack-check.sh로 강제할 수도 있습니다.

2. Compose 제공자 설치. podman compose는 외부 제공자에 위임합니다. podman-compose 또는 docker-compose 중 하나를 설치하십시오:

# Fedora / RHEL / CentOS Stream
sudo dnf install -y podman-compose

...

3. 스택 시작. shim을 설치하면 이 README의 모든 명령이 변경 없이 작동합니다. shim이 없으면, docker 대신 podman으로 대체하십시오:

git clone https://github.com/hwdsl2/self-hosted-ai-stack
cd self-hosted-ai-stack
podman compose up -d

상태 확인을 실행합니다(엔진 자동 감지):

./stack-check.sh

GPU 가속(CDI). Podman은 Compose의 deploy.resources GPU 블록을 읽지 않습니다. 대신, Container Device Interface (CDI)를 사용하십시오. NVIDIA Container Toolkit을 설치한 후, CDI 스펙을 생성합니다:

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

그런 다음 GPU를 관련 서비스에 노출합니다. podman compose의 경우, docker-compose.cuda.yml에서 ollama (및 whisper) 서비스에 대한 deploy: 블록을 다음과 같은 devices: 항목으로 대체하십시오:

    devices:
      - nvidia.com/gpu=all

일반적인 podman run 명령어의 경우, --device nvidia.com/gpu=all를 추가합니다.

SELinux. SELinux가 활성화된 호스트(Fedora, RHEL, CentOS Stream)에서는 바인드 마운트 파일에 relabel 접미사가 필요하며, 그렇지 않으면 컨테이너가 접근이 거부됩니다. chat-ui-bootstrap.sh 바인드 마운트에 :z (공유)를 추가하십시오: