Rocky Linux에 Redmine 설치(4.2.3) — PostgreSQL + Apache/Passenger 구성 가이드

이 문서는 Rocky Linux 8.4에 Redmine 4.2.3을 PostgreSQL 데이터베이스와 Apache(httpd) + Phusion Passenger로 배포하는 단계별 가이드입니다. RVM으로 Ruby 2.7을 설치하고, 데이터베이스 생성, 번들 의존성 설치, Passenger 및 가상호스트 설정, SSL(Optional) 구성, 그리고 초기 관리자 계정 설정과 검증까지 다룹니다. 문제 해결, 보안 권장사항, 운영 체크리스트, 업그레이드/백업 팁도 포함되어 있습니다.

개요

Redmine은 오픈소스 프로젝트 관리 및 이슈 추적 웹 애플리케이션으로 Ruby on Rails로 작성되었습니다. 다중 프로젝트, 위키, 포럼, 이슈 트래킹, 시간 추적, 다양한 SCM 연동 등을 지원하며 GNU GPL v2 라이선스로 배포됩니다. 본 가이드는 프로덕션 환경을 염두에 두고 Apache/httpd와 Passenger를 사용한 배포를 설명합니다.

중요 용어 한 줄 정의

• RVM: Ruby Version Manager, 시스템에 여러 Ruby 버전을 설치·관리하는 도구입니다.
• Passenger: Rails 애플리케이션을 Apache 또는 Nginx와 연동해 구동하는 애플리케이션 서버입니다.

환경 (예시)

• 운영체제: Rocky Linux 8.4 (Green Obsidian)
• 서버 IP: 192.168.1.10
• 루트 권한 필요
• 도메인: redmine.example.com
• Redmine 버전: 4.2.3
• Ruby: 2.7 (RVM으로 설치)
• 데이터베이스: PostgreSQL
• 웹서버: Apache/httpd + Passenger

목표

• RVM을 통한 Ruby 설치
• PostgreSQL 데이터베이스 설정
• Passenger 설치 및 Apache 연동
• Apache 가상호스트(HTTP/HTTPS) 설정
• Redmine 설치 및 초기 구성

중요: 본 가이드를 진행하기 전에 PostgreSQL이 설치되어 있어야 합니다. (별도 설치 가이드 참조)

사전 요구사항 및 종속 패키지 설치

다음 패키지들은 Redmine 소스 빌드와 런타임에 필요합니다. 모든 명령은 루트 또는 sudo 권한으로 실행하세요.

1. EPEL 저장소 추가

sudo dnf install epel-release -y

2. 필수 빌드 도구 및 라이브러리 설치

sudo dnf install curl gpg gnupg2 gcc gcc-c++ make patch autoconf automake bison ImageMagick libffi-devel libtool patch redhat-rpm-config readline-devel postgresql-devel zlib-devel openssl-devel -y

3. Apache/httpd 관련 개발 패키지 설치

sudo dnf install libcurl-devel httpd-devel httpd apr-devel apr-util-devel -y

httpd 설치가 완료되면 서비스 시작 및 부팅 시 자동 시작을 활성화합니다.

sudo systemctl enable --now httpd
sudo systemctl status httpd

중요: 방화벽(firewalld)이나 네트워크 ACL이 HTTP(80) 또는 HTTPS(443)를 차단하지 않는지 확인하세요.

RVM 및 Ruby 설치

Redmine 4.2.3은 Ruby 2.7을 요구합니다. RVM을 사용해 시스템에 Ruby 2.7을 설치합니다.

1. RVM GPG 키 가져오기

curl -sSL https://rvm.io/mpapis.asc | gpg2 --import -
curl -sSL https://rvm.io/pkuczynski.asc | gpg2 --import -

2. RVM 설치 및 환경 로드

curl -L get.rvm.io | bash -s stable
source /etc/profile.d/rvm.sh

3. RVM 요구사항 확인 및 의존성 자동 처리

rvm reload
rvm requirements run

4. Ruby 2.7 설치

rvm install 2.7

설치가 완료되면 버전 목록과 현재 사용 중인 Ruby를 확인합니다.

rvm list
ruby --version

참고: 시스템에 여러 Ruby 버전이 존재할 경우 프로젝트별로 RVM에서 사용 버전을 지정할 수 있습니다.

PostgreSQL 데이터베이스 설정

