[Redmine] 1편: Redmine 5.0.5에서 6.1로의 메이저 업데이트 가이드 (feat. Docker 환경과 플러그인 호환성 검증)

안녕하세요, IDSTORY: 테크에 로그인의 담덕입니다!

지난번 "시작하는 글: 왜 다시 레드마인인가?" 포스팅을 통해 제가 2026년에 다시 고전 레드마인을 꺼내 들고 시놀로지 NAS(Docker) 환경에서 구축하게 된 이유를 말씀드렸습니다 약속드렸던 대로, 오늘부터 본격적인 레드마인 운영 노하우를 연재 형식으로 풀어보고자 합니다.

첫 번째 이야기의 주제는 바로 가장 까다롭고도 중요한 "메이저 업데이트"입니다.

사실 제가 실무에서 운영 중이던 레드마인 5.0.5 버전은 이미 2025년 9월 22일(레드마인 6.1.0 릴리즈 시점)을 기점으로 공식적인 업데이트가 종료된 상태였습니다. 보안과 새로운 기능들을 온전히 누리기 위해서는 메이저 업그레이드가 필수적인 타이밍이었죠.

이번 메이저 업데이트(Redmine 5.0.5 → 6.1.1)를 진행하며 겪었던 DB 마이그레이션 도전과 피벗(Pivot), 이메일 설정 오류 해결책, 그리고 플러그인 호환성 테스트 결과까지 실무의 생생한 기록을 담아 가이드로 정리해 드립니다. 저와 함께 레드마인의 세계로 깊숙이 로그인해 보시죠!

1. 메이저 업데이트의 큰 그림과 첫 번째 장벽

이번 프로젝트의 목표는 명확했습니다. 기존 Redmine 5.0.5 환경을 최신 안정 버전인 6.1.1로 안전하게 마이그레이션하는 것이었죠.

• 기존 환경: Redmine 5.0.5 (sameersbn/redmine 튜닝 이미지 기반)
• 목표 환경: Redmine 6.1.1 (Redmine 오리지널 공식 도커 이미지 기반)

여기서 첫 번째 장벽을 만났습니다. 기존에 사용하던 이미지는 편리하게 개조된 sameersbn/redmine인 반면, 새로 올릴 이미지는 순정 오리지널 redmine 이미지였기에 컨테이너 환경 변수와 디렉토리 매핑 등 환경 세팅을 완전히 새로 해야 했습니다.

2. DB 마이그레이션의 도전: 협업을 위한 정렬과 기술적 호기심, 그리고 현실적인 피벗(Pivot)

사실 레드마인 공식 설치 가이드를 보면 PostgreSQL을 단독으로 강력하게 권장하지는 않습니다. 추천 데이터베이스 목록에는 PostgreSQL, MySQL, MSSQL, SQLite 4가지가 동등한 후보군으로 나란히 이름을 올리고 있죠.

하지만 당시 사내 일감 기록에는 '기본 권장 사항인 PostgreSQL로 업그레이드 마이그레이션 테스트를 진행한다'고 간단하게 적혀 있었습니다. 여기에는 기록에 다 담기지 않은 두 가지 진짜 비하인드 스토리가 있었습니다.

• 개발팀과의 기술적 얼라인(Align): 당시 긴밀하게 협업하고 있던 개발팀의 주력 데이터베이스 스택이 바로 PostgreSQL이었습니다. 협업 효율성과 기술 인프라 정렬 측면에서 DB를 통일하면 장기적으로 시너지가 날 것이라 판단했죠.
• 엔지니어로서의 개인적 호기심: 그동안 실무에서 PostgreSQL을 깊이 있게 다뤄볼 기회가 적었습니다. 이번 메이저 업데이트와 인프라 개편을 기회 삼아 PostgreSQL을 제대로 경험하고 다루는 기술적 챌린지를 스스로에게 던져보고 싶었습니다.

그렇게 호기롭게 시작된 DB 마이그레이션은 예상보다 까다로운 과정이었습니다.

