GitLab Mattermost

GitLabサーバー上でGitLab Mattermostサービスを実行できます。Mattermostは、GitLabが提供する単一アプリケーションの一部ではありません。MattermostとGitLabの間には優れたインテグレーションがあり、弊社のLinuxパッケージでインストールできます。ただし、Mattermostは別会社が提供する別のアプリケーションです。。GitLabサポートは、GitLabとのインテグレーション以外のMattermost固有の質問には対応できません。Mattermost自体に関するヘルプが必要な場合は、コミュニティサポートリソースを参照してください。

前提条件

GitLab Mattermostの各リリースは、Linux用のAMD 64チップセットでコンパイルされ、手動でテストされています。ARMチップセットおよびRaspberry Piのようなオペレーティングシステムはサポートされていません。

はじめに

GitLab Mattermostは独自の仮想ホストで実行されることを想定しています。あなたのDNSの設定で、同じマシンを指す2つのエントリーが必要です。例えば、gitlab.example.comとmattermost.example.com。

GitLab Mattermostはデフォルトで無効になっています。有効にするには、次の手順に従います。

1. /etc/gitlab/gitlab.rbを編集し、Mattermostの外部URLを追加します:

   mattermost_external_url 'https://mattermost.example.com'

2. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

3. GitLab Mattermostがhttps://mattermost.example.comで到達可能であり、GitLabへの接続が認可されていることを確認します。MattermostをGitLabで認可すると、ユーザーはGitLabをSSOプロバイダーとして使用できます。

アプリケーションが同じサーバーで実行されている場合、LinuxパッケージはGitLab MattermostをGitLabで自動的に認可しようとします。

自動認可には、GitLabデータベースへのアクセスが必要です。GitLabデータベースが利用できない場合、MattermostをGitLabで認可するセクションに記載されているプロセスを使用して、GitLab Mattermostへのアクセスを手動で認可する必要があります。

Mattermostの設定

MattermostはMattermostシステムコンソールを使用して設定できます。Mattermostの設定の広範なリストと、それらをどこで設定できるかについては、Mattermostのドキュメントで入手できます。

システムコンソールの使用が推奨されますが、以下のいずれかのオプションを使用してMattermostを設定することもできます:

1. Mattermostの設定を/var/opt/gitlab/mattermost/config.jsonを通して直接編集します。
2. Mattermostを実行するために使用される環境変数を、gitlab.rb内のmattermost['env']設定を変更して指定します。このように設定された設定は、システムコンソールから無効になり、Mattermostを再起動せずに変更することはできません。

HTTPSでGitLab Mattermostを実行する

SSL証明書とSSL証明書キーを/etc/gitlab/ssl内に配置します。そのディレクトリが存在しない場合は、作成してください:

sudo mkdir -p /etc/gitlab/ssl
sudo chmod 755 /etc/gitlab/ssl
sudo cp mattermost.gitlab.example.key mattermost.gitlab.example.crt /etc/gitlab/ssl/

/etc/gitlab/gitlab.rbで、次のように設定します。

mattermost_external_url 'https://mattermost.gitlab.example'
mattermost_nginx['redirect_http_to_https'] = true

証明書とキーにmattermost.gitlab.example.crtとmattermost.gitlab.example.keyという名前を付けていない場合は、以下の完全なパスも追加する必要があります:

mattermost_nginx['ssl_certificate'] = "/etc/gitlab/ssl/mattermost-nginx.crt"
mattermost_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/mattermost-nginx.key"

ここでmattermost-nginx.crtはSSL証明書、mattermost-nginx.keyはSSLキーです。

設定が完了したら、sudo gitlab-ctl reconfigureを実行して変更を適用します。

外部PostgreSQLサービスでGitLab Mattermostを実行する

デフォルトでは、MattermostはLinuxパッケージにバンドルされているPostgreSQLサービスを使用します。外部PostgreSQLサービスでMattermostを使用する場合は、独自の特定の設定が必要です。既存のGitLabが使用する外部PostgreSQL接続設定は、Mattermostに自動的に継承されません。

1. /etc/gitlab/gitlab.rbを編集し、以下の設定を指定します:

   mattermost['sql_driver_name'] = 'postgres'
   mattermost['sql_data_source'] = "user=gitlab_mattermost host=<hostname-of-postgresql-service> port=5432 sslmode=required dbname=<mattermost_production> password=<user-password>"

2. userの値と、mattermost['sql_data_source']で定義したpasswordの値に一致するPostgreSQLユーザーを作成します。

3. 使用されたdbnameの値に一致するPostgreSQLデータベースを作成します。

