Backlog プロフェッショナル 運用ガイド

1 システム要件

本ドキュメントは Backlog プロフェッショナル 最新版がインストールされており、 その環境はBacklog プロフェッショナル インストールガイド システム要件 を満たしている事を前提とします。

2 HTTPS での運用

HTTPS で Backlog を運用するためには、事前にSSLのサーバ証明書を準備頂く必要があります。 証明書の発行については、ご利用する証明書発行機関の手順にしたがってください。 以下では、HTTPS のポートは 443 で設定する事を前提とします。

2.1 HTTPS を有効化する

以下の手順でHTTPSを有効化します。

2.1.1 Backlog を停止します

次のコマンドを実行し停止します。

# systemctl stop backlog.target

2.1.2 Backlog が使用する環境変数を編集します

以下のファイルを開いてください。

• /opt/backlog/scripts/env

以下の2つの項目のポート番号をHTTP の番号から HTTPS の番号へ編集します。

例）
変更前）BACKLOG_DOMAIN="xxxx:8080" ※ 80ポートの場合は:80を省略できます
変更後）BACKLOG_DOMAIN="xxxx:8443" ※ 443ポートの場合は:443を省略できます

例）
変更前）BACKLOG_API_GIT_HTTPURLPATTERN="http://xxxx:8080/backlog/git/%s/%s.git" ※ 80ポートの場合は:80を省略できます
変更後）BACKLOG_API_GIT_HTTPURLPATTERN="https://xxxx:8443/backlog/git/%s/%s.git" ※ 443ポートの場合は:443を省略できます

以下の項目を "http" から "https" へ編集します。

例）
変更前）BACKLOG_SCHEME="http"
変更後）BACKLOG_SCHEME="https"

2.1.3 ssl.conf を編集します

/opt/backlog/httpd/conf/ssl.conf の下記部分を環境にあう設定に編集します。

### PLEASE CHANGE ###
ServerName www.example.com:443
#####################

### PLEASE CHANGE ###
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
#####################

2.1.4 httpd.conf を編集します

以下のコマンドにて、ssl.conf を読み込む設定を追加してください。

# cp -a /opt/backlog/httpd/conf/httpd.conf /opt/backlog/httpd/conf/httpd.conf.bak
# echo 'Include conf/ssl.conf' >> /opt/backlog/httpd/conf/httpd.conf

2.1.5 Backlogを起動します

次のコマンドを実行し起動します。

# systemctl start backlog.target

2.1.6 スペースURLを変更します

Backlogに管理者にてログイン後、「管理画面」→「スペースの編集」より、スペースのURLをHTTPSのものに変更してください。

2.2 HTTPSにリダイレクトする

HTTPSでの利用に限定したい場合、HTTP へのアクセスを HTTPS にリダイレクトする設定を行います。 /opt/backlog/httpd/conf/httpd.conf に以下の設定を追加してください。

RewriteCond %{SERVER_PORT} !^443$
RewriteCond %{REMOTE_ADDR} !^127\.0\.0\.1$
RewriteCond %{HTTP_USER_AGENT} !^Backlog\ HttpClient
RewriteRule ^/(.*)$ https://%{HTTP_HOST}/$1 [R,L]

尚、Backlog は内部の API 呼び出しで HTTP でのアクセスを利用するため、Apache の設定で HTTP の利用そのものを停止することは出来ません。もしサーバー外部からの HTTP アクセスを制限したい場合はファイアウォール等の設定で行うようにしてください。

3 ディレクトリ構成

Backlog プロフェッショナルは次のディレクトリ構成でインストールが行われます。

