エンタープライズ運用ガイド 2.11.0

目次

  1. ディレクトリ構成
  2. Backlogの停止・起動
  3. 使用するサービス
  4. 利用するポート番号
  5. ファイルデータの保存ディレクトリ
  6. ログの保存ディレクトリ
  7. .envのパラメーター
  8. データをバックアップする
  9. 詳細設定ファイルを作成する
  10. Active Directoryと連携する
  11. 検索インデックスを再生成する
  12. 検索インデックスの再生成の速度を変更する
  13. リクエストのパケットサイズ上限を変更する
  14. Nginxの同時接続数の最大値を変更する
  15. MySQL 5.7の利用時の注意点
  16. 課題に大きなファイルサイズのファイルを添付できない場合の対応
  17. 不要なDockerイメージを削除する
  18. データベースにSSLで接続する
  19. 商標について

ディレクトリ構成

Backlogは以下の構成でインストールされます。

<インストール先のディレクトリ>
├── backlog-job-worker
│     └── hikaricp.properties #データベース接続の最大コネクション数
├── data #Backlogの各データの保存先
├── logs #Backlogの各ログの保存先
├── .env #各設定値
├── docker-compose.yml #Backlogの各コンテナ定義
├── Licenses.txt #Backlogが利用しているオープンソースソフトウェアの情報
└── self-signed-cert #Backlogが内部で使用するSSL証明書の保存先

Backlogの停止・起動

停止

Backlogを停止します

cd <インストール先のディレクトリ>
docker-compose down

起動

Backlogを起動します

cd <インストール先のディレクトリ>
docker-compose up -d

使用するサービス

サービス名 説明
backlog-api BacklogのAPI
backlog-davsvn Backlogのファイル機能・Subversion機能
backlog-job-worker 内部のデータ処理
backlog-solr Backlogの全文検索
backlog-web BacklogのWebサービス
cron 内部のデータ処理
database-migration データベースのバージョン管理
elasticsearch Backlogの全文検索
elasticsearch-init 全文検索の初期設定
fluentd Backlogのログ収集
git-backlog-worker 内部のデータ処理
git-http BacklogのGit HTTPサービス
git-rpc 内部のデータ処理
git-ssh BacklogのGit SSHサービス
git-webhook-worker 内部のデータ処理
kanban-backend Backlogのボード機能
kanban-notification 内部のデータ処理
memcached 各種キャッシュ保存場所
nginx リバースプロキシ
redis 各種キャッシュ保存場所
update-tool アップデートツール
dewey ストレージシステム

利用するポート番号

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

利用ポート番号
HTTPS 443
Git SSH 8972

ファイルデータの保存ディレクトリ

Backlogのファイルデータは、以下のディレクトリに保存されます。

data
├── attachment
│       └── pull_request
├── davsvn
│       ├── share
│       └── svn
├── elasticsearch
├── git
├── image
└── solr
        ├── issue
        ├── pull_request
        ├── shared_file
        └── wiki
ディレクトリのパス 説明
data/attachment/pull_request Git機能のプルリクエストに添付されたファイルが保存される
data/davsvn/share ファイル機能で管理されるファイルが保存される
data/davsvn/svn Subversion機能のリポジトリが保存される
data/elasticsearch 検索のインデックス
data/git Git機能のリポジトリが保存される
data/image 画像ファイルが保存される
data/solr 検索のインデックス

ログの保存ディレクトリ

<インストール先のディレクトリ>/logsに各サービスのログが保存されます。
各サービスについては使用するサービスを確認してください。

logs
├── ${tag[1]} #ログの一時保存領域
│       └── ${tag[1]}
├── backlog-api
├── backlog-davsvn
├── backlog-davsvn-mntlog
│       ├── dav-job-worker
│       ├── httpd-davsvn
│       ├── svn-hook
│       └── svnserve
├── backlog-job-worker
├── backlog-solr
├── backlog-web
├── database-migration
├── elasticsearch
├── elasticsearch-init
├── git-http
├── git-rpc
├── git-rpc-mntlog
├── git-ssh
├── kanban-backend
├── kanban-notification
├── memcached
├── nginx
├── redis
├── update-tool
└── dewey

.envのパラメーター