PostgreSQL이 이미 설치되어 있다는 전제 하에 Redmine 전용 데이터베이스와 사용자를 생성합니다.

1. PostgreSQL 셸 진입

sudo -u postgres psql

2. Redmine용 역할 및 데이터베이스 생성 (강력한 비밀번호로 변경하세요)

CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'StrongPasswordRedmine' NOINHERIT VALID UNTIL 'infinity';
CREATE DATABASE redminedb WITH ENCODING='UTF8' OWNER=redmine;

\q

보안 팁: 외부 접근이 필요 없다면 pg_hba.conf 및 postgresql.conf에서 127.0.0.1 (또는 소켓)만 허용하고, 데이터베이스 접근 권한을 최소화하세요.

Redmine 설치 및 초기 구성

이 가이드는 Redmine 4.2.3 소스를 /var/www/redmine에 설치합니다.

1. Redmine 소스 다운로드 및 압축 해제

cd /var/www/
wget https://www.redmine.org/releases/redmine-4.2.3.tar.gz

tar -xzvf redmine-4.2.3.tar.gz
mv redmine-*/ redmine

2. 데이터베이스 설정 파일 작성

export REDMINE=/var/www/redmine
cd $REDMINE
nano config/database.yml

config/database.yml 내용 (환경에 맞춰 값 변경)

production:
  adapter: postgresql
  database: redminedb
  host: localhost
  username: redmine
  password: "StrongPasswordRedmine"
  encoding: utf8

3. Bundler 설치 및 의존성 구성

gem install bundler
bundle config set --local path 'vendor/bundle'
bundle config set --local without 'development test'
bundle install

성공적으로 패키지가 설치되면 다음 단계로 진행합니다.

4. 시크릿 토큰 생성 및 DB 마이그레이션

bundle exec rake generate_secret_token
RAILS_ENV=production bundle exec rake db:migrate

5. 파일 소유권 변경 (Apache의 기본 사용자로 설정)

sudo chown -R apache:apache $REDMINE

중요: Redmine 설치 디렉터리에 대한 권한은 최소 권한 원칙을 따르되, 업로드/로그/파일 저장소가 웹서버에서 쓰기 가능해야 합니다. 디렉터리 권한은 보안 정책에 맞게 제한하세요.

Passenger 설치 및 Apache 연동

Passenger는 Ruby 애플리케이션을 Apache에서 안정적으로 실행할 수 있게 해주는 모듈입니다.

1. Passenger RubyGem 설치

gem install passenger

2. Apache용 Passenger 모듈 설치

passenger-install-apache2-module

설치 프로그램의 지시를 따르고 필요한 경우 Enter를 눌러 계속합니다. Ruby를 애플리케이션 플랫폼으로 선택하세요.

설치가 완료되면 출력되는 Apache 설정 조각을 /etc/httpd/conf.d/passenger.conf로 복사합니다.

nano /etc/httpd/conf.d/passenger.conf

예시 (RVM 경로는 설치 환경에 따라 다릅니다. 실제 경로를 확인하여 적용하세요.)

   LoadModule passenger_module /usr/local/rvm/gems/ruby-2.7.2/gems/passenger-6.0.12/buildout/apache2/mod_passenger.so
   
     PassengerRoot /usr/local/rvm/gems/ruby-2.7.2/gems/passenger-6.0.12
     PassengerDefaultRuby /usr/local/rvm/gems/ruby-2.7.2/wrappers/ruby
   

설정 저장 후 Apache 재시작

sudo systemctl restart httpd

설치 확인이 성공적으로 출력되면 Passenger 모듈이 정상적으로 로드된 것입니다.

문제 발생 시: Apache 에러 로그(/var/log/httpd/error_log)와 Passenger 설치 로그를 확인하세요.

Apache(httpd) 가상호스트 설정 (HTTP 및 HTTPS)

Redmine을 서비스하기 위한 가상호스트 파일을 생성합니다.

1. HTTP 기본 설정

nano /etc/httpd/conf.d/redmine.conf

아래 내용을 복사하여 도메인에 맞게 수정하세요.

PassengerRuby /usr/local/rvm/gems/ruby-2.7.2/wrappers/ruby


    ServerName redmine.example.io
    DocumentRoot "/var/www/redmine/public"

    ErrorLog logs/redmine_error_log
    LogLevel warn

    
        Options Indexes ExecCGI FollowSymLinks
        Require all granted
        AllowOverride all
    