/opt/backlog
|– api-server
|– bin
|– data
| |– image
| |– git
| |– lucene
| | `– index
| |– share
| | `– dav
| |– solr
| | |– issue
| | |– pull_request
| | |– shared_file
| | `– wiki
| `– svn
|– git-server
|– httpd
|– licenses
|– licenses-api
|– licenses-git
|– perl
|– perl-git
|– python
|– scripts
|– serf
|– subversion
`– tomcat

4 ログの管理

ログの管理には Apache に付属する rotatelogs や OS に付属する logrotate を利用します。 これらの詳細についてはご利用環境で提供されているドキュメントを参照してください。

4.1 ログファイルの保存ディレクトリ

Backlog を構成する各種のミドルウェアは以下のディレクトリに保存されています。

4.2 Apache のログをローテートする

/opt/backlog/httpd/conf/httpd.conf に rotatelogs を利用した設定例をコメントアウトした状態で記載しています。 以下のように有効化してください。

# 以下をコメントアウト
#ErrorLog logs/error_log
# 以下を有効に
ErrorLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/error_log.%Y-%m-%d 86400"

#LogLevel debug
LogLevel warn

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %p %m %D" combined
LogFormat "%h %l %{note-x-backlog-user}n %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %p %m %D" backlog_user_combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common

# 以下をコメントアウト
#CustomLog logs/access_log combined env=!log-x-backlog-user
#CustomLog logs/access_log backlog_user_combined env=log-x-backlog-user
# 以下を有効に
CustomLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/access_log.%Y-%m-%d 86400" combined env=!log-x-backlog-user
CustomLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/access_log.%Y-%m-%d 86400" backlog_user_combined env=log-x-backlog-user

4.3 Tomcat のログをローテートする

/opt/backlog/tomcat/bin/catalina.sh に rotatelogs を利用した設定例をコメントアウトした状態で記載しています。 以下のように有効化してください。修正箇所は２箇所あります。

      >> "$CATALINA_OUT" 2>&1 "&"
      #2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l "$CATALINA_BASE"/logs/catalina.out.%Y-%m-%d 86400 &

     2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l "$CATALINA_BASE"/logs/catalina.out.%Y-%m-%d 86400 &
     #>> "$CATALINA_OUT" 2>&1 "&"

4.4 Git サーバーのログをローテートする

logrotate を利用してローテートを行います。/etc/logrotate.d/backlog-git に以下のファイルを追加します。

/opt/backlog/git-server/logs/httpd.log
/opt/backlog/git-server/logs/rpc.log
/opt/backlog/git-server/logs/hook-worker-backlog.log
/opt/backlog/git-server/logs/hook-worker-webhook.log
/opt/backlog/git-server/logs/hook-worker-diskusage.log
/opt/backlog/git-server/logs/sshd.log
{
  sharedscripts
  postrotate
    systemctl restart backlog-git.target
  endscript
}

4.5 API v2 のログをローテートする

/opt/backlog/scripts/backlog-api.sh に rotatelogs を利用した設定例をコメントアウトした状態で記載しています。 以下のように有効化してください。

    >> ${LOGS_DIR}/play.log 2>&1 &
    #2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l ${LOGS_DIR}/play.log.%Y-%m-%d 86400 &

    2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l ${LOGS_DIR}/play.log.%Y-%m-%d 86400 &
    #>> ${LOGS_DIR}/play.log 2>&1 &

5 バックアップ

5.1 バックアップ

以下の二点についてバックアップを定期的に取得することをおすすめします。

• データベースのダンプ
• /opt/backlog/data 以下のデータ領域ディレクトリ

データベースのタンプについて、mysqldumpなどが利用可能です。

5.2 データ領域

Backlog の利用するデータは、データベースデータに加え、以下のディレクトリに各々保存されています。

6 不要なサービスの停止

6.1 Git サービス

Git に関連する機能を利用しない場合は、backlog-git サービスを停止することができます。

# systemctl stop backlog-git.target
# systemctl disable backlog-git.target \
    backlog-git-rpc.service \
    backlog-git-httpd.service \
    backlog-git-sshd.service \
    backlog-git-hook-diskusage-worker.service \
    backlog-git-hook-webhook-worker.service \
    backlog-git-hook-backlog-worker.service

6.2 API v2 サービス

API v2 を利用しない場合、backlog-api サービスを停止することができます。
API v2 の詳細については、Nulab Developers を参照ください。

# systemctl stop backlog-api.target
# systemctl disable backlog-api.target backlog-api.service

7 インストール後の再設定

7.1 設定ツールの起動

インストール後に、次の設定値を再設定することができます。

• SMTPサーバー
• データベースの再設定

Backlogパッケージ(backlog-app)に同封している設定ツールを使用して、Backlogアプリケーションの再設定を行います。

次のコマンドを実行して、設定ツールを起動してください。

# /opt/backlog/bin/config.sh

7.2 通知メールの送信元メールアドレスの変更

Backlogから送信されるメールの送信元メールアドレスには、 課題の登録などを
実行した人のメールアドレスを使用しています。そのため、送信元メールアドレスと
実際に送信したドメインが異なる場合があり、メール受信サーバーによっては、なりすましやスパムと判定される場合があります。

送信元メールアドレスを変更することで、これを防止できます。

7.2.1 Backlog を停止します

次のコマンドを実行し停止します。

# systemctl stop backlog.target

7.2.2 Backlog が使用する環境変数に、送信元メールアドレスを指定します

以下のファイルを開いてください。

• /opt/backlog/scripts/env

以下の項目に送信元メールアドレスを指定してください。

例）
BACKLOG_MAIL_NOTIFICATIONS_ADDRESS_FORMAT="notifications@backlog.jp"

7.2.3 Backlogを起動します

次のコマンドを実行し起動します。

# systemctl start backlog.target

7.2.4 オプション設定

次のように送信元メールアドレスに送信者IDを含めて、送信者ごとに一意にすることもできます。
[notifications@backlog.jp] -> [notifications-21@backlog.jp]
送信元メールアドレスが固定の場合、Gmailでは同一送信先からのメールと判定され、送信者名が一人だけしか表示されなくなります。
送信者名をスレッド上に表示させるには、以下の手順で送信者アドレスを設定し直してください。

送信者IDを埋め込みたい箇所に %d を指定してください。

例）
BACKLOG_MAIL_NOTIFICATIONS_ADDRESS_FORMAT="notifications-%d@backlog.jp"

実際の送信元メールアドレスの例）
notifications-21@backlog.jp

修正した後は、Backlog のサービスを再起動させてください。上記の手順7.2.1 と 7.2.3にあたります。 これで、アクションを行ったユーザー一人一人の名前が Gmail の受信トレイ上に表示されます。

7.3 LDAP 署名に対応した Active Directory 連携

Backlog で Active Directory と連携しており LDAP 署名に対応したい場合は、次の設定を行ってください。
Backlog と Active Directory との通信にプロトコルとして LDAPS (LDAP over SSL/TLS) を使用するためには、事前に Active Directory にサーバー証明書をインストールする必要があります。

7.3.1 サーバー証明書を Active Directory にインストールします

下記のいずれかの方法でサーバー証明書を発行し Active Directory にインストールしてください。

• Active Directory 証明書サービスの場合

  下記のページを参考に設定してください。
  Step by Step Guide to Setup LDAPS on Windows Server
  インストールした証明書をエクスポートし、 Backlog サーバー上で keytool コマンドを使用して JRE キーストアにインポートしてください。

• サードパーティ CA の場合

  下記のページを参考に設定してください（証明書の設定に関するお問い合わせはご利用の認証局へご連絡ください）。
  Enable LDAP over SSL with a third-party certification authority

7.3.2 Backlog を停止します

次のコマンドを実行し停止します。

# systemctl stop backlog.target

7.3.3 Backlog が使用する環境変数を編集します

以下のファイルを開いてください。

• /opt/backlog/scripts/env

以下の項目 BACKLOG_LDAPS_USING を true にし、LDAPS プロトコルでの通信を有効にします。BACKLOG_LDAPS_USING を false に設定すると LDAPS を使用せずに LDAP プロトコルで通信します。

変更前）BACKLOG_LDAPS_USING="false" ※ false の場合は LDAP プロトコルで通信します
変更後）BACKLOG_LDAPS_USING="true" ※ true の場合は LDAPS プロトコルで通信します

以下の項目 BACKLOG_LDPAS_PORT で LDAPS のポート番号を指定してください。
この設定項目は BACKLOG_LDAPS_USING が false の場合は使用されません。

例）
BACKLOG_LDAPS_PORT="636"

Active Directory 証明書サービスを使用している場合、Active Directory と連携しているユーザーが Subversion、Git、共有ファイルにアクセスした際に、サーバーの証明書を確認しようとしてエラーが発生する場合があります。以下の項目 BACKLOG_LDPAS_VERIFY を "require" から "none" へ編集し、証明書の確認を無視させることができます。
この設定項目は BACKLOG_LDAPS_USING が false の場合は使用されません。

変更前）BACKLOG_LDAPS_VERIFY="require"
変更後）BACKLOG_LDAPS_VERIFY="none"

Active Directory 証明書サービスを使用している場合、Active Directory へユーザーを検索する際にエラーが発生する場合があります。以下のオプションを BACKLOG_CATALINA_OPTS に追記し、エラーを回避させてください。
このオプションは BACKLOG_LDAPS_USING が false の場合は使用されません。

BACKLOG_CATALINA_OPTS="...　-Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true"

7.3.4 Backlogを起動します

次のコマンドを実行し起動します。

# systemctl start backlog.target

8 利用するポート番号

以下のポート番号を利用してサービスを公開しますので、iptables 等を利用されている場合は、下記のポート番号への外部からのアクセスを許可してください。

上記以外で以下のポート番号をBacklog内部的に利用します。
5701, 8905, 8970, 8971, 8973, 8974, 8975

9 自動対話式モード

インストール、アップデート、アップグレードは基本対話式で実行されますが、自動対話式で実行することも可能です。

9.1 インストール時

9.1.1 自動対話式用の設定ファイルのテンプレートをコピーします

自動対話式用の設定ファイルのテンプレートをコピーしてください。コピー先のファイル名は任意で構いません。
以下の例では、コピー先のファイル名を pro-init-interactive.properties として説明します。

cp /opt/backlog/bin/pro-init-interactive.properties.template pro-init-interactive.properties

9.1.2 設定値を修正します

コピーしたファイルを開いて、設定値を適宜修正してください。
設定が必須の項目には説明欄に
# 【必須】
と記載されています。それ以外は、未設定でも構いませんがデフォルト値が使われます。
詳細はファイルに記載されている説明欄をご確認ください。
行の先頭の「#」はコメント行を表します。設定を有効にするには先頭の「#」を削除してください。
また、行の途中で「#」と記述してもコメントとして扱われません。設定を無効にしたい場合は行の先頭に「#」と記述してください。

9.1.3 保存したファイルを -i で指定して、インストーラーを実行します

インストールガイドの 4.6 環境設定ツールの起動 で、-i を指定してください。

/opt/backlog/bin/init.sh -i pro-init-interactive.properties

9.2 アップデート時

9.2.1 自動対話式用の設定ファイルのテンプレートをコピーします

自動対話式用の設定ファイルのテンプレートをコピーしてください。コピー先のファイル名は任意で構いません。
以下の例では、コピー先のファイル名を pro-update-interactive.properties として説明します。

cp /opt/backlog/bin/pro-update-interactive.properties.template pro-update-interactive.properties

9.2.2 設定値を修正します

9.1.2 インストールと同様にコピーしたファイルを開いて、設定値を適宜修正してください。

9.2.3 保存したファイルを -i で指定して、アップデーターを実行します

アップデートガイドの 4.5 アップデーターの起動 で、-i を指定してください。

/opt/backlog/bin/update.sh -i pro-update-interactive.properties

9.3 アップグレード時

9.3.1 自動対話式用の設定ファイルのテンプレートをコピーします

自動対話式用の設定ファイルのテンプレートをコピーしてください。コピー先のファイル名は任意で構いません。
以下の例では、コピー先のファイル名を pro-upgrade-interactive.properties として説明します。

cp /opt/backlog/bin/pro-upgrade-interactive.properties.template pro-upgrade-interactive.properties

9.3.2 設定値を修正します

9.1.2 インストールと同様にコピーしたファイルを開いて、設定値を適宜修正してください。

9.3.3 保存したファイルを -i で指定して、アップグレーダーを実行します

アップグレードガイドの 4.4 アップグレードツールの起動 で、-i を指定してください。

/opt/backlog/bin/upgrade.sh -i pro-upgrade-interactive.properties

10 MySQL 5.7の利用時の注意点

10.1 クエリキャッシュを無効にする

my.cnfでquery_cache_typeに0を指定してクエリキャッシュを無効にしてください。

BacklogがMySQL 8.0に対応したことにより、MySQLのクエリキャッシュを有効にするとBacklogが正しく動作しなくなるおそれがあります。

なお、MySQL 5.7でquery_cache_typeのデフォルト値は0のため、my.cnfで設定していない場合は追加する必要はありません。

[mysqld]
max_allowed_packet = 16M
character-set-server=utf8mb4
sql_mode = "NO_ENGINE_SUBSTITUTION"
query_cache_type = 0

[mysql]
default-character-set=utf8mb4

[client]
default-character-set=utf8mb4