パラメーター名 初期値 説明 設定ツールで入力
BACKLOG_DB_HOST 接続先データベースのホスト ✔︎
BACKLOG_DB_PORT 接続先データベースのポート ✔︎
BACKLOG_DB_NAME 接続先データベースのスキーマ名 ✔︎
BACKLOG_DB_USER 接続先データベースのユーザー名 ✔︎
BACKLOG_DB_PASSWORD 接続先データベースのパスワード ✔︎
BACKLOG_SMTP_HOST SMTPサーバーのホスト ✔︎
BACKLOG_TIMEZONE タイムゾーン ✔︎(初回のみ)
BACKLOG_MAIL_NOTIFICATIONS_ADDRESS_FORMAT Backlogから送信されるメールの送信元メールアドレス
指定しない場合は、課題の登録などを実行した人のメールアドレスになるため、なりすましやスパムと判定される場合があります。
BACKLOG_WEB_PLAY_SESSION_SECRET_KEY 設定ツールで自動生成された値 このパラメーターは変更しないでください
BACKLOG_API_PLAY_SESSION_SECRET_KEY 設定ツールで自動生成された値 このパラメーターは変更しないでください
FIXED_IP_ADDRESS_PREFIX 10.254.249 Docker Composeのネットワークに使用する固定IPのプレフィックス
LOG_REMAIN_DAYS 7 ログの保存期間
LDAPS_USING false LDAPS通信の有無
GIT_SSH_HOST_PRIVATE_KEY_ENC 設定ツールで自動生成された値 このパラメーターは変更しないでください
KANBAN_OAUTH2_CLIENT_ID 設定ツールで自動生成された値 このパラメーターは変更しないでください
BACKLOG_DATA_DIRECTORY ./data Backlogのデータディレクトリのパス
BACKLOG_LOG_DIRECTORY ./logs ログディレクトリ
BACKLOG_CERT_DIRECTORY SSL証明書と秘密鍵のディレクトリ ✔︎(初回のみ)
BACKLOG_WEB_JAVA_OPTS ‘-Xmx2048M -Xms512M -XX:MaxMetaspaceSize=512m’ backlog-webのJVM起動オプション
BACKLOG_API_JAVA_OPTS ‘-Xmx1024M -Xms512M -XX:MaxMetaspaceSize=512m’ backlog-apiのJVM起動オプション
BACKLOG_JOBWORKER_JAVA_OPTS ‘-Xmx1024M -Xms512M -XX:MaxMetaspaceSize=256m’ backlog-job-workerのJVM起動オプション
BACKLOG_KANBAN_JAVA_OPTS ‘-Xmx1024M -Xms512M -XX:MaxMetaspaceSize=256m’ kanban-backendのJVM起動オプション
BACKLOG_WEB_DB_MAXIMUM_POOL_SIZE 10 backlog-webのDB接続コネクション最大数
BACKLOG_API_DB_MAXIMUM_POOL_SIZE 10 backlog-apiのDB接続コネクション最大数
BACKLOG_DAVSVN_START_SERVERS 5 backlog-davsvnのHTTPサーバーの設定
詳しくはApache MPM 共通ディレクティブ > StartServers ディレクティブを参照してください
BACKLOG_DAVSVN_MIN_SPARE_SERVERS 5 backlog-davsvnのHTTPサーバーの設定
詳しくはApache MPM prefork > MinSpareServers ディレクティブを参照してください
BACKLOG_DAVSVN_MAX_SPARE_SERVERS 10 backlog-davsvnのHTTPサーバーの設定
詳しくはApache MPM prefork > MaxSpareServers ディレクティブを参照してください
BACKLOG_DAVSVN_MAX_REQUEST_WORKERS 256 backlog-davsvnのHTTPサーバーの設定
詳しくはApache MPM 共通ディレクティブ > MaxRequestWorkers ディレクティブを参照してください
BACKLOG_DAVSVN_MAX_CONNECTIONS_PER_CHILD 0 backlog-davsvnのHTTPサーバーの設定
詳しくはApache MPM 共通ディレクティブ > MaxConnectionsPerChild ディレクティブを参照してください
BACKLOG_REDIS_PASSWORD 設定ツールで自動生成された値 このパラメーターは変更しないでください
BACKLOG_ELASTICSEARCH_PASSWORD 設定ツールで自動生成された値 このパラメーターは変更しないでください
BACKLOG_DEWEY_PASSWORD 設定ツールで自動生成された値 このパラメーターは変更しないでください
DB_USE_SSL データベースSSL通信の有無
詳しくはデータベースにSSLで接続するを参照してください
DB_SSL_CA_PATH データベース接続用CA証明書のパス
詳しくはデータベースにSSLで接続するを参照してください
JDBC_OPTIONS JDBC接続オプション
詳しくはデータベースにSSLで接続するを参照してください

データをバックアップする

Backlogで扱うデータは以下に保存されています。これらのファイルは定期的にバックアップすることを推奨します。

詳細設定ファイルを作成する