4. userが、dbnameで作成されたデータベースに対する権限を持っていることを確認します。

5. GitLabを再設定し、Mattermostを再起動して変更を適用します:

   sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart mattermost

独自のサーバーでGitLab Mattermostを実行する

GitLabとGitLab Mattermostを2つの異なるサーバーで実行している場合でも、GitLabサービスはGitLab Mattermostサーバー上にセットアップされます。ただし、GitLabサービスはユーザーリクエストを受け入れたり、システムリソースを消費したりすることはありません。GitLab Mattermostサーバーで以下の設定と設定の詳細を使用することで、LinuxパッケージにバンドルされているGitLabサービスを効果的に無効にできます。

mattermost_external_url 'http://mattermost.example.com'

# Shut down GitLab services on the Mattermost server
alertmanager['enable'] = false
gitlab_exporter['enable'] = false
gitlab_kas['enable'] = false
gitlab_rails['enable'] = false
grafana['enable'] = false
letsencrypt['enable'] = false
node_exporter['enable'] = false
postgres_exporter['enable'] = false
prometheus['enable'] = false
redis_exporter['enable'] = false
redis['enable'] = false

次に、GitLab Mattermostを認可するセクションの適切な手順に従います。最後に、GitLabとのインテグレーションを有効にするには、GitLabサーバーで以下を追加します:

gitlab_rails['mattermost_host'] = "https://mattermost.example.com"

デフォルトでは、GitLab MattermostはすべてのユーザーにGitLabでのサインアップを要求し、メールによるアカウント作成オプションを無効にします。MattermostのGitLab SSOに関するドキュメントを参照してください。

手動でGitLab MattermostをGitLabで再認可する

GitLab Mattermostを再認可する

GitLab Mattermostを再認可するには、まず既存の認可を失効する必要があります。これは、GitLabの設定 > アプリケーションエリアで行うことができます。次に、以下のセクションの手順に従って認可を完了します。

GitLab Mattermostを認可する

GitLabで設定 > アプリケーションエリアに移動します。新しいアプリケーションを作成し、Redirect URIには以下を使用します（HTTPSを使用する場合はhttpをhttpsに置き換えます）:

http://mattermost.example.com/signup/gitlab/complete
http://mattermost.example.com/login/gitlab/complete

信用済みと非公開の設定を選択していることを確認してください。スコープでread_userを選択します。次に、アプリケーションを保存を選択します。

アプリケーションが作成されると、Application IDとSecretが提供されます。その他に必要な情報は、GitLabインスタンスのURLです。GitLab Mattermostを実行しているサーバーに戻り、以前に受け取った値を使用して、/etc/gitlab/gitlab.rb設定ファイルを次のように編集します:

mattermost['gitlab_enable'] = true
mattermost['gitlab_id'] = "12345656"
mattermost['gitlab_secret'] = "123456789"
mattermost['gitlab_scope'] = "read_user"
mattermost['gitlab_auth_endpoint'] = "http://gitlab.example.com/oauth/authorize"
mattermost['gitlab_token_endpoint'] = "http://gitlab.example.com/oauth/token"
mattermost['gitlab_user_api_endpoint'] = "http://gitlab.example.com/api/v4/user"

変更を保存し、sudo gitlab-ctl reconfigureを実行します。エラーがなければ、GitLabとGitLab Mattermostは正しく設定されているはずです。

ユーザーおよびグループの数値識別子を指定する

Linuxパッケージはユーザーとグループmattermostを作成します。これらのユーザーの数値識別子は、/etc/gitlab/gitlab.rbで次のように指定できます:

mattermost['uid'] = 1234
mattermost['gid'] = 1234

変更を適用するにはsudo gitlab-ctl reconfigureを実行します。

カスタム環境変数を設定する

必要に応じて、/etc/gitlab/gitlab.rbを介してMattermostで使用されるカスタム環境変数を設定できます。これは、Mattermostサーバーが企業インターネットプロキシの背後で運用されている場合に役立ちます。/etc/gitlab/gitlab.rbで、mattermost['env']にハッシュ値を指定します。例:

mattermost['env'] = {"HTTP_PROXY" => "my_proxy", "HTTPS_PROXY" => "my_proxy", "NO_PROXY" => "my_no_proxy"}

変更を適用するにはsudo gitlab-ctl reconfigureを実行します。

PostgreSQLのバンドルされたデータベースに接続する

バンドルされたPostgreSQLデータベースに接続する必要があり、デフォルトのLinuxパッケージデータベース設定を使用している場合は、PostgreSQLスーパーユーザーとして接続できます:

sudo gitlab-psql -d mattermost_production

GitLab Mattermostをバックアップする