1. 테스트 가동: 먼저 PostgreSQL 17.7 및 18.1 도커 이미지를 가동하고 접속 테스트까지 무사히 성공했습니다. 여기까지는 순탄하게 진행되는 듯했습니다.
2. 이관 실패와 난관: 하지만 기존 MariaDB 환경에서 테이블 구조와 원본 데이터를 덤프해 PostgreSQL로 이관을 시도하는 과정에서 다양한 오류가 발생하기 시작했습니다. MariaDB와 PostgreSQL 간의 내부 SQL 쿼리 문법, 데이터 구조 매핑의 미세한 격차가 생각보다 컸기 때문입니다. 마이그레이션 중 쿼리 에러가 반복되었고, 결과적으로 데이터가 정상적으로 입력되지 않았습니다.
3. 현실적인 결단과 빠른 피벗(Pivot): 이 스키마 격차와 에러들을 하나씩 코드로 직접 수정해가며 해결하기엔 시간과 리소스 소모가 너무나도 막대했습니다. 결국 메이저 업데이트라는 본래의 목적을 안정적으로 달성하기 위해 PostgreSQL로의 전환을 포기했습니다. 대신 현실적인 선택으로 기존의 MariaDB 기반 설정을 유지하기로 빠르게 피벗(Pivot)했습니다.
4. MariaDB 최신화: 기존 MariaDB 환경을 유지하되, 최신 안정 버전인 mariadb:12.1.2를 추가 구축하여 레드마인 6.1.1 컨테이너와 연결했습니다.

피벗 이후의 마이그레이션 작업은 매끄럽게 진행되었습니다. 기존에 백업해 두었던 원본 데이터가 한 번에 성공적으로 마이그레이션되며, 레드마인 6.1.1이 안정적으로 구동되는 것을 확인했습니다.

💡 실무 팁:

운영 중인 프로덕션 레드마인의 DB 브랜치(DBMS 종류)를 전환하는 것은 단순한 버전 업보다 몇 배는 높은 비용이 따릅니다. 협업팀의 인프라 스택 변경이나 특별한 요구사항이 없다면, 기존에 사용 중인 DBMS의 안정적인 최신 버전을 유지하는 것이 리소스를 절약하는 가장 합리적인 선택입니다.

3. 메일 알림(SMTP) 설정 오류 해결법

DB 이관을 마친 후 또 다른 자잘한 문제가 있었습니다. 바로 이메일 알림 기능이었습니다.

처음에는 편하게 docker-compose.yaml 파일에 메일 관련 환경 변수(SMTP 설정 등)를 직접 주입해 기동하려고 했으나, 환경 변수가 정상적으로 주입되지 않으며 이메일 설정이 실패했습니다.

• 해결 방법: 환경 변수 직접 주입 대신, 레드마인 공식 메일 설정 파일인 configuration.yml 파일을 로컬에 직접 생성하여 상세 SMTP 설정을 입력했습니다. 그리고 해당 파일을 도커 볼륨 마운트 기능(-v 또는 volumes)을 통해 레드마인 컨테이너 내부 설정 경로(config/configuration.yml)로 마운트하여 기동했습니다. 이 방법을 적용하자마자 메일 알림이 정상적으로 송수신되는 것을 확인할 수 있었습니다.

4. 플러그인 호환성 매트릭스 (5.0.5 vs 6.1.1)

레드마인 메이저 업데이트에서 가장 신중한 검증이 필요한 단계는 단연 "플러그인 호환성 검증"입니다. 메이저 버전이 올라가면 작동하지 않는 플러그인이 수두룩하기 때문이죠.

이번 6.1.1 업그레이드 과정에서 검증한 플러그인 리스트와 조치 내역을 한눈에 보실 수 있게 정리했습니다.

1. 업그레이드 및 설치 완료 플러그인 (정상 작동)
• Additionals: 3.0.9 ➔ 4.3.0 (핵심 라이브러리 역할)
• Easy Baseline / Easy Gantt / PRO Easy Gantt: 2.0 ➔ 3.0 (간트차트 필수 3총사)
• Advanced checklists (Free): 2.3.8 ➔ 2.4.2 (일감 내 체크리스트 제공)
• RedMica UI extension: 0.3.10 ➔ 0.5.0 (UI 사용성 세련되게 개선)
• Redmine Banner plugin: 0.3.4 유지 (전체 공지용 배너 등록)
• Redmine Drawio plugin: 1.5.3 유지 (위키/일감 내 다이어그램 드로잉)
• Redmine People plugin (Light version): 1.6.8 ➔ 1.6.12
• Submenus: 0.2.0 ➔ 0.2.1
• Redmine Theme Changer plugin: 0.7.0 ➔ 0.7.1
• Redmine Wiki Extensions plugin: 0.9.5 ➔ 1.2.0
• View Customize plugin: 3.5.4 유지 (UI CSS/JS 동적 커스텀 최강자)
• Redmine Issue Templates plugin: 1.1.2 ➔ 1.2.2 (일감 작성 템플릿)
• Issue To-do Lists Plugin (reworked): 2.2.2 유지 (할 일 목록 수동 정렬)
• Vault plugin: 0.8.1 ➔ 0.10.2 (※ 플러그인 내부 루비 소스 코드 수동 수정 후 정상 빌드 완료)
• Redmine Wiki Text Colorizer plugin: 신규 설치 (0.1.4 적용, 에디터 글자/배경색 추가)
• Redmine Spreadsheet Editor plugin: 신규 설치 (0.0.1 적용, 엑셀 시트 방식 일감 관리)
• Additional Tags: 신규 설치 (4.3.0 적용, 일감/위키 태그 기능 강화)
• RedmineX Lightbox2 (Lightbox 대체): 기존 1.0.0에서 최신 2.0.0 설치 테스트 중 오류가 발견되어, 최종적으로 Lightbox v2.0.0 플러그인으로 변경 설치하여 깔끔하게 대체 성공
2. 6.x 메이저 버전 미지원으로 인한 적용 불가 (보류)
   업데이트 진행 당시 아래 플러그인들은 레드마인 6.x 계열을 지원하지 않아 배포 항목에서 제외하게 되었습니다.