docker-compose.ymlと同じ階層にdocker-compose.override.ymlを作成します。
docker-compose.override.ymlには、変更したいサービスとその設定値を記載します。
作成後は、起動と同じコマンドで再起動してください。

services:
  backlog-web:
    environment:
    ...

  backlog-api:
    environment:
    ...

詳しくは以下のサイトをご覧ください。
https://docs.docker.jp/compose/extends.html#understanding-multiple-compose-files

Active Directoryと連携する

LDAPSポート番号を変更する

LDAPS接続する場合は、詳細設定ファイルにLDAPSポート番号を記載します。
編集後は、起動と同じコマンドで再起動してください。

backlog-api:
  environment:
    - LDAPS_PORT=8636 #デフォルト 636

backlog-web:
  environment:
    - LDAPS_PORT=8636 #デフォルト 636

Active Directory証明書サービスを使用する

LDAPS接続を利用し、かつActive Directory証明書サービスを利用した場合は、Active Directory証明書サービスで発行した証明書を任意のディレクトリに配置し、詳細設定ファイルに以下の内容を追記します。
編集後は、起動と同じコマンドで再起動してください。

backlog-api:
  volumes:
    - /path/to/cert/dir:/mnt/certs #`/path/to/cert/dir`を証明書を配置したディレクトリに書き換えてください
  command: -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

backlog-web:
  volumes:
    - /path/to/cert/dir:/mnt/certs #`/path/to/cert/dir`を証明書を配置したディレクトリに書き換えてください
  command: -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

Active Directoryを用いてユーザーを作成する

Active Directoryの情報を利用してBacklogユーザーを作成できます。
操作する際には、あらかじめActive Directory用のゾーン定義や、SRVリソースレコードを設定しておいてください。
Windows Server 2012 R2、Windows Server 2016、Windows Server 2019でのActive Directoryに対応しています。

詳しい操作方法はヘルプページを参照してください。

検索インデックスを再生成する

キーワード検索の結果が正しく表示されない場合、検索インデクシングを再生成するコマンドを実行してください。インデクシングデータが多い場合、再生成には時間がかかります。

課題検索(課題一覧)に問題があるとき

以下を実行してください。

docker-compose up elasticsearch-tool

グローバルバーの全体からキーワード検索に問題があるとき

まず、ログの保存ディレクトリのbacklog-solrのログに以下のメッセージが出力されているか確認してください。

java.lang.OutOfMemoryError: Java heap space

メッセージが出力されている場合

Solrのメモリが少ない可能性があります。詳細設定ファイルのdocker-compose.override.ymlを開き、Solrのメモリの値を修正してください。

backlog-solr:
  environment:
    - SOLR_JAVA_MEM=-Xms1024m -Xmx1024m #デフォルト -Xms512m -Xmx512m

編集後は、起動と同じコマンドで再起動してください。
再起動後、以下を実行してください。検索インデックスが再作成されます。

docker-compose up solr-tool

メッセージが出力されていない場合

以下を実行してください。検索インデックスが再作成されます。

docker-compose up solr-tool

検索インデックスの再生成の速度を変更する

詳細設定ファイルのインデクシングジョブの制限値を変更します。
編集後は、起動と同じコマンドで再起動してください。

backlog-job-worker:
  environment:
    - BACKLOG_WORKER_JOB_INDEXING_ISSUE_JOB_PERMITS=16 #デフォルト 6

リクエストのパケットサイズ上限を変更する

Wikiの文字数が多すぎて保存ができなくなった場合などは、詳細設定ファイルのパケットサイズの制限値を変更します。
編集後は、起動と同じコマンドで再起動してください。

backlog-api:
  environment:
    - MAX_MEMORY_BUFFER=25MB #デフォルト 20MB
    - MAX_DISK_BUFFER=60MB #デフォルト 55MB

backlog-web:
  environment:
    - MAX_MEMORY_BUFFER=25MB
    - MAX_DISK_BUFFER=60MB

Nginxの同時接続数の最大値を変更する

以下のコマンドでnginx.confをローカルにコピーします。

docker-compose cp nginx:/etc/nginx/nginx.conf .

nginx.confを編集し、docker-compose.override.ymlを編集します。

nginx:
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf

nginx.confの設定について詳しくは以下のサイトをご覧ください。
nginx documentation

編集した後は、以下のコマンドでNginxを削除し、再起動してください。

docker-compose rm -fs nginx
docker-compose up -d nginx

MySQL 5.7の利用時の注意点

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

