데비안 시스템의 Confluence 서버에서 MySQL을 PostgreSQL로 마이그레이션 한 과정을 보여주려고 한다. 내가 사용하는 데비안 9(stretch)의 PostgreSQL 버전은 9.6이다. Confluence는 버전 6.13.8을 설치하고 있다. 먼저 이 버전의 Confluence에서 지원하는 데이터베이스를 볼 필요가 있다. Supported Platforms – Confluence 6.13을 보면 PostgreSQL 9.4, 9.5, 9.6을 지원하므로 마이그레이션을 진행할 수 있다. 작업을 진행하기 전에 MySQL의 데이터베이스와 Confluence 홈 디렉토리를 백업한다. 뒤에서 서술할 내용에서 Confluence의 설치 위치는 /opt/share/confluence, 홈 디렉토리는 /var/local/lib/confluence이다. 여러분이 이와 다르다면 참작해서 보기 바란다.
단계 1. Confluence에 설치한 Atlassian Marketplace 앱의 정보를 확인하기
단계 4에서 보겠지만 기존 버전과 같은 Confluence를 새로 설치하고 앞으로 그것을 사용해야 한다. 이전의 Confluence에 있던 앱들은 다시 설치해야 한다. 단계 2에서 생성하는 XML 포맷의 백업 파일에는 앱의 환경 설정 정보들을 가지고 있다. 이 안의 동일한 버전으로 앱을 설치해야 문제가 발생하지 않을 것이다. 같은 버전으로 쉽게 설치하기 위해 앱을 미리 업데이트해 주는 것이 좋을 것이다. 업데이트 후 앱 이름, 버전, 제작자, 활성화 여부를 기록해 둔다. 나의 경우는 다음과 같다.
- Atlassian Troubleshooting and Support Tools / 1.25.0 / Atlassian / enabled
- Atlassian Universal Plugin Manager Plugin / 3.0.6 / Atlassian / enabled
- Confluence Cloud Migration Assistant / 2.6.0 / Atlassian / enabled
- Confluence Mobile Plugin / 2.2.4 / Atlassian / enabled
- Refined for Confluence / 6.1.15 / Refined / enabled
- RefinedMobile for Confluence / 3.3.2 / RefinedWiki / enabled
- Gliffy Diagrams for Confluence / 8.6.5 / Gliffy, Inc. / enabled
- LaTex Math / 3.9.13 / Bolo Software / enabled
단계 2. XML 포맷으로 데이터를 백업하기
이 단계를 진행할 때 http://192.168.1.10:8090/confluence/admin/backup.action 주소처럼 Confluence 서버에 직접 연결한다. IP 주소는 Confluence를 설치한 시스템의 주소로 여러분에게 맞는 것을 입력한다. Proxy 등과 같이 Confluence 전단의 Apache로 접속하여 작업하면 에러가 날 가능성이 크다. IP 주소로 직접 접속할 때 Confluence의 base URL을 변경하라는 메시지가 나오면 무시하고 진행해도 괜찮다. 다음과 같이 작업한다.
- Confluence 설정으로 들어가서 ADMINISTRATION > Backup & Restore를 클릭한다.
- Export this site에서 디폴트 선택인 Include attachments 체크를 그대로 둔 채 Export 버튼을 클릭한다. 백업할 데이터가 크다면 시간이 오래 걸린다. 인내심을 가지고 기다린다.
- 작업이 완료되면 새로운 창에서 다음과 같이 백업 성공 메시지와 백업 파일의 저장 위치가 나온다. 그리고 24시간 안에 이 파일이 지워질 것을 알려준다. 나는 Proxy Error가 한 번 발생해서 xmlexport-20200524-215026-2.zip처럼 끝에 -2가 붙었다. 이후에 이 파일을 복원에 사용할 것이다.
The backup was successfully created at /var/local/lib/confluence/temp/xmlexport-20200524-215026-2.zip. This file will be deleted in 24 hours.
attachments가 너무 크다면 Include attachments를 체크하지 않는 것이 좋을 수도 있다. 이 경우 단계 5의 다음 단계에서 이전 Confluence의 attachments를 새 Confluence로 복사해야 할 것이다. 다음의 명령어 실행으로 attachments의 크기를 알아볼 수 있다.
# du -h /var/local/lib/confluence/attachments ... 4.6G /var/local/lib/confluence/attachments
du의 -h 옵션은 크기를 읽기 쉽게 K, M, G로 표시해 준다. 나의 경우 4.6 기가바이트가 나왔는데 attachments 디렉토리를 포함하여 XML 포맷으로 백업할 수 있었다.
단계 3. PostgreSQL의 데이터베이스 만들기
Confluence에서 사용할 PostgreSQL의 데이터베이스를 생성한다. 다음은 psql 클라이언트를 사용한 진행 과정이다.
# psql -h localhost -U postgres -d postgres
psql (9.6.17)
SSL 연결정보 (프로토콜: TLSv1.2, 암호화기법: ECDHE-RSA-AES256-GCM-SHA384, 비트: 256, 압축: off)
도움말을 보려면 "help"를 입력하십시오.
postgres=# CREATE ROLE confluence WITH LOGIN PASSWORD '원하는 암호 입력';
CREATE ROLE
postgres=# CREATE DATABASE confluence WITH ENCODING='UTF8' OWNER=confluence;
CREATE DATABASE
postgres=# \l
데이터베이스 목록
이름 | 소유주 | 인코딩 | Collate | Ctype | 액세스 권한
------------+------------+--------+-------------+-------------+-----------------------
confluence | confluence | UTF8 | ko_KR.UTF-8 | ko_KR.UTF-8 |
jira | jira | UTF8 | C | C |
postgres | postgres | UTF8 | ko_KR.UTF-8 | ko_KR.UTF-8 |
template0 | postgres | UTF8 | ko_KR.UTF-8 | ko_KR.UTF-8 | =c/postgres +
| | | | | postgres=CTc/postgres
template1 | postgres | UTF8 | ko_KR.UTF-8 | ko_KR.UTF-8 | =c/postgres +
| | | | | postgres=CTc/postgres
(5개 행)
라인 6에서 CREATE ROLE로 confluence 사용자를 만든다. 라인 8에서 CREATE DATABASE로 confluence 데이터베이스를 생성한다. Confluence의 데이터베이스는 인코딩과 Collation은 utf8로 설정해야 한다. 라인 10에서 \l 명령어로 새로 생성한 confluence 데이터베이스를 확인한다. PostgreSQL에 기본적인 사용은 PostgreSQL의 데이터베이스와 사용자 생성, 백업 및 복구를 참고할 수 있다.
단계 4. 현재 사용하는 Confluence와 같은 버전의 Confluence를 새로 설치하기
새로 설치하는 Confluence는 현재 사용하는 Confluence와 같은 버전이어야 한다. 그러나 설치 위치와 홈 디렉토리는 달라져야 한다. 다음과 같이 작업한다.
1. 현재 사용하는 Confluence를 종료한다.
2. 마이그레이션에 실패할 시 빠르게 원래대로 복구하기 위해 기존 Confluence의 설치 파일과 홈 디렉토리의 이름을 변경해 둔다.
# mv /opt/share/confluence /opt/share/confluence-old # mv /var/local/lib/confluence /var/local/lib/confluence-old
3. 새 Confluence를 위한 홈 디렉토리를 생성한다.
# mkdir /var/local/lib/confluence # cd /var/local/lib # chown confluence:confluence confluence # chmod g-s confluence
라인 4는 스티키 비트(sticky bit)를 사용하지 않으므로 제거한 것이다. 데비안에서 /var/local 디렉토리의 그룹에 스티키 비트가 있어 /var/local/lib/confluence 디렉토리에 스티키 비트가 붙는다. 여러분이 다른 Confluence 홈 디렉토리를 사용한다면 무시하고 넘어간다.
4. 기존 Confluece와 같은 버전의 TAR.GZ 압축 파일을 /opt/share에 복사한 후 다음의 절차로 /opt/share/confluece에 위치하도록 압축을 푼다.
# cd /opt/share # tar zxvf atlassian-confluence-6.13.8.tar.gz # mv atlassian-confluence-6.13.8 confluence # chown -R root:root confluence # chown -R confluence:confluence confluence/logs # chown -R confluence:confluence confluence/temp # chown -R confluence:confluence confluence/work
라인 4에서 7까지 파일의 소유주와 그룹을 설정하는 이유는 보안 때문이다. Confluence 데몬이 쓰기 권한을 가져야만 하는 logs, temp, work 디렉토리 이외에는 파일을 저장할 수 없도록 한다. 데몬(서비스)의 보안에 관해서는 Confluence, Jira, Bitbucket의 systemd unit 설정에서 볼 수 있다.
5. /opt/share/confluence/confluence/WEB-INF/classes/confluence-init.properties 파일에서 다음과 같이 Confluence Home Directory를 지정한다.
confluence.home=/var/local/lib/confluence
6. (선택적) Confluence에 접속할 때 웹 브라우저에 따라 언어를 설정하지 않도록 /opt/share/confluence/bin/setenv.sh 파일에 다음의 내용을 추가한다. Confluence에서 언어를 영어로 선택하여 항상 영문 메뉴가 나오도록 하기 위한 것이다.
CATALINA_OPTS="-Dconfluence.browser.language.enabled=false ${CATALINA_OPTS}"
단계 5. Confluence Setup Wizard를 진행하여 PostgreSQL로 마이그레이션 하기
1. 새로 설치한 Confluence 서버를 시작한 후 웹 브라우저로 http://192.168.1.10:8090/에 접속하여 Confluence setup wizard를 진행한다. IP 주소는 여러분에게 맞는 것으로 변경한다.
2. Get apps에서 Production Installation을 선택하고 Next 버튼을 클릭한다. Apps extend what Confluence can do. …에서 Confluece Questions, Confluece Team Calendars를 디폴트인 선택하지 않은 상태를 그대로 둔 채 Next 버튼을 클릭한다.
3. License key에서 Confluence의 라이센스를 입력하고 Next 버튼을 클릭한다. (https://my.atlassian.com/에 접속하여 라이센스 키를 복사할 수 있다.)
4. Set up your database에서 디폴트 선택인 My own database 선택을 그대로 둔 채 Next 버튼을 클릭한다. 다음의 설정을 한 후 Test connection 버튼을 클릭한다. 데이터베이스 연결에 성공한 메시지가 나오면 Next 버튼을 클릭한다.
- Database type: 디폴트 선택인 PostgreSQL을 그대로 둔다.
- Setup type: 디폴트 선택인 Simple을 그대로 둔다.
- Hostname: PostgreSQL이 설치된 시스템의 로컬 IP 주소를 입력한다. (예: 192.168.1.10)
- Post: 5432를 입력한다.
- Database name: 위에서 생성한 데이터베이스의 이름인 confluecne를 입력한다.
- Username: 위에서 생성한 데이터베이스의 사용자 이름인 confluence를 입력한다.
- Password: 위에서 생성한 데이터베이스의 ‘암호’를 입력한다.
5. Load Content에서 Restore From Backup 버튼을 클릭한다.
6. Restore Data 화면에서 Import form the home directory로 작업한다. 복원할 xmlexport-20200524-215026-2.zip 파일의 크기가 25MB보다 크기 때문이다.
6.1. 새로 설치한 Confluence 홈 디렉토리의 restore 디렉토리로 단계 2에서 생성한 xmlexport-20200524-215026-2.zip 파일을 복사하기 위해 다음의 명령어를 실행한다.
# cp -a /var/local/lib/confluence-old/temp/xmlexport-20200524-215026-2.zip /var/local/lib/confluence/restore/
cp의 -a 옵션은 파일의 속성인 소유자, 생성 날짜 등을 유지한 채 복사하기 위한 것이다.
6.2. 복사를 완료하였으면 Import from the home directory의 Import 버튼을 클릭한다. 에러 메시지와 함께 xmlexport-20200524-215026-2.zip 파일이 보이면 선택하고 다시 한번 Import 버튼을 클릭한다.
6.3. Restore 과정이 진행된다. Restore 과정이 끝난 후 Next 버튼을 클릭한다.
7. Setup Successful 화면에서 Start 버튼을 클릭한다.
단계 6. Atlassian Marketplace 앱을 다시 설치하기
단계 1에서 메모해 두었던 앱들을 같은 버전으로 다시 설치한다. Confluence 설정으로 들어가서 ATLASSIAN MARKETPLACE > Find new apps에서 앱을 검색할 수 있다. Atlassian이 제공하는 앱은 이미 설치되어 있으므로 간단하게 Update만 한다.
단계 7. 새로 설치한 Confluence를 위한 설정을 한다.
도메인의 URL 주소로 접속하기 위해 /opt/share/confluence/conf/server.xml 파일을 수정한다. 나의 경우 Apache의 Proxy를 사용하기 때문에 다음과 같이 한다.
<Context> 지시자의 path를 /confluence로 설정한다.
<Context path="/confluence" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
디폴트 <Connector> 지시자는 주석 처리한다. HTTS 상의 Proxying인 <Connector> 지시자의 주석을 제거하고 proxyName을 www.bitneer.dev로 변경한다.
<Connector port="8090" connectionTimeout="20000" redirectPort="8443"
maxThreads="48" minSpareThreads="10"
enableLookups="false" acceptCount="10" debug="0" URIEncoding="UTF-8"
protocol="org.apache.coyote.http11.Http11NioProtocol"
scheme="https" secure="true" proxyName="www.bitneer.dev" proxyPort="443"/>
Confluence를 다시 시작하고 웹 브라우저로 Confluence에 접속한다. Confluence 설정에 들어가서 CONFIGURATION > General Configuration의 Server Base URL을 도메인 주소에 맞게 설정한다.
단계 8. 문제 점검 및 기존 파일 삭제하기
다음의 명령어를 실행한 후 다른 ssh 연결 세션에서 Confluence를 시작, 종료하면서 발생하는 로그를 검사한다.
# tail -100f /var/local/lib/confluence/logs/atlassian-confluence.log
위의 atlassian-confluence.log에 Error 로그가 보인다면 Confluence 설정의 ADMINISTRATION > Troubleshooting and support tools의 Log analyzer에서 문제를 해결할 수 있는지 확인한다. 해당 Error 로그를 클릭하면 해결책을 제시하는 페이지에 접속할 수 있다.
Confluence 설정의 ADMINISTRATION > Troubleshooting and support tools의 Instance heath에 문제가 있는지 확인한다. atlassian-confluence.log에 Error 로그가 나오더라도 Instance heath에서 모든 항목이 초록색으로 표시되어 있고 Log analyzer에 해당 Error 로그가 나오지 않는다면 Confluence 사용에 크게 문제를 일으키지는 않는 것으로 보인다.
MySQL에서 PostgreSQL로 마이그레이션에 성공하였다면 기존의 Confluence 관련 파일을 삭제한다.
# cd /opt/share/ # rm -rf confluence-old # rm atlassian-confluence-6.13.8.tar.gz # cd /var/local/lib/ # rm -rf confluence-old