Kamal을 활용한 Ruby on Rails 애플리케이션 자체 호스팅 배포 가이드

Self Hosted App | Drifting Ruby

작성자
The Awesome Ruby
발행일
2026년 01월 04일
원문 보기
www.driftingruby.com

핵심 요약

  • 1 Kamal을 사용하여 Ruby on Rails 애플리케이션을 Docker 컨테이너 기반으로 자체 서버에 배포하는 방법을 설명합니다.
  • 2 config/deploy.yml 파일을 통해 서버, 이미지, 환경 변수, 빌더 아키텍처 등 배포 환경을 세밀하게 구성하는 과정을 제시합니다.
  • 3 Raspberry Pi와 같은 ARM64 기반 환경에서 Solid Queue를 포함한 Rails 애플리케이션을 효율적으로 운영하기 위한 설정 전략을 다룹니다.

도입

Kamal(이전 MRSK)은 Docker와 SSH를 활용하여 웹 애플리케이션을 단일 서버 또는 소규모 서버 그룹에 효율적으로 배포할 수 있는 도구입니다. 본 문서는 Kamal을 사용하여 Ruby on Rails 기반 애플리케이션을 자체 호스팅 환경에 배포하는 구체적인 설정과 절차를 안내합니다. 특히 `config/deploy.yml` 파일의 각 섹션이 배포 과정에서 어떤 역할을 하는지 상세히 설명하며, Raspberry Pi와 같은 ARM64 아키텍처 서버 환경에 최적화된 배포 전략을 제시합니다.

Kamal 배포 기본 명령 및 서버 준비

  • kamal setup: 애플리케이션 배포를 위한 초기 환경을 설정합니다.

  • kamal deploy: 새로운 버전의 애플리케이션을 배포하고 이전 버전을 교체합니다.

Raspberry Pi 서버 준비

  • sudo usermod -aG docker $USER: 현재 사용자를 Docker 그룹에 추가하여 Docker 명령 실행 권한을 부여합니다.

  • sudo apt update && sudo apt upgrade -y: 시스템 패키지를 최신 상태로 업데이트합니다.

  • sudo apt install wget curl: 필수 유틸리티인 wget과 curl을 설치합니다.

config/deploy.yml 상세 설정

config/deploy.yml 파일은 Kamal 배포의 핵심 설정 파일로, 애플리케이션의 배포 환경을 정의합니다.

애플리케이션 기본 정보

  • service: 애플리케이션의 고유한 이름입니다. (예: example)

  • image: 컨테이너 이미지의 이름입니다. (예: example)

서버 구성

  • servers: 애플리케이션이 배포될 서버 목록을 정의합니다.
    • web: 웹 서버 역할을 수행할 호스트의 IP 주소를 지정합니다. (예: 192.168.254.57)
    • job (주석 처리됨): 백그라운드 작업을 처리할 서버를 별도로 지정할 수 있습니다.

레지스트리 설정

  • registry: Docker 이미지를 저장하고 가져올 레지스트리 서버를 지정합니다.
    • server: 레지스트리 서버 주소입니다. 자체 호스팅 환경에서는 localhost:5555와 같은 로컬 레지스트리를 활용할 수 있습니다.
    • username, password (주석 처리됨): 인증이 필요한 레지스트리의 경우 사용자 이름과 비밀번호를 설정합니다. 보안을 위해 KAMAL_REGISTRY_PASSWORD와 같은 환경 변수를 사용하는 것이 권장됩니다.

환경 변수 (ENV)

컨테이너 내에서 사용될 환경 변수를 설정합니다.

  • secret: .kamal/secrets 파일에서 로드될 민감한 환경 변수입니다. (예: RAILS_MASTER_KEY)

  • clear: 직접 값을 지정하는 일반 환경 변수입니다.

    • SOLID_QUEUE_IN_PUMA: true: Rails 애플리케이션에서 Solid Queue 작업을 Puma 프로세스 내에서 처리하도록 설정합니다.
    • JOB_CONCURRENCY, WEB_CONCURRENCY, DB_HOST, RAILS_LOG_LEVEL (주석 처리됨): 작업 동시성, 웹 동시성, 데이터베이스 호스트, 로그 레벨 등을 설정할 수 있습니다.