my.cnfでquery_cache_typeに0を指定してクエリキャッシュを無効にしてください。
MySQL 5.7利用時にクエリキャッシュを有効にするとBacklogが正しく動作しなくなるおそれがあります。
なお、MySQL 5.7でquery_cache_typeのデフォルト値は0のため、my.cnfで設定していない場合は追加する必要はありません。

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

[mysql]
default-character-set=utf8mb4

[client]
default-character-set=utf8mb4

課題に大きなファイルサイズのファイルを添付できない場合の対応

課題に添付できるファイルサイズの上限は50MBです。課題にファイルを添付できない場合は、以下を確認してください。

リクエストのパケットサイズ上限を上げる

詳細設定ファイルでMAX_DISK_BUFFERを55MB未満に設定している場合は、MAX_DISK_BUFFERの設定を削除するか、55MB以上に変更してください。
編集後は、起動と同じコマンドで再起動してください。

backlog-api:
  environment:
    - MAX_DISK_BUFFER=55MB #デフォルト 55MB

backlog-web:
  environment:
    - MAX_DISK_BUFFER=55MB

MySQLの設定を変更または追加する

my.cnfでmax_allowed_packetの値を128M以上に設定してください。
この設定は、MySQL 8.4、8.0、5.7のいずれでも必要です。
編集後はMySQLを再起動してください。

[mysqld]
max_allowed_packet=128M

不要なDockerイメージを削除する

不要になったDockerイメージの中から、特定のバージョンをまとめて削除する方法を説明します。
以下に、バージョン2.0.0のイメージをまとめて削除する例を示します。

docker images | grep '019623933850.dkr.ecr.ap-northeast-1.amazonaws.com' | awk '{print $1 ":2.0.0"}' | xargs docker rmi

データベースにSSLで接続する

MySQLへの接続通信をSSLで暗号化するための設定方法を説明します。使用する証明書の種類(公的CAか、プライベートCAか)によって手順が異なります。

公的認証局の証明書を利用する場合

公的認証局(DigiCert, Let’s Encryptなど)の証明書を使用する場合の設定です。

前提条件

  • MySQL 8.4を使用していること
  • MySQLサーバー側でSSL接続が有効になっていること

設定手順

手順1:.envにMySQLのSSL接続設定を追加

.env ファイルの項目を以下のように修正してください。

DB_USE_SSL=true
JDBC_OPTIONS='&useSsl=true'
手順2:詳細設定ファイルの編集

詳細設定ファイルに以下の内容を追記します。

  • .envの内容を読み込む

編集後は、起動と同じコマンドで再起動してください。

services:
  database-migration:
    environment:
      - FLYWAY_URL=jdbc:mysql://$BACKLOG_DB_HOST:$BACKLOG_DB_PORT/$BACKLOG_DB_NAME?allowPublicKeyRetrieval=true${JDBC_OPTIONS}
  backlog-api:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
  backlog-web:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
  backlog-job-worker:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
  elasticsearch-init:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
  elasticsearch-tool:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
  update-tool:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
  kanban-backend:
    environment:
      - MYSQL_JDBC_OPTIONS=${JDBC_OPTIONS}
  kanban-notification:
    environment:
      - BACKLOG_NOTIFICATIONS_DB_USE_SSL=${DB_USE_SSL}
  backlog-davsvn:
    environment:
      - BACKLOG_DB_USE_SSL=${DB_USE_SSL}
  git-ssh:
    environment:
      - DB_USE_SSL=${DB_USE_SSL}
  git-http:
    environment:
      - DB_USE_SSL=${DB_USE_SSL}
  git-rpc:
    environment:
      - BACKLOG_DB_USE_SSL=${DB_USE_SSL}
  git-backlog-worker:
    environment:
      - BACKLOG_DB_USE_SSL=${DB_USE_SSL}
  git-webhook-worker:
    environment:
      - BACKLOG_DB_USE_SSL=${DB_USE_SSL}
  backlog-solr:
    environment:
      - SOLR_OPTS=-Denable.packages=true -Ddataimporter.request.db_url=jdbc:mysql://$BACKLOG_DB_HOST:$BACKLOG_DB_PORT/$BACKLOG_DB_NAME?useUnicode=true&characterEncoding=UTF-8&useServerPrepStmts=false&allowPublicKeyRetrieval=true${JDBC_OPTIONS} -Ddataimporter.request.db_user=$BACKLOG_DB_USER -Ddataimporter.request.db_pass=$BACKLOG_DB_PASSWORD

自己署名・プライベート認証局の証明書を利用する場合

自己署名証明書や、プライベート認証局から発行された証明書を使用する場合の設定です。信頼するCA証明書をBacklogに明示的に読み込ませる必要があります。

