설정 지옥에서 한 번의 명령으로 배포까지: Claude Code로 구축한 HolyCode

실용적 조언

Docker 컨테이너에서 브라우저 기반 에이전트를 실행할 때 shm_size를 2g 이상으로 설정하여 메모리 부족으로 인한 크래시를 방지할 것
데이터 영속성을 위해 세션과 설정 데이터를 호스트 볼륨에 마운트하여 재빌드 시에도 환경을 유지할 것

섹션별 상세

개발 환경 이동 시마다 발생하는 설정 번거로움을 해결하기 위해 Claude Code로 Docker 아키텍처를 설계했다. AI 에이전트가 Chromium, xvfb, Playwright 기반의 브라우저 컨테이너 흐름을 분석하고 오류를 수정하여 실행 환경을 자동화했다. 원문에 명시된 대로 브라우저와 컨테이너 간의 복잡한 이슈를 신속하게 디버깅하여 재현 가능한 빌드 프로세스를 완성했다. 이는 코딩 에이전트가 인프라 구축의 복잡성을 낮추는 데 실질적인 도움을 줄 수 있음을 시사한다.

컨테이너 재빌드 시 작업 데이터가 소실되는 문제를 방지하고자 영구 저장소 기반의 HolyCode를 개발했다. 호스트의 특정 디렉토리를 컨테이너 내부의 /home/opencode와 /workspace에 볼륨 마운트하여 세션과 설정을 보존한다. Docker Compose 파일에 정의된 볼륨 설정을 통해 재시작 후에도 이전 작업 상태를 그대로 유지할 수 있다. 데이터 영속성 확보는 장기적인 AI 에이전트 프로젝트 운영에서 필수적인 요소이다.

브라우저 기반 에이전트의 실행 안정성을 확보하기 위해 시스템 리소스 할당 방식을 최적화했다. Docker의 shm_size를 기본값보다 훨씬 큰 2GB로 설정하여 다중 탭 실행 시 발생하는 메모리 부족 크래시를 방지했다. 공유된 Docker Compose 코드 스니펫에서 shm_size: 2g 설정을 통해 고부하 작업에서도 중단 없는 실행이 가능함을 확인했다. 적절한 리소스 제한 해제는 헤드리스 브라우저 환경의 신뢰성을 높이는 핵심 실무 팁이다.

yaml

services:
  holycode:
    image: coderluii/holycode:latest
    restart: unless-stopped
    shm_size: 2g
    ports:
      - "4096:4096"
    volumes:
      - ./data/opencode:/home/opencode
      - ./workspace:/workspace
    environment:
      - PUID=1000
      - PGID=1000
      - ANTHROPIC_API_KEY=your-key-here

HolyCode 환경을 실행하기 위한 Docker Compose 설정 예시

용어 해설

X 가상 프레임버퍼(Xvfb): — 실제 디스플레이 하드웨어 없이 메모리상에서 그래픽 작업을 수행하는 디스플레이 서버이다. GUI가 없는 서버 환경에서 Chromium 같은 브라우저를 실행하여 AI 에이전트가 웹 페이지를 렌더링하고 조작할 수 있게 한다.
공유 메모리 크기(shm_size): — Docker 컨테이너에 할당되는 공유 메모리(/dev/shm)의 크기를 지정하는 설정이다. 브라우저 기반 에이전트는 탭 실행 시 많은 공유 메모리를 사용하므로, 기본값 대신 2GB 정도로 늘려야 크래시 없이 안정적으로 작동한다.
영구 저장소(Persistent Storage): — 컨테이너가 삭제되거나 재시작되어도 데이터가 사라지지 않고 유지되는 저장 공간이다. AI 에이전트의 브라우저 세션, 설치된 플러그인, 사용자 설정을 호스트 디렉토리에 볼륨 마운트하여 환경의 연속성을 보장한다.

언급된 도구

Claude Code추천

AI 코딩 에이전트 및 개발 보조

HolyCode추천

Docker 기반 AI 에이전트 실행 환경

Playwright중립

브라우저 자동화 및 에이전트 워크플로우 제어

언급된 리소스

GitHubHolyCode GitHub Repository