콘텐츠로 이동
Search

Coder

Secure environments for developers and their agents

Tutorials

Install

Docker 

## 1. 공식 compose 예제 다운로드 / Download the official compose example
curl -fLo compose.yaml https://raw.githubusercontent.com/coder/coder/main/compose.yaml

## 2. docker 그룹 GID 확인 (아래 group_add 값에 사용) / Get docker group GID
getent group docker | cut -d: -f3

## 3. Coder 기동 / Start Coder
docker compose up -d

## 4. 로그 확인 (access URL 확인용) / Check logs for the access URL
docker compose logs -f coder

외부에서 도달 가능한 IP 또는 Domain 을 CODER_ACCESS_URL 환경변수로 설정해야 한다.

클라이언트 로그인 

## 클라이언트 설치
curl -fsSL https://coder.com/install.sh | sh

## `coder` 커맨드 사용 가능
coder login https://coder.run   # 브라우저가 열리고 세션 토큰 발급 / opens browser for session token

SSH 접속 방법

워크스페이스 생성 후: 

coder config-ssh

## 워크스페이스.coder 이름으로 접속하자. 예를 들어 이름이 `demo-workspace` 라면:
ssh demo-workspace.coder

Docker 템플릿에 GPU 연결하기

템플릿을 수정하면 된다:

kreuzwerker/docker 를 사용하고 있으니, docker_container에 gpus 인자가 그대로 있습니다. docker run --gpus all과 동일하게 DeviceRequests로 변환됩니다. 

resource "docker_container" "workspace" {
  count = data.coder_workspace.me.start_count
  image = docker_image.main.image_id
  name  = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"

  gpus = "all"   # == docker run --gpus all

  # ...
}

Docker 템플릿에서 shared memory 늘리기

템플릿을 수정하면 된다:

kreuzwerker/docker 의 docker_container 에는 shm_size 인자가 있습니다. 단위는 MB 이며, docker run --shm-size=10g 과 동일하게 동작합니다. 

resource "docker_container" "workspace" {
  count = data.coder_workspace.me.start_count
  image = "coder-dgx-spark:cuda13"
  name  = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"

  gpus     = "all"
  shm_size = 10240   # == docker run --shm-size=10g (MB 단위)

  # ...
}

shm_size 변경은 컨테이너 재생성을 유발하므로 워크스페이스를 재시작해야 한다. 홈 디렉토리는 home_volume 에 있으므로 데이터는 유지된다.

적용 후 컨테이너 안에서 확인: 

df -h /dev/shm

Size 가 10G 로 표시되면 정상이다. /dev/shm 은 tmpfs 라서 실제로 쓴 만큼만 RAM 을 점유한다.

=== 참고: ipc_mode = "host" === 상한을 아예 없애고 싶다면 shm_size 대신 ipc_mode = "host" 를 쓸 수도 있다. 다만 호스트 IPC 네임스페이스를 공유하므로 격리가 약해진다. 명시적으로 크기를 제한하는 shm_size 쪽을 권장한다.

Troubleshooting

HTTP 400: System message must be at the beginning

vLLM 실행 후 "OpenAI 호환" 으로 AI 연결하면 HTTP 400 에러 나면서 다음 에러 출력됨: 

System message must be at the beginning

Jinja chat template 이 문제이다.

많은 템플릿에 이런 방어 코드가 들어 있습니다: 

{%- if messages[0]['role'] != 'system' and ns.system_seen %}
    {{- raise_exception('System message must be at the beginning') }}
{%- endif %}

즉 messages 배열에 role: "system" 이 첫 번째가 아닌 위치에 들어왔다는 뜻입니다. 게이트웨이가 프롬프트를 통과시킬 때 system 메시지를 추가로 끼워넣었거나, 클라이언트가 대화 중간에 system을 다시 보낸 경우입니다.

흔한 발생 경로:

  • Anthropic 포맷 클라이언트(Claude Code 등) → OpenAI 포맷 변환. Anthropic은 system이 최상위 별도 필드라 변환 시 위치가 어긋날 수 있습니다.
  • 에이전트 하네스가 대화 중간에 system reminder를 삽입 (Claude Code, Cline이 자주 이럽니다)
  • system 메시지가 2개 이상 (첫 번째는 맞는데 두 번째가 중간에)
  • role: "developer" 를 system으로 매핑하면서 위치가 밀림

See also

Favorite site

lastmod 2026-09-14created 2026-09-14author Zer0 sitemap