• Redmine ONLYOFFICE integration plugin: 실무에서 문서 관리에 유용했으나, 현재 5.x 버전만 공식 지원하여 6.x 호환 플러그인이 나올 때까지 적용 보류.
• Redmine WYSIWYG Editor plugin (Visual Editor): 6.x 기동 시 에러 발생으로 인해 사용 불가 판정.
• Module manager plugin: 6.x 미지원.
• Redmine Enhanced UX plugin / Redmine Impersonate / Redmine XLSX format exporter: 모두 6.x 미지원으로 임시 사용 중단.
3. 사용성 저조 및 자체 기능 대체로 인한 미설치
   실제 활용도와 리포지토리 경량화를 위해 정리한 플러그인들입니다.
• Easy MindMup / Easy WBS: 사용량이 거의 없어 정리.
• Redmine Issues Tree plugin: 레드마인 6.x 자체에서 일감 목록 트리 보기를 기본 지원(접기 기능은 불가능하지만 쓸만함)하여 플러그인 미설치.
• Redmine Shortcuts / Redmine Issue Attachments / Redmine Logs: 사용률 저조로 미설치.

5. 실전 배포 D-Day: 30분 만의 롤오버 워크플로우

철저하게 테스트 서버에서 검증을 마친 후, 드디어 업무 시간 외에 실제 서비스 배포 일정을 잡았습니다. 제가 수립하고 진행했던 배포 D-Day 가이드입니다.

1. 사용자 접속 제한: 기존 레드마인 5.0.5의 접속을 차단하여 추가 데이터 적재를 막습니다.
2. 이전 데이터 백업: 기존 MariaDB 컨테이너에서 DB 데이터를 백업(Backup) 받아둡니다.
3. 새로운 DB 복구: 신규 구축한 mariadb:12.1.2 컨테이너에 백업받은 데이터를 복구(Restore)합니다.
4. 새 버전 기동 및 마이그레이션: Redmine 6.1.1 컨테이너를 실행하고, 내부 데이터베이스 마이그레이션 명령어(bundle exec rake db:migrate)를 통해 테이블 구조를 새 버전에 맞게 업그레이드합니다.
5. 플러그인 일괄 빌드 및 적용: 사전에 테스트가 완료된 6.1.1 호환 플러그인 파일들을 복사해 넣고 플러그인 마이그레이션을 실행합니다.
6. 최종 기능 검증 및 서비스 오픈: 이메일 알림, 핵심 플러그인 동작 상태를 테스트한 뒤 도메인을 신규 서버로 전환하여 배포를 완료합니다!

마무리하며: 메이저 업데이트를 마치고

업무 외 시간에 진행된 약 30여 분 동안의 배포 작업 끝에, 저희 회사의 협업 중심축인 레드마인은 성공적으로 6.1.1 버전으로 완전히 전환되었습니다.

비록 ONLYOFFICE와 WYSIWYG 에디터를 당장 쓰지 못하게 된 아쉬움은 있지만, 훨씬 안정적이고 보안이 강화된 환경에서 더 매끄럽고 빠른 협업 환경을 구축했다는 점에서 팀원들 모두 만족스러워하고 있습니다.

다음 포스팅인 **"2편: 업무 효율을 극대화하는 필수 플러그인 Best 5"**에서는 이번에 업데이트를 마치고 정착한 플러그인 중, 실무진들이 유용하다고 평가한 핵심 플러그인들 위주로 딥다이브해 보겠습니다.

다음 레드마인 이야기도 기대되신다면, IDSTORY: 테크에 로그인해 주세요! 독자 여러분의 피드백이나 질문은 언제나 환영합니다. 댓글로 편하게 의견 남겨주세요!