GitLab Mattermostは、通常のLinuxパッケージバックアップ Rakeタスクには含まれません。

一般的なMattermostのバックアップと災害リカバリーに関するドキュメントは、バックアップが必要なもののガイドとして使用できます。

バンドルされたPostgreSQLデータベースをバックアップする

バンドルされたPostgreSQLデータベースをバックアップする必要があり、デフォルトのLinuxパッケージデータベース設定を使用している場合は、このコマンドを使用してバックアップできます:

sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz

dataディレクトリとconfig.jsonをバックアップする

Mattermostにはdataディレクトリとconfig.jsonファイルがあり、これらもバックアップする必要があります:

sudo tar -zcvf mattermost_data_$(date --rfc-3339=date).gz -C /var/opt/gitlab/mattermost data config.json

GitLab Mattermostを復元する

以前にGitLab Mattermostのバックアップを作成した場合は、以下のコマンドを実行して復元することができます:

# Stop Mattermost so we don't have any open database connections
sudo gitlab-ctl stop mattermost

# Drop the Mattermost database
sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# Create the Mattermost database
sudo -u gitlab-psql /opt/gitlab/embedded/bin/createdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# Perform the database restore
# Replace /tmp/mattermost_dbdump_2021-08-05.sql.gz with your backup
sudo -u mattermost sh -c "zcat /tmp/mattermost_dbdump_2021-08-05.sql.gz | /opt/gitlab/embedded/bin/psql -U gitlab_mattermost -h /var/opt/gitlab/postgresql -p 5432 mattermost_production"

# Restore the data directory and config.json
# Replace /tmp/mattermost_data_2021-08-09.gz with your backup
sudo tar -xzvf /tmp/mattermost_data_2021-08-09.gz -C /var/opt/gitlab/mattermost

# Fix permissions if required
sudo chown -R mattermost:mattermost /var/opt/gitlab/mattermost/data
sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json

# Start Mattermost
sudo gitlab-ctl start mattermost

Mattermostコマンドラインツール（CLI）

mmctlは、Mattermostサーバー用のCLIツールで、ローカルにインストールされ、Mattermost APIを使用しますが、リモートでも使用できます。ローカル接続用にMattermostを設定するか、ローカルログイン認証情報を使用して管理者として認証する必要があります（GitLab SSOを介さない）。実行可能ファイルは/opt/gitlab/embedded/bin/mmctlにあります。

ローカル接続を介してmmctlを使用する

ローカル接続の場合、mmctlバイナリとMattermostは同じサーバーから実行する必要があります。ローカルソケットを有効にするには:

1. /var/opt/gitlab/mattermost/config.jsonを編集し、以下の行を追加します:

   {
       "ServiceSettings": {
          ...
           "EnableLocalMode": true,
           "LocalModeSocketLocation": "/var/tmp/mattermost_local.socket",
           ...
       }
   }

2. Mattermostを再起動します:

   sudo gitlab-ctl restart mattermost

その後、sudo /opt/gitlab/embedded/bin/mmctl --localを使用してMattermostインスタンスでmmctlコマンドを実行できます。

例えば、ユーザーのリストを表示するには:

$ sudo /opt/gitlab/embedded/bin/mmctl --local user list

13dzo5bmg7fu8rdox347hbfxde: appsbot (appsbot@localhost)
tbnkwjdug3dejcoddboo4yuomr: boards (boards@localhost)
wd3g5zpepjgbfjgpdjaas7yj6a: feedbackbot (feedbackbot@localhost)
8d3zzgpurp85zgf1q88pef73eo: playbooks (playbooks@localhost)
There are 4 users on local instance

リモート接続を介してmmctlを使用する

リモート接続またはソケットが使用できないローカル接続の場合は、SSO以外のユーザーを作成し、そのユーザーに管理者権限を付与します。これらの認証情報は、mmctlを認証するために使用できます:

$ /opt/gitlab/embedded/bin/mmctl auth login http://mattermost.example.com

Connection name: test
Username: local-user
Password:
 credentials for "test": "local-user@http://mattermost.example.com" stored

GitLabとMattermostのインテグレーションを設定する

プラグインを使用して、Mattermostでイシュー、マージリクエスト、プルリクエストに関する通知、およびマージリクエストのレビュー、未読メッセージ、タスクの割り当てに関する個人の通知を受信するように登録できます。イシューの作成や表示、またはデプロイをトリガーするなどのアクションを実行するためにスラッシュコマンドを使用したい場合は、GitLab Mattermostスラッシュコマンドを使用してください。

このプラグインとスラッシュコマンドは、組み合わせて使用することも、個別に使用することもできます。

