Capistrano::Sidekiq
Gem Version
COSS Compliant
Capistrano용 Sidekiq 통합 기능 - Sidekiq 7 이상 버전에 대한 systemd 서비스 관리 및 배포 조정 기능을 제공합니다.
v2.x에서 업그레이드하나요? 중단되는 변경 사항(breaking changes) 및 업그레이드 지침은 Migration Guide를 참조하세요.
예제 애플리케이션 (Example Application)
이 Gem의 작동하는 완전한 예제를 보려면, 다음 capistrano-example-app을 참고하세요. 여기에는 다음 내용이 시연되어 있습니다:
- Capistrano를 사용한 Rails 8.0 배포
- Redis 7+와 함께하는 Sidekiq 7.0
- Systemd 서비스 관리
- rbenv 통합
- 전체 배포 가이드
설치 (Installation)
Gemfile에 추가하세요:
gem 'capistrano-sidekiq', group: :development
그런 다음 실행하세요:
설정 (Setup)
Capfile에 추가하세요:
require 'capistrano/sidekiq'
install_plugin Capistrano::Sidekiq
...
중요: require와 install_plugin 라인 둘 다 필요합니다. require는 Gem 코드를 로드하는 역할을 하며, install_plugin은 실제로 Capistrano 태스크를 등록합니다. install_plugin이 없으면 cap sidekiq:start 같은 명령어는 사용할 수 없습니다.
설정 옵션 (Configuration Options)
기본 설정 (Basic Settings)
set :sidekiq_roles, :worker
set :sidekiq_default_hooks, true
...
다른 Gem과의 공유 설정 (Shared Configuration with Other Gems)
이 Gem은 여러 서비스 Gem(예: capistrano-puma, capistrano-sidekiq)에 걸쳐 공통 설정을 공유하는 Capistrano의 관례를 따릅니다. 다음 설정들이 공유됩니다:
:service_unit_user - 서비스가 시스템 단위로 실행될지 사용자 단위로 실행될지를 결정합니다.:systemctl_bin - systemctl 바이너리의 경로입니다.:lingering_user - systemd lingering(사용자 서비스용)을 위한 사용자입니다.:service_unit_env_files - 공유 환경 파일입니다.:service_unit_env_vars - 공유 환경 변수입니다.
각 gem은 접두사가 붙은 버전(예: :sidekiq_systemctl_user)으로 이들을 재정의할 수 있습니다.
고급 구성 (Advanced Configuration)
set :service_unit_user, :user
set :systemctl_bin, '/bin/systemctl'
...
서버별 구성 (Per-Server Configuration)
특정 서버에 대해 Sidekiq를 다르게 구성할 수 있으며, 이를 통해 서로 다른 서버에서 서로 다른 구성을 가진 여러 Sidekiq 프로세스를 실행할 수 있습니다.
기본 서버별 설정 (Basic Per-Server Setup)
server 'worker1.example.com',
roles: [:worker],
...
고급 서버별 구성 (Advanced Per-Server Configuration)
server 'worker1.example.com',
roles: [:worker],
...
작동 방식 (How It Works)
- 구성 파일 (Configuration Files): 각 서버는 자체
sidekiq_config_files 세트를 가질 수 있습니다.
- 서비스 생성 (Service Creation): 각 설정 파일에 대해 별도의 systemd 서비스가 생성됩니다.
- 서비스 이름 지정 (Service Naming): 기본
sidekiq.yml의 경우 서비스 이름은 <app>_sidekiq_<stage>로, 추가 구성 파일의 경우 <app>_sidekiq_<stage>.<config_name>으로 지정됩니다.
- 독립 제어 (Independent Control): 각 서비스는 독립적으로 시작, 중지 및 재시작될 수 있습니다.
예제 구성 (Example Configurations)
config/sidekiq_high_priority.yml:
:concurrency: 10
:queues:
- [critical, 2]
...
config/sidekiq_low_priority.yml:
:concurrency: 5
:queues:
- [low, 1]
...
배포 명령어 (Deployment Commands)
서버별(per-server) 구성을 사용할 경우, Capistrano는 다음 작업을 수행합니다:
cap production sidekiq:install 실행 시 각 서버에 적절한 서비스를 설치합니다.cap production sidekiq:start 실행 시 구성된 서비스만 각 서버에서 시작합니다.- 각 서버의 서비스를 독립적으로 관리합니다.
특정 서버를 지정할 수도 있습니다:
cap production sidekiq:restart --hosts=worker1.example.com
여러 프로세스(Multiple Processes)
여러 Sidekiq 프로세스를 실행하는 방법은 두 가지가 있습니다:
옵션 1: 여러 설정 파일 사용 (권장)
워크로드별로 별도의 설정 파일을 생성합니다:
:concurrency: 5
:queues:
...
deploy.rb에 다음과 같이 구성합니다:
set :sidekiq_config_files, ['sidekiq_critical.yml', 'sidekiq_default.yml']
이것은 별도의 서비스들을 생성합니다:
myapp_sidekiq_production.sidekiq_criticalmyapp_sidekiq_production.sidekiq_default
장점:
- 각 프로세스의 목적이 명확함
- 독립적인 확장 및 관리 가능
- 프로세스별 다른 구성 적용 가능
- 의미 있는 서비스 이름 부여
옵션 2: Sidekiq Enterprise (Sidekiqswarm)
동일한 프로세스로 간단하게 스케일링할 경우:
set :sidekiq_command, 'sidekiqswarm'
set :sidekiq_service_unit_env_vars, ['SIDEKIQ_COUNT=10']
이것은 단일 서비스로 10개의 동일한 프로세스를 실행합니다.
여러 프로세스에 대한 빠른 설정
헬퍼 태스크를 사용하여 설정 파일을 생성합니다:
bundle exec cap production sidekiq:helpers:generate_configs[5]
...
그런 다음 deploy.rb에 추가합니다:
set :sidekiq_config_files, ['sidekiq.yml', 'sidekiq_1.yml', 'sidekiq_2.yml', 'sidekiq_3.yml', 'sidekiq_4.yml']
사용 가능한 태스크(Available Tasks)
Systemd 통합
systemd 통합에 대한 자세한 정보는 Systemd Integration Guide를 참조하십시오.
배포 추적(Deployment Tracking) (Sidekiq 7+)
Sidekiq 7은 배포 추적 기능이 포함된 메트릭을 도입했습니다. 이 기능을 활성화하면 Sidekiq 메트릭 그래프에서 배포 마커를 볼 수 있습니다:
설정 (Configuration)
작동 방식 (How It Works)
활성화하면 gem은 다음 작업을 수행합니다:
- 성공적인 배포 후 자동으로 배포를 표시합니다.
- Sidekiq의 메트릭 그래프에 수직 빨간색 선을 보여줍니다.
- 마커 위로 마우스를 가져가면 배포 레이블이 표시됩니다.
이는 성능 변화와 배포 간의 상관관계를 파악하는 데 도움이 됩니다.
Sidekiq Enterprise (Swarm) 지원
이 gem은 단일 서비스로 여러 프로세스를 관리하는 Sidekiq Enterprise의 sidekiqswarm 명령을 지원합니다.
설정 (Configuration)
Sidekiqswarm의 이점
- 단일 서비스: 하나의 systemd 서비스를 사용하여 N개의 프로세스를 관리합니다.
- 메모리 효율성: 앱을 한 번 로드한 후, 포크(fork)하여 프로세스를 실행합니다.
- 자동 재시작 (Auto-restart): 메모리 제한을 초과하는 프로세스는 자동으로 재시작됩니다.
- 단순화된 관리: 여러 개의 서비스 파일이 필요하지 않습니다.
서버별 Swarm 설정
server 'worker1.example.com',
roles: [:worker],
sidekiq_service_unit_env_vars: ['SIDEKIQ_COUNT=20', 'SIDEKIQ_MAXMEM_MB=1024']
...
Systemd 로그 작업 (Working with Systemd Logs)
journalctl을 사용하여 Sidekiq 서비스 로그를 확인합니다:
journalctl -u sidekiq_myapp_production -n 100
...
로그 파일 설정 (Log File Configuration)
최신 Systemd (v240 이상, 예: Ubuntu 20.04+)
로그 파일은 systemd 서비스 파일의 append: 기능을 사용하여 자동으로 구성됩니다.
레거시 Systemd 시스템
append: 기능이 지원되지 않는 구형 Systemd 버전을 사용하는 시스템의 경우:
- Sidekiq 메시지는 기본적으로 syslog로 전송됩니다.
- 시스템 로거를 구성하여 Sidekiq 메시지를 필터링합니다.
- 자세한 설정 지침은 wiki를 참조하십시오.
예제 애플리케이션 (Example Application)
이 gem의 사용법을 시연하는 전체 예제 애플리케이션은 다음에서 확인할 수 있습니다:
기여 방법
- 저장소 포크(Fork)하기
- 기능 브랜치 생성하기 (
git checkout -b my-new-feature)
- 변경 사항 커밋하기 (
git commit -am 'Add some feature')
- 브랜치로 푸시(Push)하기 (
git push origin my-new-feature)
- 새로운 풀 리퀘스트(Pull Request) 생성하기
