Docker Composeを使用してSynapse Matrix Serverをインストールする方法

具体例：小規模なボランティアグループが、独自の Matrix ホームサーバーを に設置したいとしますchat.example.com。これは架空の設定であり、テスト済みのサーバーのレポートではありません。同じ手順を実際のドメインにも適用できますが、Matrix サーバー名は慎重に選択してください。Synapse はこれをユーザー ID に使用するため、後から変更することはできません。

このガイドでは、Docker Compose を使用して Synapse サービスと PostgreSQL データベースを作成します。Synapse の公式 Docker イメージはデフォルトで SQLite から開始されますが、これは使い捨ての試用には便利です。Synapse の Docker ドキュメントでは、本番環境では PostgreSQL を推奨しています。そのため、この例ではまず Synapse の構成を生成し、データベース設定を PostgreSQL に変更してから、両方のコンテナを起動します。公式イメージは ですghcr.io/element-hq/synapse。手順とイメージの詳細は、2026 年 10 月 6 日の最新の公式ドキュメントに基づいて確認されています。イメージのタグとサポートされているソフトウェアのバージョンは変更される可能性があるため、長期展開の前にリンク先のドキュメントを確認してください。

インストール前に必要なもの

• Docker EngineとDocker ComposeプラグインがインストールされたLinuxサーバー、またはDockerをサポートするその他のホストが必要です。Composeが利用可能かどうかは、コマンドで確認してくださいdocker compose version。ご使用のオペレーティングシステムに応じたDockerの公式インストール手順に従ってください。
• サーバーを指すドメインまたはサブドメイン。この例では、chat.example.comは Synapse サーバー名なので、ローカルユーザー ID は のようになります@alex:chat.example.com。設定を生成する前に、これを管理しているドメインに置き換えてください。
• リバースプロキシ、またはパブリック利用のための別のTLS終端方法。SynapseのデフォルトのHTTPリスナーは、8008インターネットに公開されるHTTPSエンドポイントではありません。このComposeの例では、そのポートをホストのループバックインターフェースにバインドすることで、同じマシン上のリバースプロキシからアクセスできるようにします。

の名前はSYNAPSE_SERVER_NAME、必ずしもすべてのクライアント接続の URL になるわけではありません。@alex:example.comからクライアントにサービスを提供する際に、 のような短い ID を使用したい場合はchat.example.com、ドメインと検出設定を意図的に行う必要があります。アカウントを作成する前に、この点を決定してください。

1. 作業ディレクトリとデータベースパスワードを作成する

サーバー上に、Composeプロジェクトと永続的なSynapseファイル用のディレクトリを作成します。

mkdir -p ~/matrix-synapse/data
cd ~/matrix-synapse

.envDocker Compose が読み込むローカルファイルを作成します。パスワードマネージャーまたはローカルの安全な生成ツールを使用して長いランダムなパスワードを生成し、それを の後に配置しますPOSTGRES_PASSWORD=。この例では、後で YAML の引用符の問題を回避するために、文字と数字を使用します。このファイルを公開リポジトリにコミットせず、権限を制限します。

umask 077
nano .env

ファイルには、例えば のような 1 行のみが含まれている必要がありますPOSTGRES_PASSWORD=replace-with-a-long-random-value。このテキストはプレースホルダーであり、再利用するパスワードではありません。パスワードは、手順 3 の Synapse データベース構成のために保管しておいてください。

2. SynapseおよびPostgreSQLサービスを定義する

compose.yamlプロジェクトディレクトリ内に以下を作成します。

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: chat.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"

volumes:
  postgres_data:

chat.example.com選択した最終サーバー名に置き換えてください。PostgreSQL のヘルスチェックにより、Compose は Synapse の起動前にデータベースが準備完了と報告するまで待機します。名前付きデータベースボリュームとホストマウントディレクトリは、コンテナの置き換え後も保持されます。コンテナを削除するだけでは、これらは消去されません。データベースボリュームを意図的に削除したい場合を除き、./dataこの操作は避けてください。docker compose down -v

この例では:latest、最初のプルを簡素化するために、特定の Synapse リリース タグまたはイメージ ダイジェストを選択して記録し、リリース ノートを確認した後、計画されたアップグレード プロセスを通じて更新します。変更可能なlatestタグが同じバージョンを維持するとは限らないことに注意してください。

3. Synapseの設定を生成し、PostgreSQLを指定します。

公式イメージを構成生成モードで一度実行します。Composeは./dataにマウントされるため/data、生成された構成と署名キーはホスト上に残ります。

docker compose run --rm synapse generate

このコマンドは、Compose 環境のサーバー名と匿名統計情報の設定を使用します。Synapse は署名キーも作成します。このキーはデータディレクトリに保管し、保護されたバックアップにも含めてください。通常のコンテナ更新時に再生成したり破棄したりしないでください。

生成されたセクションを開きdata/homeserver.yaml、database:以下の設定に置き換えてください。.envプレースホルダーの代わりに、正確なパスワードを使用してください。

database:
  name: psycopg2
  args:
    user: synapse
    password: 'replace-with-the-same-random-value'
    dbname: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

周囲の YAML インデントを維持し、アクティブなセクションが 1 つだけであることを確認してくださいdatabase:。ホスト名postgresは Compose サービス名であり、コンテナは共有デフォルト ネットワーク上でこれを解決できます。設定では、Synapse のドキュメントに記載されている PostgreSQL エンジン名、psycopg2および、を含むデータベース引数名を使用しますdbname。

