Nginxでカスタム要素Webクライアントをホストする方法

Matrixホームサーバーを公開できるものの、ユーザーに公開されているElementウェブサイトを使わせたくない場合は、独自のNginxサーバー上にElement Webを静的サイトとしてホストできます。ファイルはNginxによって配信され、Matrixホームサーバーはアカウント、ルーム、メッセージ、フェデレーションを処理する独立したサービスとして残ります。この区別は重要です。WebクライアントをSynapseに向けるだけでは、Synapseのインストールや設定は行われません。

この初心者向けチュートリアルでは、chat.example.orgElementサイトには、matrix.example.orgホームサーバーにはを使用します。両方とも実際のホスト名に置き換えてください。コマンドはDebianまたはUbuntuスタイルのLinuxサーバーを想定しています。パッケージパスとサービス名はディストリビューションによって異なります。

始める前に必要なもの

サーバーファイルを変更する前に、以下の項目を準備しておいてください。

• Webクライアント用のドメインまたはサブドメインで、DNSがNginxホストを指しているもの。
• HTTPS URL でアクセスできる動作中の Matrix ホームサーバー (例: https://matrix.example.org)。
• Nginxがインストールされており、サイト設定の編集とサービスの再起動を行う権限が付与されています。
• ウェブクライアントのホスト名に対応する有効なTLS証明書が必要です。ユーザーはHTTPS経由でログインする必要があります。これは、ブラウザが認証情報とセッショントークンをサイトに送信するためです。
• 公式プロジェクトから提供される、最新の安定版Element Webリリースアーカイブです。開発用ソフトウェアを実行する目的でない限り、開発ビルドを公開サービスにデプロイすることは避けてください。

Element Web は静的ファイルで構成されるブラウザアプリケーションです。プロジェクトの現在のインストール手順では、リリースをダウンロードし、サーバー上で解凍し、Web サーバーを生成されたファイルに向けて設定することを推奨していますconfig.json。Debian および Ubuntu では、プロジェクトは Web ルートを に/usr/share/element-web、設定を にインストールする Element Web パッケージも提供しています/etc/element-web/config.json。以下の手順ではリリース アーカイブを使用するため、専用のドキュメント ルートを選択できます。

バージョンを選択する前に、 Element Webのインストール手順と公式リリースを確認してください。Debianパッケージを使用する場合は、Nginxをパッケージのドキュメントに記載されているWebルートに指定し、パッケージ設定ファイルを編集してください。以下のアーカイブパスは変更せずにコピーしないでください。

1. Element Web ファイルをダウンロードしてインストールします。

ドキュメントルートとは、訪問者がサイトを開いたときにNginxが表示するディレクトリのことです。専用のルートを作成し、そこにリリースを展開してください。ダウンロードした実際のアーカイブ名とディレクトリ名に置き換えてください。リリースバージョンは時間とともに変更される場合があります。

sudo install -d -o root -g www-data -m 0755 /var/www/element
tar -xzf element-vX.Y.Z.tar.gz
ls

アーカイブは通常、バージョン付きディレクトリに展開されます。そのディレクトリの内容（index.htmlJavaScriptバンドル、フォント、画像、サンプル設定など）をNginxのドキュメントルートにコピーします。たとえば、展開されたディレクトリの名前が次のようになっている場合element-vX.Y.Z：

sudo cp -a element-vX.Y.Z/. /var/www/element/
sudo find /var/www/element -type d -exec chmod 755 {} \;
sudo find /var/www/element -type f -exec chmod 644 {} \;
ls -l /var/www/element/index.html /var/www/element/config.sample.json

コピーコマンドでは、実際のバージョン付きディレクトリ名を使用してください。Nginxはこれらのファイルへの読み取りアクセス権を必要としますが、書き込みアクセス権は必要ありません。アップグレード前に現在のリリースと設定のコピーを保持しておけば、デプロイが失敗した場合に復元できます。

2. クライアントがホームサーバーを使用するように設定します。

Element を起動するには、ホームサーバーのアドレスが必要です。サンプルファイルをコピーして、デフォルトの Matrix クライアント API URL を設定してください。この例では、Synapse には次のアドレスからアクセスできますhttps://matrix.example.org。

cd /var/www/element
sudo cp config.sample.json config.json
sudoedit /var/www/element/config.json

編集して/var/www/element/config.json、エントリを含む有効な JSON オブジェクトが含まれていることを確認してくださいdefault_server_config。例:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.org"
    }
  }
}