メール通知

GitLab Mattermost用のSMTPを設定する

これらの設定は、システム管理者によってMattermostシステムコンソールを通じて設定されます。System Consoleの環境 > SMTPタブで、SMTPプロバイダーから提供されたSMTP認証情報、または127.0.0.1とポート25を入力してsendmailを使用できます。必要な特定の設定に関する詳細は、Mattermostのドキュメントで確認できます。

これらの設定は/var/opt/gitlab/mattermost/config.jsonでも設定できます。

メールバッチ処理

この機能を有効にすると、ユーザーはメール通知を受信する頻度を制御できます。

Mattermost System Consoleで、環境 > SMTPタブに移動し、Enable Email Batching設定をtrueに設定することで、メールバッチ処理を有効にできます。

この設定は/var/opt/gitlab/mattermost/config.jsonでも設定できます。

GitLab Mattermostのアップグレード

GitLab Mattermostは、通常のLinuxパッケージの更新プロセスを通じてアップグレードできます。以前のGitLabバージョンをアップグレードする場合、Mattermostの設定がGitLabの外部で変更されていない場合にのみ、更新プロセスを使用できます。つまり、Mattermost config.jsonファイルへの変更が、直接または変更をconfig.jsonに保存するMattermost System Consoleを介して行われていないことを意味します。

gitlab.rbを使用してMattermostを設定した場合のみ、Linuxパッケージを使用してGitLabをアップグレードし、その後gitlab-ctl reconfigureを実行してGitLab Mattermostを最新バージョンにアップグレードできます。

そうでない場合は、2つのオプションがあります:

1. config.jsonに対して行われた変更でgitlab.rbを更新します。config.jsonのすべての設定がgitlab.rbで利用できるわけではないため、いくつかのパラメータを追加する必要があるかもしれません。完了すると、LinuxパッケージはGitLab Mattermostをあるバージョンから次のバージョンにアップグレードできるようになります。
2. Linuxパッケージによって制御されるディレクトリの外部にMattermostを移行することで、独立して管理およびアップグレードできるようにします。Mattermost移行ガイドに従って、Mattermostの設定とデータをLinuxパッケージから独立した別のディレクトリまたはサーバーに移動してください。

アップグレードに関する通知と古いバージョンに関する特別な考慮事項の完全なリストについては、Mattermostのドキュメントを参照してください。

Linuxパッケージに同梱されているGitLab Mattermostのバージョンとエディション（非推奨）

以下の表は、GitLab 15.0以降のMattermostバージョンの変更点を示しています:

LinuxパッケージにはMattermost Team Editionがバンドルされており、これはFreeのオープンソースエディションであり、商用機能は含まれていません。Mattermost Enterprise Editionにアップグレードするには、Mattermostのアップグレードに関するドキュメントを参照してください。

OAuth 2.0シーケンス図

以下の画像は、GitLabがMattermostのOAuth 2.0プロバイダーとして機能する方法を示すシーケンス図です。これをインテグレーションの動作に関するエラーのトラブルシューティングを行うために使用できます:

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
accTitle: GitLab as OAuth 2.0 provider
accDescr: Sequence of actions that happen when a user authenticates to GitLab through Mattermost.

    User->>Mattermost: GET https://mm.domain.com
    Note over Mattermost, GitLab: Obtain access code
    Mattermost->>GitLab: GET https://gitlab.domain.com/oauth/authorize
    Note over User, GitLab: GitLab user signs in (if necessary)
    Note over GitLab: GitLab verifies client_id matches an OAuth application
    GitLab->>User: GitLab asks user to authorize Mattermost OAuth app
    User->>GitLab: User selects 'Allow'
    Note over GitLab: GitLab verifies redirect_uri matches list of valid URLs
    GitLab->>User: 302 redirect: https://mm.domain.com/signup/gitlab/complete
    User->>Mattermost: GET https://mm.domain.com/signup/gitlab/complete
    Note over Mattermost, GitLab: Exchange access code for access token
    Mattermost->>GitLab: POST http://gitlab.domain.com/oauth/token
    GitLab->>GitLab: Doorkeeper::TokensController#35;create
    GitLab->>Mattermost: Access token
    Note over Mattermost, GitLab: Mattermost looks up GitLab user
    Mattermost->>GitLab: GET https://gitlab.domain.com/api/v4/user
    GitLab->>Mattermost: User details
    Mattermost->>User: Mattermost/GitLab user ready

コミュニティサポートリソース

あなたのGitLab Mattermostデプロイに関するヘルプとサポートについては、以下を参照してください:

• Mattermostイシューのトラブルシューティング。
• Mattermostフォーラム。