클라이언트의 Ruby 2.2.2 애플리케이션을 Kamal로 배포하는 과정에서 가장 먼저 발생한 문제는 Docker 이미지 풀링 오류였습니다. ERROR: failed to solve: failed to load cache key: Pulling Schema 1 images have been deprecated and disabled by default since containerd v2.0 메시지는 ruby:2.2.2-slim 이미지가 Docker Image Manifest Schema 1을 사용하며, 최신 Docker 버전(v26 이상에서 기본 비활성화, v28 이상에서 완전 제거)에서 지원되지 않기 때문에 발생했습니다. 이 문제는 레거시 앱을 현대적인 컨테이너 환경에 통합하려는 시도에서 흔히 발생하는 버전 호환성 문제를 명확히 보여주었습니다.
문제 해결을 위해 세 가지 접근 방식을 시도했습니다. 첫 번째 시도는 Docker 데몬에 DOCKER_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE=1 환경 변수를 설정하여 레거시 스키마 지원을 활성화하는 것이었습니다. 그러나 Kamal의 기본 docker-container 빌드 드라이버가 독립적인 BuildKit 환경에서 작동하며 호스트 Docker 데몬 설정을 상속받지 않기 때문에 이 방법은 효과가 없었습니다. 이는 Kamal의 빌드 전략에 대한 중요한 학습 포인트였습니다.
두 번째 시도는 Kamal의 빌드 드라이버를 docker로 변경하는 것이었습니다. kamal.yml 파일에 builder: driver: docker를 추가함으로써 Kamal이 호스트 Docker 엔진을 직접 사용하도록 하여 호스트 설정이 적용될 수 있게 했습니다. 이는 문제 해결에 진전을 보였지만, 여전히 동일한 오류가 발생했습니다. 그 이유는 호스트 머신이 Docker v28을 실행하고 있었고, 이 버전에서는 Schema 1 지원이 완전히 제거되었기 때문이었습니다. 따라서 세 번째이자 최종 해결책은 Docker 버전을 v26으로 다운그레이드하여 Schema 1을 활성화할 수 있는 환경을 조성하는 것이었습니다. Docker 서비스 재시작 후, 비로소 레거시 Ruby 애플리케이션의 이미지가 성공적으로 빌드되고 배포될 수 있었습니다.
주요 배포 문제를 해결한 후, SSL 인증서 관리라는 또 다른 문제가 발생했습니다. Kamal은 Let’s Encrypt를 통한 내장 프록시를 지원하지만, 클라이언트는 이미 구매한 맞춤형 SSL 인증서를 사용해야 했습니다. Kamal은 기본적으로 타사 인증서를 지원하지 않으므로, Kamal의 프록시를 비활성화하고 Nginx를 액세서리 서비스로 추가하는 방식으로 해결했습니다. Nginx 컨테이너 내에서 기존 인증서 경로를 수동으로 구성하여 클라이언트의 기존 SSL 인프라를 유지하면서 컨테이너화된 배포를 가능하게 했습니다.