Backlogエンタープライズ 2.5.1
アップグレードガイド

はじめに

このガイドではBacklogエンタープライズ Ver.1（以下 Ver.1）をBacklogエンタープライズ Ver.2（以下 Ver.2）にアップグレードする方法をご案内します。

目次

  1. 前提条件
  2. 作業手順
  3. Ver.1をアンインストール
  4. アップグレードツールを削除
  5. 商標について

前提条件

Ver.1を最新版にアップデートしていること

アップグレードを開始する前に、Ver.1を最新版にアップデートしてください。

Ver.2のシステム要件を満たしていること

Ver.2はAWS CLI、Docker、およびDocker Composeが必要です。サーバーがVer.2のシステム要件を満たす必要があります。
現在の環境で、Ver.2のシステム要件を満たせない場合、別のサーバーを用意してください。

Ver.2のシステム要件

サーバー
ハードウェア
仕様
メモリ 16GB
ハードディスク 30GB
Backlogに保存したいデータ量やファイル、リポジトリサイズ等に応じて増量してください。
CPU 2.4GHz, 4core
OS

Dockerが対応しているOS
(https://docs.docker.com/engine/install/)

ソフトウェア
AWS CLI (Command Line Interface)

バージョン2.x

Docker

バージョン20.10.0以上

Docker Compose

バージョンv2.18.1以上

ミドルウェア
データベース

MySQL 5.7
MySQL 8.0

SMTPサーバー

SMTP認証なしでメールを送信できるSMTPサーバー

作業手順

事前準備

Backlogをアップグレードするために必要なものを用意します。
ここではLinux環境での作業を例として記述します。

SSL証明書を用意

Backlogでは通信にHTTPSを使用します。Ver.1ですでにSSL通信を使用していた場合、この手順は不要です。
あらかじめ、サーバーに配置する

  • SSL証明書
  • 秘密鍵ファイル

をご用意ください。

AWS CLIをインストール

AWS CLIのインストーラーをダウンロード、インストールします。

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

AWS CLIのインストールに関する詳細は以下のAWS公式ガイドをご覧ください。
https://docs.aws.amazon.com/ja_jp/cli/latest/userguide/cli-chap-getting-started.html

Dockerをインストール

yumリポジトリを追加して、Dockerをインストールします。

sudo yum install -y yum-utils
sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Dockerを自動起動するよう設定します。

sudo systemctl enable docker

Dockerを起動します。

sudo systemctl start docker

Docker Composeをインストールします。

sudo curl -L https://github.com/docker/compose/releases/download/v2.18.1/docker-compose-linux-x86_64 \
    -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Dockerのインストールに関する詳細は、詳しくは以下のサイトもご覧ください。

データベース（MySQL）を用意

Backlogのデータを保存するデータベース（MySQL）を使用します。Ver.1で使用しているデータベースをそのまま使える場合、この手順は不要です。
Amazon RDSなどのIaaSを利用したり、Backlogのインストール先と同じサーバーなど、任意のサーバーにインストールしたものを利用できます。
my.cnfには以下の設定を追加してください。

MySQL 8.0の場合
[mysqld]
sql_mode="NO_ENGINE_SUBSTITUTION"
default_authentication_plugin=mysql_native_password
max_allowed_packet=128M
MySQL 5.7の場合
[mysqld]
max_allowed_packet=128M
character-set-server=utf8mb4
sql_mode = "NO_ENGINE_SUBSTITUTION"

[mysql]
default-character-set=utf8mb4

[client]
default-character-set=utf8mb4

SMTPサーバーを用意

Backlogからメールを送信するためのSMTPサーバーを利用します。Ver.1で使用しているSMTPサーバーをそのまま使える場合、この手順は不要です。
SMTP認証なしでメールを送信できるSendmail、Postfixなど、Red Hat Enterprise LinuxやCentOSに標準でインストールされるSMTPサーバーが利用できます。

稼働環境の設定

データベースを作成

データベースサーバーにBacklog用のデータベースとデータベースユーザーを作成してください。Ver.1で使用しているデータベースをそのまま使える場合、この手順は不要です。

推奨値
データベース名 backlog
データベースユーザー名 backlog

データベース名、ユーザー名は任意の値を設定できます。

SSL証明書を配置

SSL証明書と秘密鍵をサーバー上の任意のディレクトリに配置します。

mkdir <任意のディレクトリ>
cp <SSL証明書> <任意のディレクトリ>/crt.pem
cp <秘密鍵> <任意のディレクトリ>/key.pem

Ver.1のデータをVer.2のサーバーにコピー

Ver.1と同じサーバーでVer.2へアップグレードする場合、本手順は不要です。Backlogをアップグレードに進んでください。

以下の手順でデータをコピーします。
Ver.1環境での作業

  1. Backlogを停止
  2. データをバックアップ

Ver.2環境での作業

  1. バックアップデータを展開

Ver.1環境での作業

Backlogを停止

以下でVer.1を停止します。root権限で実行してください。

systemctl stop backlog.target
データをバックアップ

以下でデータ領域をアーカイブファイルに圧縮します。root権限で実行してください。
下記ではアーカイブしたファイル名をdata.tar.gzとします。

cd /opt/backlog/
tar cvfp data.tar.gz data

Ver.1のサーバーでMySQLを動かしている場合、MySQLのデータをダンプします。
下記ではダンプのファイル名をbacklog-dump.sql、データベース名をbacklog、データベースユーザー名をbacklogとします。 

mysqldump -ubacklog -p --opt backlog > backlog-dump.sql

Ver.2環境での作業

Ver.1環境での作業で作成した圧縮ファイル、ダンプファイルをscpコマンド等でVer.2をインストールするサーバーへ転送してください。

バックアップデータを展開

以下でデータ領域を展開します。root権限で実行してください。

mkdir -p /opt/backlog
tar xvfp data.tar.gz -C /opt/backlog

MySQLのダンプファイルを作成した場合は、リストアします。
下記ではダンプのファイル名をbacklog-dump.sql、リストア先のデータベース名をbacklog、リストア先のデータベースユーザー名をbacklog
とします。

mysql -ubacklog -p backlog < backlog-dump.sql

以上でVer.1のデータをVer.2にコピーする作業は完了です。

Backlogをアップグレード

次の手順でVer.2へアップグレードします。

  1. Ver.1を停止
  2. バックアップ
  3. アップグレードツールをダウンロード
  4. 検証ツールを起動
  5. アップグレードツールを起動

Ver.1を停止

以下でVer.1を停止します。root権限で実行してください。

systemctl stop backlog.target

バックアップ

アップグレードする前に必ずデータベースをバックアップしてください。

アップグレードツールをダウンロード

アップグレードツールを以下の手順にてダウンロードします。
エンタープライズ契約管理サイトに記載されたAWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEYを環境変数に設定してください。 

export AWS_ACCESS_KEY_ID="XXXX"
export AWS_SECRET_ACCESS_KEY="XXXX"

Dockerにログインします。

aws ecr get-login-password --region ap-northeast-1 | \
    docker login --username AWS --password-stdin 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com

次に、アップグレード先のディレクトリでアップグレードツールを起動します。
下記ではアップグレード先のディレクトリをbacklog-enterpriseとします。

アップグレード先のディレクトリとして/opt/backlogおよびそれ以下のディレクトリパスを指定しないでください。

mkdir backlog-enterprise
cd backlog-enterprise
docker run --rm -it -v $PWD:/work \
    019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-bootstrap:2.5.1 upgrade

Ver.1環境を検証

アップグレードの前に検証ツールを起動します。

cd upgrade-assistant
環境変数を用意

upgrade.envをroot権限で編集してください。

パラメーター名 初期値 説明
BACKLOG_DB_HOST 127.0.0.1 接続先データベースのホスト
BACKLOG_DB_PORT 3306 接続先データベースのポート
BACKLOG_DB_NAME backlog 接続先データベースのスキーマ名
BACKLOG_DB_USER backlog 接続先データベースのユーザー名
BACKLOG_DB_PASSWORD 接続先データベースのパスワード
ENTERPRISE_V1_DATA_DIR /opt/backlog/data このパラメーターは変更しないでください
ENTERPRISE_V2_DIR アップグレード先のディレクトリを絶対パスで指定してください
/path/to/backlog-enterprise
検証ツールを起動
./advance-check.sh

赤文字のメッセージが表示された場合、データ構造の変更により、アプリ側にデータがすべて表示できていない可能性があります。
内容を確認する必要があれば、データベースを直接ご確認ください。
例えば以下のようなメッセージが表示されます。

10 database records will be truncated when the upgrade tool is run due to changes in the database table structure. Please see the red messages above for further details.

アップグレードツールを起動

Backlogをアップグレードします。アップグレードには数分かかる場合があります。

docker pull 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-database-migration:2.5.1
docker pull 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-password-migration-tool:2.5.1
docker pull 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-git-rpc:2.5.1
sudo ./upgrade.sh

以上でBacklogのアップグレードは完了です。

環境設定ツールを起動

Ver.2の起動に必要な環境を設定するツールを起動します。
アップグレード先のディレクトリで実行してください。
backlog-enterpriseとします。 

cd /path/to/backlog-enterprise #`/path/to/backlog-enterprise`をアップグレード先のディレクトリの絶対パスに書き換えてください
docker run --rm -it -v $PWD:/work -v $PWD/data:/data -e LANG="ja_JP.UTF-8" \
    019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-bootstrap:2.5.1

対話形式で8つの項目を設定します。Backlogが稼働する環境に応じて設定してください。
特に以下のことに注意してください。

データベースサーバーのホスト名を入力してください。
[例] backlog-db.example.com, 192.168.0.11
> 10.254.249.1

upgrade.envのBACKLOG_DB_HOSTの値をlocalhostまたは127.0.0.1に設定していると、ここでは10.254.249.1が初期値として表示されます。
Backlogがデータベースにアクセスする際に内部的に使用するホスト名のため変更しないでください。

Backlogエンタープライズのデータベース名を入力してください。
デフォルト値: backlog
> backlog

データベース接続ユーザーのユーザー名を入力してください。
デフォルト値: backlog
> backlog

データベース接続ユーザーのパスワードを入力してください。
>

データベースを作成したデータベースの情報を入力してください。

メール送信に使うSMTPサーバーのホスト名を入力してください。環境変数も使えます。
[例] backlog-smtp.example.com, 192.168.0.12
>

SMTPサーバーを用意で用意したサーバーの情報を入力してください。
Backlogをインストールしたサーバーと同じ環境のSMTPサーバーを使用する場合は、10.254.249.1を設定してください。

タイムゾーン名を入力してください。
[例] Asia/Tokyo, America/New_York, Europe/London
>

タイムゾーン名はデータベースサーバーやSMTPサーバーなど、他のミドルウェアのタイムゾーンと揃えてください。

SSL証明書を格納しているディレクトリを入力してください。
>

SSL証明書を配置したディレクトリを”絶対パス”で入力してください。
以上でVer.2の起動に必要な環境の設定は完了です。

Ver.2を起動

以下でVer.2を起動します。

docker-compose up -d

グローバルバーの全体からキーワード検索機能を有効にするため、以下を実行します。

docker-compose up solr-tool

Ver.1をアンインストール

Ver.2へのアップグレードが完了したら、Ver.1をアンインストールできます。
次の手順でBacklogをdisableにします。root権限が必要です。

systemctl disable backlog.target

次の手順でRPMパッケージをアンインストールします。root権限が必要です。

rpm -aq | grep backlog | xargs rpm -e

次の手順でVer.1のデータ領域を削除します。root権限が必要です。

rm -rf /opt/backlog

アップグレードツールを削除

Ver.2へのアップグレードが完了したら、アップグレードツールを削除できます。root権限が必要です。

cd /path/to/backlog-enterprise #`/path/to/backlog-enterprise`をアップグレード先のディレクトリの絶対パスに書き換えてください
rm -rf upgrade-assistant

商標について

  • MySQLとJavaは、Oracle Corporation及びその子会社、関連会社の米国及びその他の国における登録商標です。文中の社名、商品名等は各社の商標または登録商標である場合があります。
  • Dockerは、米国及びその他の国におけるDocker, Inc.の商標または登録商標です。
  • Amazon Web Services、アマゾンウェブサービス、AWS、AWS CLI、AWSコマンドラインインターフェースは、米国その他の諸国における、Amazon.com, Inc. またはその関連会社の商標です。
  • Linuxは、米国およびその他の国におけるLinus Torvaldsの登録商標です。
  • その他記載されている会社名および商品名は各社の登録商標または商標です。