この簡単な例では、データベースのパスワードはSynapseの設定ファイルと保護された.envファイルの両方に含まれています。両方のファイルを機密情報として扱い、ホストからのアクセスを制限し、展開環境で必要であれば専用の機密情報管理方法を使用してください。実際のパスワードをログ、スクリーンショット、サポートリクエストに貼り付けないでください。

4. Docker ComposeでSynapseを起動する

スタックをバックグラウンドで起動する：

docker compose up -d

サービスの状態を確認し、起動ログを読み取ってください。

docker compose ps
docker compose logs --tail=100 synapse

Synapse が初回起動時のデータベース設定を完了するまでお待ちください。コンテナが実行中ということは、そのプロセスがアクティブになっていることを意味します。先に進む前に、ログを確認して設定、データベース、または権限のエラーがないか確認してください。ログの到着を監視するには、[ログ] を使用し、[ログ]docker compose logs -f synapseキーを押すと、Ctrl+Cコンテナを停止せずにログの監視を停止できます。

5. ローカルAPIを確認し、パブリックアクセスを設定する

Dockerホストから、SynapseのクライアントAPIバージョンのエンドポイントにリクエストを送信します。

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

正常な応答は、サポートされているMatrixクライアントAPIのバージョンを記述したJSONです。これは、HTTPリスナーがローカルで応答していることを確認するものであり、DNS、HTTPS、またはフェデレーションが正しく構成されていることを証明するものではありません。

ホストのリバースプロキシを設定して、選択したドメインへのリクエストを転送しhttp://127.0.0.1:8008、有効なTLS証明書を取得します。プロキシ処理時には、Matrixリクエストパスを保持します。その後、公開エンドポイントを確認します。

curl -fsS https://chat.example.com/_matrix/client/versions

サンプルホスト名を実際のホスト名に置き換えてください。クライアントが別のユーザーIDドメインからホームサーバーを検出する必要がある場合は、その設計に適したMatrixの既知の検出レコードを公開してください。フェデレーションには、適切なパブリックルーティングとDNSも必要です。ローカルポートを開放する8008だけでは、完全なパブリック展開は実現できません。サービスを公開する前に、Synapseのリバースプロキシとフェデレーションに関するガイダンスを確認してください。

6. 最初の管理者アカウントを作成する

Synapse はデフォルトで公開登録を無効にしています。プライベートサーバーの場合は、このデフォルト設定のままにして、コマンドラインからアカウントを作成してください。一時的に に強力なregistration_shared_secret値を追加しdata/homeserver.yaml、Synapse を再起動して変更を反映させます。

docker compose restart synapse

コンテナ内で登録ツールを実行します。ユーザー名とパスワードの入力を求められます。設定により--admin最初の管理者が作成されます。

docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

アカウント作成後、registration_shared_secret設定から削除し、Synapseを再起動してください。シークレットを設定したままにしておくと、シークレットを入手したユーザーは誰でも登録インターフェースから標準アカウントまたは管理者アカウントを登録できてしまいます。リバースプロキシから提供されるサーバーURLを使用して、カスタムホームサーバーをサポートするMatrixクライアントからサインインしてください。

バックアップ、アップグレード、および一般的な修正

• 適切なデータをバックアップしてください。PostgreSQLのデータを停止するか、定期的にスナップショットを作成し、構成、メディア、署名キーを含めてバックアップしてください./data。のコピーcompose.yamlだけではホームサーバーを復元できません。バックアップはサーバーとは別の場所に保存し、定期的に読み取り可能であることを確認してください。
• Synapse は に書き込みできません/data。のホスト所有権とパーミッションを確認してください./data。公式イメージのランタイム ユーザーには、設定の読み取りとデータの書き込み権限が必要です。ディレクトリを誰でも書き込み可能にするのではなく、ホスト所有権を慎重に調整してください。
• データベース接続に失敗しました。データベース構成で が使用されていることhost: postgres、パスワードが と一致していること.env、 がdocker compose logs postgres正常なデータベースを示していることを確認してください。Compose のdepends_on準備状況は起動時の競合状態を軽減しますが、誤った認証情報を修復するものではありません。
• ローカルAPIは動作しますが、クライアントが接続できません。選択したドメイン構成のDNSレコード、TLS証明書、リバースプロキシのアップストリーム、および検出レコードを確認してください。ループバック専用のポートマッピングは、同一ホストプロキシの場合に意図的なものです。別のコンテナ内のプロキシには、共有Dockerネットワークと異なるルーティング設計が必要です。
• アップグレードするには、docker compose pullまずバックアップを作成し、Synapse のリリース ノートを確認し、ピン留めされたイメージ タグを更新してから、 を実行してサービスを再作成しますdocker compose up -d。データ ディレクトリ、データベース ボリューム、サーバー名、署名キーはそのままにしておきます。

例示されているボランティアグループの設定では、ローカルバージョンのエンドポイントが応答し、プロキシ経由でHTTPSエンドポイントが応答し、管理者が意図したMatrix IDドメインを使用してサインインできる場合にのみ、インストールが完了します。これらのチェックは、最初のデプロイメントが正常に動作していることを示す実用的な指標であり、より広範なコミュニティを招待する前に、セキュリティ、バックアップ、フェデレーション、および運用要件を確認することの代わりとなるものではありません。

公式資料

• Synapseのインストール手順とサーバー名に関するガイダンス
• Synapse公式DockerイメージのREADME
• シナプス構成リファレンス
• シナプス逆代理誘導
• Docker Engineのインストール
• Docker Composeの起動順序とヘルスチェック