これは、Elementがデフォルトで提供するサーバーを設定します。Synapseアカウントを作成したり、すべてのユーザーにこのサーバーを選択するよう強制したりするものではありません。現在のElement設定ガイドでは、default_server_configホームサーバー接続情報を提供する推奨方法としてこの方法が記載されています。以前のdefault_hs_urlオプションは非推奨です。ユーザーを1つのサーバーに制限する場合は、Elementに別のdisable_custom_urls設定項目が記載されています。有効にする前に、それがコミュニティに適しているかどうかを判断してください。

ドキュメントに記載されているElementオプションを使用して、デフォルトテーマや特定のブランディング詳細など、限定的なカスタマイズを設定することもできます。これは完全なホワイトラベル置換とは異なります。このプロジェクトでは、無制限のリブランディングではなく、選択されたカスタマイズ設定について説明しています。インストールするリリースでサポートされているオプションについては、構成ガイドを確認してください。確認せずに別のバージョンから設定をコピーしないでください。

Element Web の最新の設定リファレンスを参照してください。developドキュメントはプロジェクトの進化に伴って変更される可能性があるため、展開するリリースに合わせてオプションキーを確認してください。

3. Webクライアント用にNginxサイトを追加する

クライアントホスト名のサイト構成を作成します。この例では、chat.example.org表示されている証明書パスに既に証明書が存在することを前提としています。証明書の発行方法は、ホスト、DNSプロバイダ、および既存のTLS設定によって異なるため、ここでは説明しません。

server {
    listen 80;
    server_name chat.example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name chat.example.org;

    ssl_certificate     /etc/letsencrypt/live/chat.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.example.org/privkey.pem;

    root /var/www/element;
    index index.html;

    # Revalidate the client files after deployments.
    add_header Cache-Control "no-cache" always;

    # Element Web hosting security headers.
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Content-Security-Policy "frame-ancestors 'self'" always;

    location / {
        try_files $uri $uri/ =404;
    }
}

ブロックをディストリビューションに適したサイトファイルに配置し、必要に応じてそのサイトを有効にし、グローバルな Nginx 設定が標準mime.typesファイルをロードしていることを確認します。Nginx は MIME タイプを使用して、レスポンスが JavaScript、CSS、JSON、またはその他の種類のファイルであるかどうかをブラウザrootに伝えます。 は、 を直接含むディレクトリを指している必要がありますindex.html。

上記の no-cache ヘッダーは、デプロイメントに適したシンプルなベースラインです。ブラウザは、古いクライアントコードを使い続けるのではなく、更新後にファイルを再検証します。Element のホスティングに関する注意事項では、特に、、、、およびをキャッシュしないことが求められており、/config.*.jsonサイトルートの再検証が推奨されています。後で大きな静的アセットに対してより長期間のキャッシュを追加する場合は、キャッシュルールを作成する前に、これらのパスを最新の状態に保ち、リリースのアセット命名規則を確認してください。/i18n/version/index.html

ElementのWeb READMEでは、セルフホスト型サイト向けにアンチフレーミングヘッダーとコンテンツタイプヘッダーの使用を推奨しています。既にコンテンツセキュリティポリシー（CSP）を設定している場合は、frame-ancestors 'self'2つ目のCSPヘッダーを送信するのではなく、既存のポリシーに追加してください。制限の厳しいCSPは必要なアプリケーションスクリプトをブロックする可能性があるため、デプロイ済みのクライアントでテストせずに広範なポリシーをコピーしないでください。

、、および静的ファイルの処理の動作については、Element Web のホスティングおよびキャッシュの要件とNginx の公式コアモジュールのドキュメントを参照してください。roottry_files

4. 設定を検証し、Nginxをリロードします。

設定を適用する前にテストしてください。Nginxでエラーが発生した場合は、報告されたファイルと行を修正する間、現在のプロセスを実行したままにしてください。破損した設定を再読み込みしないでください。

sudo nginx -t
sudo systemctl reload nginx
curl -I https://chat.example.org/
curl -I https://chat.example.org/config.json

テストでは、構文が正常であり、構成テストが成功したことが報告されるはずです。HTTPSリクエストは目的のホストに到達し、正常な応答を返すはずです。構成ファイル自体が有効なJSONであることも確認してください。

curl -fsS https://chat.example.org/config.json | python3 -m json.tool