2. HTTPS(SSL) 설정 예시 — Let’s Encrypt 경로 예시 포함

SSL 사용 시 mod_ssl을 활성화하고 인증서 경로를 실제 경로로 변경하세요.

PassengerRuby /usr/local/rvm/gems/ruby-2.7.2/wrappers/ruby


  ServerName redmine.example.io
  Redirect permanent / https://redmine.example.io/



  ServerName redmine.example.io

  Protocols h2 http/1.1

  
    Redirect permanent / https://redmine.example.io/
  

  DocumentRoot "/var/www/redmine/public"

  ErrorLog /var/log/httpd/redmine.example.io-error.log
  CustomLog /var/log/httpd/redmine.example.io-access.log combined

  SSLEngine On
  SSLCertificateFile /etc/letsencrypt/live/redmine.example.io/fullchain.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/redmine.example.io/privkey.pem

  
    Options Indexes ExecCGI FollowSymLinks
    Require all granted
    AllowOverride all
  

구성 확인 및 재시작

apachectl configtest
sudo systemctl restart httpd

팁: Let’s Encrypt를 사용하려면 certbot을 설치해 인증서를 발급하고 자동 갱신 설정을 구성하세요.

설치 검증 및 초기 로그인

브라우저에서 https://redmine.example.io/login 로 접속합니다.

기본 관리자 계정: 사용자명 admin, 비밀번호 admin

1. 로그인 후 관리자 암호를 즉시 변경하세요.

2. 기본 암호 변경

3. 계정 정보 확인 및 저장

4. 관리 대시보드 진입 및 초기 설정

처음 로그인 시 기본 언어 구성을 불러오는 옵션이 있습니다. 운영 환경에 맞는 언어를 선택하고 기본 구성을 로드하세요.

사용자 목록과 설치 정보 확인

설치가 성공적으로 완료되면 Redmine 4.2.3이 Ruby 2.7 및 PostgreSQL 위에서 동작합니다.

보안 권장사항

• HTTPS 적용은 필수입니다. Let’s Encrypt 또는 유효한 SSL 인증서를 사용하세요.
• 데이터베이스 사용자 권한은 최소화(Least Privilege)를 적용하세요.
• config/secrets.yml 또는 환경변수로 시크릿 토큰을 안전하게 관리하세요.
• Redmine 파일 권한은 웹서버가 필요한 파일만 쓰도록 최소화하세요.
• 정기적으로 OS 및 패키지 보안 업데이트를 적용하세요.
• 백업: 데이터베이스와 파일 저장소(public/uploads 등)를 정기 백업하세요.
• 플러그인 설치 시 신뢰할 수 있는 출처만 사용하고 테스트 환경에서 먼저 검증하세요.

참고: SELinux가 활성화된 시스템에서는 httpd 및 Passenger가 파일에 접근할 수 있도록 적절한 SELinux 컨텍스트를 설정해야 합니다. (예: restorecon, chcon 활용)

운영 체크리스트 (역할별)

시스템 관리자

• 방화벽 포트(80,443) 열기 확인
• Apache 및 Passenger 서비스 상태 모니터링
• 자동 백업 스케줄 설정
• SSL 자동 갱신(certbot 등)

Redmine 관리자

• 초기 admin 비밀번호 변경
• 사용자 및 권한 모델(역할, 그룹) 구성
• 프로젝트 템플릿 및 워크플로우 설정
• 이메일(SMTP) 알림 설정 및 테스트

개발자/플러그인 관리자

• 플러그인 호환성 확인(Redmine 버전)
• 테스트 환경에서 플러그인 검증
• 의존성 및 번들 업데이트 관리

사용자(일반)

• 로그인 및 프로필 정보 업데이트
• 프로젝트 생성/이슈 작성 기본 절차 숙지
• 권한에 따른 액세스 범위 확인

문제 해결 가이드 (자주 발생하는 오류와 대처법)

1. Passenger 모듈을 로드하지 못함

• 원인: LoadModule 경로가 RVM 또는 gem 설치 경로와 다름
• 해결: passenger-install-apache2-module의 출력에서 지시한 정확한 LoadModule 및 PassengerRoot 경로로 /etc/httpd/conf.d/passenger.conf를 업데이트하고 Apache 재시작

2. bundle install 중 빌드 실패