별칭 (Aliases)

자주 사용하는 명령어를 짧은 별칭으로 정의하여 bin/kamal <alias> 형태로 실행할 수 있게 합니다.

  • console: bin/rails console 실행

  • shell: bash 셸 실행

  • logs: 애플리케이션 로그 실시간 확인

  • dbc: bin/rails dbconsole 실행

볼륨 및 자산 경로

  • volumes: 데이터 지속성을 위해 컨테이너와 호스트 간에 공유될 볼륨을 정의합니다. (예: example_storage:/rails/storage)

  • asset_path: 배포 중 자산(assets)의 404 오류를 방지하기 위해 이전 버전과 새 버전의 자산을 브리지하는 경로를 지정합니다. (예: /rails/public/assets)

빌더 설정

  • builder: Docker 이미지 빌드 설정을 정의합니다.
    • arch: arm64: Raspberry Pi와 같은 ARM 기반 서버를 위한 크로스 컴파일 빌드를 가능하게 합니다.
    • remote, args, secrets (주석 처리됨): 원격 빌드 서버, 빌드 인수, 빌드 시 사용할 비밀값 등을 설정할 수 있습니다.

SSH 사용자

  • ssh: SSH 연결에 사용될 사용자(user: kobaltz)를 지정하여 기본 root 사용자 대신 다른 계정을 사용할 수 있도록 합니다.

액세서리 서비스 (주석 처리됨)

  • accessories: MySQL, Redis와 같은 추가 서비스를 Docker 컨테이너로 함께 배포할 수 있습니다. 예시에서는 db (MySQL)와 redis (Valkey) 설정이 주석 처리되어 있습니다.

결론

Kamal은 Docker와 SSH를 활용하여 Ruby on Rails 애플리케이션을 포함한 컨테이너 기반 애플리케이션을 효율적으로 자체 호스팅 환경에 배포할 수 있는 강력한 도구입니다. `config/deploy.yml` 파일의 체계적인 설정을 통해 서버 구성, 환경 변수 관리, 빌드 아키텍처 지정 등 배포의 모든 측면을 유연하게 제어할 수 있습니다. 특히 ARM64 아키텍처 지원과 Solid Queue 같은 Rails 관련 기능 통합은 소규모 서버나 Raspberry Pi와 같은 저전력 장치에서도 Ruby on Rails 애플리케이션을 안정적으로 운영할 수 있는 실질적인 방안을 제공합니다. 이는 개발자가 인프라 관리에 드는 노력을 최소화하면서 애플리케이션 배포에 집중할 수 있도록 돕습니다.

관련 글들

Kamal 2: 단일 서버에 여러 Rails 앱 배포 간소화

Kamal 2는 새로운 Kamal Proxy를 통해 단일 서버에 여러 Rails 애플리케이션을 쉽게 배포할 수 있도록 지원합니다.

10/20 읽어보기 →

Kamal을 활용한 Bugsink 배포 가이드

Kamal을 사용하여 개인 프로젝트를 위한 Bugsink 오류 추적 시스템을 효율적으로 배포하는 방법을 상세히 설명합니다.

06/16 읽어보기 →

Kamal을 활용한 Rails 8 애플리케이션 프로덕션 배포 가이드

Kamal은 Rails 8에 내장된 배포 도구로, Heroku와 같은 서드파티 플랫폼 없이 Ruby on Rails 애플리케이션을 프로덕션 환경에 직접 배포하는 과정을 간소화합니다.

07/16 읽어보기 →

Cloudflare와 Kamal을 사용하여 Rails 앱에 Full (Strict) SSL 연결 구성하기

Cloudflare의 Full (strict) SSL 프록시를 Rails 애플리케이션에 적용하기 위한 핵심 설정들을 다룹니다.

12/11 읽어보기 →

댓글 0

로그인이 필요합니다

댓글을 작성하거나 대화에 참여하려면 로그인이 필요합니다.

로그인 하러 가기

아직 댓글이 없습니다

첫 번째 댓글을 작성해보세요!