Strata는 카드별 사전 빌드 이미지를 GitHub Container Registry에 0.2.1 버전부터 게시합니다: ghcr.io/niko1221/strata:<버전>-<flavor>(예: 0.2.7-cuda13), 최신은 :latest-<flavor>. 컨테이너에는 엔진이 포함되어 있고, NVIDIA·AMD 이미지는 첫 실행 때 모델 다운로드·준비까지 합니다(Intel Arc는 준비된 모델 파일 필요). 데이터 볼륨을 유지하면 다운로드와 설정이 재사용됩니다.

내 환경에 맞는 이미지 선택하기

그래픽 카드	이미지 태그	컴퓨터에 필요한 것
NVIDIA RTX 20/30/40/50(해당 RTX A/Quadro 포함)	0.2.7-cuda13	NVIDIA 드라이버 580 이상, NVIDIA Container Toolkit
NVIDIA GTX 10, Tesla P100, V100, 드라이버 575~579 환경	0.2.7-cuda12	드라이버 575 이상, 동일 툴킷
AMD RX 9000 시리즈·AI PRO R9700(RDNA 4)	0.2.7-rocm-gfx120x	amdgpu 커널 드라이버(Linux 6.8+)
AMD RX 7000 시리즈(RDNA 3)	0.2.7-rocm-gfx110x	amdgpu 커널 드라이버
AMD Ryzen AI Max(Strix Halo)	0.2.7-rocm-gfx1151	amdgpu 커널 드라이버
Intel Arc A·B 시리즈	0.2.7-sycl	i915/xe 드라이버, 준비된 모델 파일

NVIDIA에서 헷갈리면 nvidia-smi가 드라이버 580 이상이고 RTX면 cuda13, 아니면 cuda12. 잘못 골라도 문제는 없습니다. 컨테이너가 떠서 "이 카드에 엔진이 맞지 않는다"고 평문으로 알린 뒤 멈춥니다. 이미지 크기는 디스크 기준 1.5~2.9GB, 다운로드와 모델은 그 위입니다.

바로 실행해 보는 한 줄 명령어

아래 명령은 백그라운드 실행, 파일은 strata-data 볼륨 유지, 이 컴퓨터(127.0.0.1:8080)에서만 접근합니다. FAMILY·MODEL을 고르고 키를 만듭니다. 첫 실행은 모델 다운로드(수십 GB)가 있으니 docker logs -f strata로 보세요.

NVIDIA

docker run -d --name strata --gpus all -p 127.0.0.1:8080:8080 \
  --ulimit memlock=-1:-1 --shm-size 2g --stop-timeout 120 \
  -v strata-data:/data -e FAMILY=qwen -e MODEL=IQ3_XXS -e API_KEY=$(openssl rand -hex 24) \
  ghcr.io/niko1221/strata:0.2.7-cuda13

AMD

docker run -d --name strata --device /dev/kfd --device /dev/dri \
  --group-add video --group-add $(getent group render | cut -d: -f3) -p 127.0.0.1:8080:8080 \
  --ulimit memlock=-1:-1 --shm-size 2g --stop-timeout 120 \
  -v strata-data:/data -e FAMILY=qwen -e MODEL=IQ3_XXS -e API_KEY=$(openssl rand -hex 24) \
  ghcr.io/niko1221/strata:0.2.7-rocm-gfx120x

Intel Arc (준비된 GGUF 폴더 필수)

docker run -d --name strata --device /dev/dri --group-add $(getent group render | cut -d: -f3) \
  -p 127.0.0.1:8080:8080 --ulimit memlock=-1:-1 --shm-size 2g --stop-timeout 120 \
  -v strata-data:/data -e FAMILY=qwen -e MODEL=IQ3_S -e MODEL_PATH=/models -v /srv/gguf/IQ3_S:/models:ro \
  -e API_KEY=$(openssl rand -hex 24) ghcr.io/niko1221/strata:0.2.7-sycl

왜 이 옵션들이 필요한가요?

옵션	이유
--ulimit memlock=-1:-1	엔진이 모델용 RAM을 pin(고정)할 수 있게 함
--shm-size 2g	shared memory 여유
--stop-timeout 120	큰 모델이 언로드되는 데 기본 10초로는 부족하므로 2분 허용
-p 127.0.0.1:8080:8080	이 컴퓨터만 접근. 바깥으로 여는 건 명시적으로 판단

컨테이너에 메모리 제한을 걸지 마세요. Strata는 사용 가능한 전체 RAM을 기준으로 실행 계획을 세우고 수십 GB의 모델을 로드하므로, 제한을 걸면 실행 도중 메모리 부족으로 종료될 수 있습니다.

Docker Compose

문서는 FAMILY/MODEL/API_KEY 환경변수와 데이터 볼륨을 그대로 옮기는 compose 파일을 예로 듭니다. 구조는 실행 명령과 같고, 카드별 device_requests/devices 옵션이 다릅니다. 여러 카드를 한 컨테이너에 쓰거나 배치를 구성할 때는 이미지에서 직접 엔진을 실행하는 형태가 아니라 이 문서의 실행 래퍼를 통하는 것이 원칙입니다. 이미지 자체를 다시 빌드하는 경우(Build it yourself)는 별도 태그를 붙여 예제에서 그 태그를 쓰면 됩니다.

API 키

API_KEY 환경변수로 넣은 값이 inference 키입니다. 만든 키를 나중에 보려면 실행 중인 컨테이너에 물어보면 됩니다.

docker exec strata strata launch --show-key --preset docker

셸 히스토리에 남기기 싫으면 시작 전에 echo로 찍어 두거나 비밀 관리 수단을 쓰세요.

이미 준비된 GGUF로 시작

모델 GGUF를 이미 갖고 있다면 -e MODEL_PATH=/models -v /your/folder:/models:ro를 붙이면 모델 다운로드가 생략됩니다(Intel Arc는 이 방식이 기본 경로). 데이터 볼륨 /data에는 설정과 준비 파일이 남습니다.

로그 확인·정지·업데이트

docker logs -f strata      # 다운로드·시작 로그
docker stop strata         # 언로드 대기 후 정지(--stop-timeout)
docker rm strata           # 제거(데이터 볼륨은 -v strata-data 유지 시 재사용)

이미지 업데이트는 새 태그를 당겨 오는 방식입니다. 특정 버전으로 고정했다가 직접 결정해서 올리고 싶으면 버전 태그를 pin하세요(latest-<flavor>는 해당 flavor의 최신 릴리스). NVIDIA에서 CUDA 이미지 선택이 애매하면 앞의 표 기준으로 nvidia-smi 드라이버부터 확인합니다.

Mac과 Windows의 제한

• Mac: Docker는 Mac의 그래픽 칩(Metal)에 접근하지 못합니다. Mac에서는 앱이나 터미널을 쓰세요.
• Windows + Docker Desktop: WSL 2로 NVIDIA 카드는 패스스루되지만 Radeon·Arc는 안 됩니다. Windows에서는 지원 카드에 네이티브 앱이 정답이고, Intel Arc는 Linux 가이드를 따릅니다.
• 구버전 이미지에서 이전한 경우의 호환 메모가 DOCKER.md에 있습니다(From the older image).