• 원인: 필요한 개발 헤더(libxml2-devel 등) 누락
• 해결: 에러 메시지의 부족한 패키지를 설치한 후 bundle install 재실행

3. DB 연결 실패

• 원인: database.yml의 자격증명 오류 또는 PostgreSQL이 외부 연결을 차단
• 해결: database.yml 값 검토, psql로 직접 접속해 계정/권한 확인, pg_hba.conf 설정 확인

4. 500 Internal Server Error

• 원인: 레일스 환경설정 오류, 권한 문제, 시크릿 토큰 미설정
• 해결: /var/log/httpd/error_log 및 /var/www/redmine/log/production.log 확인, 파일 권한 및 시크릿 토큰 존재 여부 점검

로그 확인 명령 예시

sudo tail -n 200 /var/log/httpd/error_log
sudo tail -n 200 /var/www/redmine/log/production.log

업그레이드 및 유지관리 팁

• 업그레이드 전 반드시 데이터베이스 및 파일 시스템 전체 백업 수행
• Redmine 업그레이드는 소스 교체 후 bundle install 및 db:migrate를 수행합니다
• 플러그인 호환성은 업그레이드 중 가장 큰 리스크이므로 테스트 환경에서 미리 검증하세요
• 보안 패치 적용 시 서비스 중단 시간을 고려한 유지보수 윈도우를 계획하세요

백업 및 복구 간단 절차

백업

• PostgreSQL 덤프

sudo -u postgres pg_dump -Fc redminedb > /path/to/backup/redminedb-$(date +%F).dump

• 파일 업로드/첨부 등 직접 저장되는 디렉터리 복사

rsync -avz /var/www/redmine/files /backup/location/redmine-files-$(date +%F)/

복구

• 데이터베이스 복원

sudo -u postgres pg_restore -d redminedb /path/to/backup/redminedb-YYYY-MM-DD.dump

• 파일 복원: rsync 또는 cp로 원위치 복사 후 권한 재설정

sudo chown -R apache:apache /var/www/redmine

플러그인 설치(요약)

1. plugins 디렉터리에 플러그인 코드 복사
2. 플러그인 디렉터리에서 bundle install 실행(필요 시)
3. Rails 마이그레이션이 필요한 플러그인은 실행

cd /var/www/redmine
bundle install
RAILS_ENV=production bundle exec rake redmine:plugins:migrate
sudo systemctl restart httpd

플러그인 설치 전 반드시 호환성(레드마인 버전, Ruby 버전)을 확인하세요.

점검표 및 수용 기준

설치 완료 수용 기준

• Redmine 웹 UI가 https로 접속되고 로그인 가능
• 관리자(admin)로 로그인 후 비밀번호 변경 완료
• 프로젝트 생성 및 이슈 생성/조회 동작 확인
• 이메일 알림(설정한 경우) 테스트 통과
• 정기 백업 스크립트가 동작하도록 설정됨

유용한 명령 요약(치트시트)

• Apache 재시작: sudo systemctl restart httpd
• Passenger 모듈 정보 확인: passenger-config about ruby-command
• Bundler 설치: gem install bundler
• 의존성 설치: bundle install
• DB 마이그레이션: RAILS_ENV=production bundle exec rake db:migrate

결론

축하합니다! 이 가이드에서 Rocky Linux 8.4에 Redmine 4.2.3을 PostgreSQL과 Apache/Passenger로 설치하는 전체 과정을 살펴보았습니다. RVM으로 Ruby 2.7을 설치하고, 데이터베이스 설정, 번들 의존성 설치, Passenger 통합, Apache 가상호스트(HTTP 및 HTTPS) 구성, 초기 관리자 계정 설정과 검증, 그리고 운영 및 보안 권장사항까지 다루었습니다.

다음 권장 작업

• SMTP 설정을 통해 메일 알림 활성화
• 필요한 플러그인을 테스트 환경에서 검증 후 운영으로 적용
• 자동화된 백업 및 모니터링(로그, 서비스 헬스체크) 구성

중요

운영 환경에서는 항상 변경 전 백업을 수행하고, 테스트 환경에서 변경을 검증한 뒤 프로덕션에 적용하세요.

요약

Redmine은 유연한 프로젝트 관리 도구이며, Apache + Passenger + PostgreSQL 조합은 안정적인 프로덕션 배포 환경을 제공합니다. 본 문서를 참조해 설치 및 운영 절차를 체계적으로 구성하세요.