次に、https://chat.example.orgブラウザで開きます。Elementのログイン画面またはウェルカム画面が表示され、Matrixホームサーバーがデフォルトとして設定されているはずです。テストアカウントを試用し、ブラウザの開発者ツールでネットワークリクエストの失敗を確認し、ログイン、ルームリストの読み込み、メッセージ送信が正常に動作することを確認してください。ページの読み込みが成功したとしても、NginxがWebクライアントにサービスを提供したことは証明されるだけで、ホームサーバーにアクセス可能であることや正しく設定されていることを証明するものではありません。

5. 必要に応じてホームサーバーの検出機能を動作させる

example.orgマトリックスIDで、 Synapse APIがにあるサーバー名（例：）を使用している場合matrix.example.org、マトリックスクライアントは、クライアント既知の応答を使用してhttps://example.org/.well-known/matrix/clientAPI URLを検出できます。このオプションの検出エンドポイントは、マトリックスIDのドメインに属し、Elementウェブクライアントのホスト名に自動的に属するわけではありません。最小限の応答は次のようになります。

{
  "m.homeserver": {
    "base_url": "https://matrix.example.org"
  }
}

ブラウザベースのクライアントに必要な CORS ヘッダーを含む JSON 形式で配信してください。Synapse のインストール ドキュメントには Nginx の例が記載されており、public_baseurlクライアントが Synapse にアクセスするために使用する URL と一致させる必要があるとされています。Element の設定で正しいホームサーバーの URL を直接設定し、ユーザーがそのクライアント固有の設定を入力する場合、この基本的な設定では検出は不要かもしれません。

Synapseのクライアントに関する周知のガイダンスに従い、ユーザーIDの検出が機能することを期待する前に、最終的なURLをテストしてくださいcurl。セキュリティ上の分離のため、Synapseのセキュリティガイダンスでは、可能な限り、ホームサーバーを機密性の高いWebアプリケーションとは異なる登録済みドメインでホストすることを推奨しています。サブドメインを分けることである程度の保護は得られますが、登録済みドメインを分けることがより確実な推奨事項です。

避けるべき一般的な問題

• Nginxで403エラーが表示される場合：ファイルとディレクトリの読み取り権限を確認し、Nginxワーカーが各親ディレクトリを走査できることを確認してください。
• ページが空白になるか、JavaScriptで404エラーが返される場合は、展開されたリリースディレクトリの内容が正しく指定されていることを確認してくださいroot。上下のディレクトリが正しく指定されていない可能性があります。Nginxのエラーログとアクセスログを確認してください。
• 要素は読み込まれるが、接続またはログインできない場合は、base_urlホームサーバーのHTTPS証明書、ファイアウォールアクセス、およびSynapse側のCORSまたはリバースプロキシの設定を確認してくださいconfig.json。CORSはブラウザによって強制されるため、Nginx静的サイトはホームサーバーのオリジンポリシーを単独で修正することはできません。
• 最近の変更が反映されない場合は、キャッシュヘッダーの/、/index.html、/config.json、/version、を確認し/i18n、デプロイされたファイルが置き換えられたことを確認した後、ブラウザを強制的に更新してください。
• ログインページはHTTPでのみ動作します。TLS設定を完了し、ユーザーをサインインに招待する前にHTTPをHTTPSにリダイレクトしてください。

最終展開チェックリスト

• Element Webのホスト名はNginxサーバーに解決され、有効なHTTPS証明書を持っています。
• ドキュメントルートには、リリースのindex.html、アセット、および有効なが含まれていますconfig.json。
• JSONファイルは、m.homeserver.base_urlお使いのMatrixホームサーバーに接続可能なHTTPSクライアントAPIを指し示しています。
• sudo nginx -tパスが通過し、Nginxはホームページとconfig.jsonHTTPS経由の両方を提供します。
• ブラウザは、証明書エラー、CORSエラー、またはファイル欠落エラーが発生することなく、ログインしてホームサーバーに実際のリクエストを送信できます。
• キャッシュルールにより、アップグレード後に新しいクライアントファイルと設定が有効になります。

これらのチェックが完了すると、カスタムのElement WebクライアントはNginxによって提供され、Matrixホームサーバーと通信できるようになります。Element Webは常に最新の状態に保ち、以前のリリースと設定のロールバックコピーを保持し、アップグレード後には必ずホームサーバーのURLとブラウザのネットワークリクエストを再確認してください。

公式資料

• Element Web インストールに関するドキュメント
• Element Web 設定ガイド
• 要素ウェブホスティング、セキュリティヘッダー、およびキャッシュに関するガイダンス
• Synapseクライアントの既知のURIに関するドキュメント
• シナプスセキュリティガイダンス
• Nginxコアモジュールのドキュメント