GitLab Mattermost

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

前提要件

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

はじめに

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

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

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

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

2. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

3. https://mattermost.example.comでGitLab Mattermostにアクセスでき、GitLabに接続する認可されていることを確認します。GitLabでMattermostを認可すると、ユーザーはGitLabをSSOプロバイダーとして使用できます。

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

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

Mattermostの設定

Mattermostは、Mattermostシステムコンソールを使用して設定できます。Mattermostの設定と、それらを設定できる場所の広範なリストは、Mattermostドキュメントにあります。

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

1. /var/opt/gitlab/mattermost/config.jsonを介してMattermostの設定を直接編集します。
2. gitlab.rbのmattermost['env']設定を変更して、Mattermostの実行に使用される環境変数を指定します。この方法で設定された設定は、システムコンソールから無効になり、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の実行

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

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でのGitLab Mattermostの手動による（再）認可

GitLab Mattermostの再認可

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

GitLab Mattermostの認可

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

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

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

アプリケーションを作成すると、Application IDとSecretが提供されます。必要なもう1つの情報は、GitLabインスタンスのURIです。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 APIを使用するMattermostサーバー用のCLIツールですが、リモートで使用することもできます。ローカル接続用に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のEnvironment > SMTPタブで、SMTPプロバイダーから提供されたSMTP認証情報、または127.0.0.1およびポート25を入力すると、sendmailを使用できます。必要な特定の設定に関する詳細情報は、Mattermostドキュメントにあります。

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

メールバッチ処理

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

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

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

GitLab Mattermostのアップグレード

GitLab Mattermostは、通常のLinuxパッケージ更新プロセスを通じてアップグレードできます。以前のバージョンのGitLabをアップグレードする場合、Mattermostの設定設定がGitLabの外部で変更されていない場合にのみ、更新プロセスを使用できます。つまり、Mattermostのconfig.jsonファイルには、直接的にも、MattermostのSystem Consoleを介してconfig.jsonに変更を保存する方法でも、一切変更が加えられていません。

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

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

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

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

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

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

Linuxパッケージには、無料のオープンソースエディションであり、商用機能は含まれていないMattermost Team Editionがバンドルされています。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フォーラム。