Docker로 구동하는 Claude Code: 자택 서버로 테스트한 견고한 로컬 개발 환경 구축 방법

이 기사의 목표

사내 정보 시스템 부서/제조업 현장에서 "LLM을 개발에 도입하고 싶지만, 사내 정책이나 기밀 유지 문제로 손을 댈 수 없다"라는 케이스에 대해, 자택 서버 x Docker x Claude Code로 만든 현실적인 구성을 해설합니다.

과제: 클라우드 AI를 그대로 업무에 사용할 수 없는 이유

중소기업이나 제조업 현장에서 내년도 DX(디지털 전환)를 위해 생성 AI 도입을 검토하는 움직임이 늘고 있습니다. 하지만 즉시 실운용할 수 없는 이유는 대개 다음 3가지 점으로 집약됩니다.

• 기밀 정보를 사외로 유출하고 싶지 않음 (계약 도면, 고객 리스트, 품질 기록……)
• 개발 환경의 의존성 지옥 (라이브러리 충돌, OS 차이, Python 2/3 혼재)
• "누군가가 실행했을 때만 작동하는" 상태가 지속되어 기술적 부채가 됨

저도 2025년부터 시작한 개인 사업에서, Docker와 Anthropic의 Claude Code를 조합하여 자택의 x1lite 서버 상에 로컬 AI 개발 환경을 구축하고, 업무 시스템의 오퍼레이션을 지원해 왔습니다. 이번에는 그 구현과 주의점을 공유합니다.

구축의 전체상

설계는 "최소의 리스크"를 기준으로 3가지 영역으로 나누었습니다.

• 호스트: Ubuntu 24.04가 구동되는 Beelink EliteMini (구 명칭 x1lite)
• 기반: Docker Compose + s6 overlay를 통한 서비스 재시작 자동화
• 애플리케이션: ClawLess의 WebContainers 런타임(Runtime)을 참고하여, 브라우저 상에서 Claude Code를 동작시키는 구성

보안 측면은 Docker 네트워크를 bridge로 분리하고, 호스트 측의 포트 80/443을 통해서만 외부 공개합니다. LLM 관련 컨테이너는 PR 빌드 시에만 기동함으로써 상주 비용을 억제하고 있습니다.

구현: 3개의 Dockerfile로 환경을 고정하기

핸즈온(Hands-on)의 재현성을 높이기 위해, 저는 3개의 Dockerfile을 나누었습니다. 파일은 /srv/common/obsidian/wiki/Docker.md 메모로 관리하면서, 실제 구성도 git으로 추적하고 있습니다.

# base image: CPU 아키텍처에 맞춰 slim 계열을 사용
FROM python:3.13-slim
RUN apt-get update && apt-get install -y \
...

# claude-python: Claude API 호출 예시
FROM python:3.13-slim
RUN pip install anthropic==0.39.0
...

# claude_client.py (최소한의 동작 예시)
import os
from anthropic import Anthropic
...

포인트는 호스트 OS의 라이브러리 차이를 Dockerfile로 봉쇄하는 것입니다. 추후 C 확장(C extension)이 있는 라이브러리를 추가하는 경우에도 apt 레이어를 고정함으로써 재현할 수 있습니다.

docker compose로 전체를 기동하기

docker-compose.yml은 다음과 같이 서비스를 나누었습니다. ClawLess의 WebContainers 런타임 메커니즘을 참고하여, 브라우저 상에서 Claude Code를 조작할 수 있는 포털도 마련해 두었습니다.

version: '3.9'
services:
llm-api:
...

주의사항으로, API 키는 .env에 기재하고 git에는 포함하지 않습니다. Anthropic의 대시보드에서 발행한 키를 런타임 측에 통째로 넘기는 것이 아니라, docker compose run --rm -e ANTHROPIC_API_KEY ... 형태로 매번 주입하는 운용 방식을 권장합니다.

자택 서버로 얻은 효과

실제로 이 환경을 사용하기 시작한 후의 장점을 3가지 꼽겠습니다.

1. 재사용성

Claude와의 대화 로그나 보조 스크립트를 모두 Obsidian의 Vault에 저장. 동일한 구성을 다른 프로젝트에도 10분 만에 재사용할 수 있었습니다. Docker 이미지의 레이어를 태그 지정 없이 고정함으로써, 반년 후의 재현성도 확보하고 있습니다.

2. 비용 구조가 보임

x1lite는 소비 전력이 적어, 하루 Docker 구동 시간당 전기 요금은 몇 엔 정도입니다. 부서 단위로 클라우드 AI를 계약할 경우의 1/10 이하로 해결되는 케이스도 많아, 소규모 사업소의 도입 장벽을 낮출 수 있습니다.

3. 업데이트의 공포가 사라짐

docker compose pull로 최신 버그 수정을 가져오면서, docker compose up -d로 새로운 컨테이너를 기동합니다. 이전 이미지는 docker images로 관리하며, 장애 발생 시에는 docker compose down으로 이전 버전으로 되돌릴 수 있습니다. 제조업의 유지보수 및 운영(Maintenance & Operations) 감각과 매우 상성이 좋다는 점도 유지율이 높은 이유라고 생각합니다.

과제와 현시점의 대응

구축을 진행하는 과정에서, 다음 사항들은 현재 진행형으로 개선 중입니다.

• Windows / Mac에서의 재현성: 호스트 OS의 파일 시스템 권한(Docker Desktop에서는 rootless 동작이 다름) 문제로 인해 중단되기 쉽습니다. docker compose exec를 통해 홈 디렉토리를 명시적으로 마운트합니다.
• 키 관리 (Key Management): 실무 프로젝트에서는 HashiCorp Vault 등과 병용하여, Docker Compose 자체에 secrets를 전달하지 않는 설계로 이행할 예정입니다.
• 장기 실행 테스트: 2년 단위의 Dependabot 업데이트와, docker compose run --rm을 이용한 엔드 투 엔드 (end-to-end) 테스트를 CI에서 실행함으로써 파괴적 변경(Breaking Changes)을 조기에 감지하고 있습니다.

요약

Claude Code + Docker의 로컬 개발 환경은 기밀 유지와 재사용성을 양립하는 현실적인 선택지입니다. 클라우드 기반 프로젝트와 병행하여, 소규모 자동화 스크립트부터 운영을 시작함으로써 조직의 AI 리터러시(AI Literacy)를 높일 수 있습니다.

자택 서버에서도, 제조업의 기간 시스템 연계에서도, 우선은 '하나의 Docker Compose'부터 시작하는 것이 가장 빠른 길입니다. 저는 개인 사업 형태로 중소기업의 DX(Digital Transformation) 추진, 서버 구축, 업무 시스템 내재화 지원을 다루고 있습니다. 기밀 유지 요건이 있는 프로젝트에서도 상담 내용에 따라 최적의 구성을 제안해 드릴 수 있습니다.

참고 자료

• Obsidian 메모:
  /srv/common/obsidian/wiki/Docker.md

• Obsidian 메모:
  /srv/common/obsidian/wiki/Claude.md

• Anthropic Claude Docs: https://docs.anthropic.com/

Discussion