前提条件

  • MySQL 8.4を使用していること
  • MySQLサーバー側でSSL接続が有効になっていること
  • CA証明書ファイルがBacklogサーバー上にあること
    • CA証明書を置くディレクトリにはCA証明書以外(無関係なファイルや秘密鍵など)を配置しないでください

設定手順

手順1:.envにMySQLのSSL接続設定を追加

.env ファイルの項目を以下のように修正してください。
CA証明書名は実際のファイル名に適宜修正してください。
/mnt/mysqlcerts の部分はDockerコンテナ内のパスのため編集を行わず、CA証明書名のみを編集してください。

DB_USE_SSL=true
DB_SSL_CA_PATH='/mnt/mysqlcerts/CA証明書名'
JDBC_OPTIONS='&useSsl=true&disableSslHostnameVerification=true&serverSslCert=/mnt/mysqlcerts/CA証明書名'
手順2:詳細設定ファイルの編集

詳細設定ファイルに以下2点の設定を行います。

  • .envの内容を読み込む
  • CA証明書を置いたディレクトリをコンテナ内のパスにマウントする

/path/to/cert/dir の部分は、CA証明書を配置したディレクトリパスに書き換えてください。
編集後は、起動と同じコマンドで再起動してください。

services:
  database-migration:
    environment:
      - FLYWAY_URL=jdbc:mysql://$BACKLOG_DB_HOST:$BACKLOG_DB_PORT/$BACKLOG_DB_NAME?allowPublicKeyRetrieval=true${JDBC_OPTIONS}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  backlog-api:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  backlog-web:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  backlog-job-worker:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  elasticsearch-init:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  elasticsearch-tool:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  update-tool:
    environment:
      - JDBC_OPTIONS=${JDBC_OPTIONS}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  kanban-backend:
    environment:
      - MYSQL_JDBC_OPTIONS=${JDBC_OPTIONS}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  kanban-notification:
    environment:
      - BACKLOG_NOTIFICATIONS_DB_USE_SSL=${DB_USE_SSL}
      - BACKLOG_NOTIFICATIONS_DB_SSL_CA_PATH=${DB_SSL_CA_PATH}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  backlog-davsvn:
    environment:
      - BACKLOG_DB_USE_SSL=${DB_USE_SSL}
      - BACKLOG_DB_SSL_CA_FILE=${DB_SSL_CA_PATH}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  git-ssh:
    environment:
      - DB_USE_SSL=${DB_USE_SSL}
      - DB_CA_PATH=${DB_SSL_CA_PATH}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  git-http:
    environment:
      - DB_USE_SSL=${DB_USE_SSL}
      - DB_CA_PATH=${DB_SSL_CA_PATH}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  git-rpc:
    environment:
      - BACKLOG_DB_USE_SSL=${DB_USE_SSL}
      - BACKLOG_DB_SSL_CA_FILE=${DB_SSL_CA_PATH}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  git-backlog-worker:
    environment:
      - BACKLOG_DB_USE_SSL=${DB_USE_SSL}
      - BACKLOG_DB_SSL_CA_FILE=${DB_SSL_CA_PATH}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  git-webhook-worker:
    environment:
      - BACKLOG_DB_USE_SSL=${DB_USE_SSL}
      - BACKLOG_DB_SSL_CA_FILE=${DB_SSL_CA_PATH}
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts
  backlog-solr:
    environment:
      - SOLR_OPTS=-Denable.packages=true -Ddataimporter.request.db_url=jdbc:mysql://$BACKLOG_DB_HOST:$BACKLOG_DB_PORT/$BACKLOG_DB_NAME?useUnicode=true&characterEncoding=UTF-8&useServerPrepStmts=false&allowPublicKeyRetrieval=true${JDBC_OPTIONS} -Ddataimporter.request.db_user=$BACKLOG_DB_USER -Ddataimporter.request.db_pass=$BACKLOG_DB_PASSWORD
    volumes:
      - /path/to/cert/dir:/mnt/mysqlcerts

商標について

  • MySQLとJavaは、Oracle Corporation及びその子会社、関連会社の米国及びその他の国における登録商標です。文中の社名、商品名等は各社の商標または登録商標である場合があります。
  • Dockerは、米国及びその他の国におけるDocker, Inc. の商標または登録商標です。
  • Nginxは、米国及びその他の国におけるNginx Software Inc. 及びその子会社、関連会社の登録商標です。
  • Active DirectoryとWindows Serverは、米国Microsoft Corporationの米国およびその他の国における登録商標または商標です。
  • その他記載されている会社名および商品名は各社の登録商標または商標です。