################ チュートリアル ################ 概要 ==== このチュートリアルでは、Sora に組み込まれている開発者ツールを動かして、ひととおり使ってみるところまでを説明します。 チュートリアルの注意点 ============================== .. caution:: 繋がらないという問い合わせのほとんどは UDP のポート開放忘れです。必ずポートを開放してください。 - このチュートリアルでは、リバースプロキシとしての nginx や HTTPS の知識を必要とします - Sora は TCP と UDP の両方を利用します - TCP はデフォルトであれば 3000 番と 5000 番を利用します - UDP はデフォルトであればエフェメラルポートの範囲を利用します - Sora の開発者ツールは Sora に組み込まれているものを利用して下さい - Sora の開発者ツールは HTTPS 非対応のため、nginx をリバースプロキシとして利用して、TLS 終端を行ってから Sora に繋ぐ必要があります - Sora のシグナリングは WebSocket over TLS 非対応のため、nginx をリバースプロキシとして利用して、 TLS 終端を行い Sora のシグナリングへ繋ぐ必要があります Sora の展開 =================== tar.gz で圧縮されていますので、展開して下さい。 .. code-block:: console $ tar xfz sora---.tar.gz 設定ファイル ============ 設定ファイルは Sora を展開した ``sora-/etc/sora.conf`` にあります。まずは開発者ツールを動作させるまでの最低限の設定を行います。 ``#`` はコメントになっている部分ですので、設定する項目がコメントになっている場合は ``#`` を削除して設定項目を有効にしてください。 #. ライセンスファイルの指定 - ライセンスファイルを etc/ において、cp コマンドを利用して ``license.json`` に変更して下さい。 #. 開発者ツールの有効化 - Sora には簡単に検証してもらうための開発者ツールを組み込んでいます。 ``devtools`` 項目の ``#`` を削除して設定を有効にし、 加えて、設定値に true を指定して Sora に組み込まれている開発者ツールを有効化してください。 .. code-block:: ini ## ライセンスファイルを指定してください ## この設定はオプションで、デフォルトは "etc/license.json" です # license_file = etc/license.json ## 開発者ツールを有効にするかどうかを指定してください ## オプションでデフォルト false です devtools = true 他の設定はここでは不要です。 起動 ==== 設定が終わったらサーバーを起動します。 :: $ sora-/bin/sora daemon 停止 ---- 以下で停止できます。 :: $ sora-/bin/sora stop シグナリングへの HTTPS の適用 ============================= **HTTPS (WebSocket over TLS を含む) の適用は必ず行ってください。HTTPS への接続以外はサポート対象外となります** ブラウザで WebRTC の機能の一つである getUserMedia を利用する場合は HTTPS が必須となります。 ただし、Sora 自体は HTTPS 非対応のため、Sora の前段にリバースプロキシとして nginx を設置して TLS 終端を行ってください。 nginx の location ディレクティブの設定については :doc:`nginx ` を参考にして設定をお願いします。 .. attention:: nginx の設定に関する質問については Sora のサポート範囲外となりますのでご了承下さい。 証明書については `Let's Encrypt - Free SSL/TLS Certificates `_ の利用をおすすめします。 .. attention:: Let's Encrypt に関する質問については Sora のサポート範囲外となりますのでご了承下さい。 リバースプロキシとしての nginx の役割:: // 開発者ツールの静的ファイルの場合 クライアント -> -> nginx -> -> Sora // シグナリングの場合 クライアント -> -> nginx -> -> Sora 開発者ツールを利用してみる ===================================== Sora に組み込まれている開発者ツールの使い方を説明します。 開発者ツールでは Sora の持っている一通りの配信機能を試すことができます。 ブラウザで ``https://<設定したドメイン>/`` にアクセスして以下のような画面が表示されれば成功です。 .. image:: https://i.gyazo.com/a2ec768a1c51493ac8a71497c3e95603.png 開発者ツールが動作するブラウザ一覧 ----------------------------------------------- 以下の最新のブラウザで動作します。 - Google Chrome - Mozilla Firefox - Apple Safari - Microsoft Edge ただし一部の機能は特定のブラウザでのみ動作します。 動作確認 --------------------- .. warning:: ハウリングする可能性があります。 ビデオ会議システムなどで利用されるような双方向での配信機能です。 受信だけ、送信だけでの利用もできます。 ``マルチストリーム送受信`` を開き ``connect`` を押して、 その後、別のブラウザやタブで同じ URL を開いて、 ``connect`` を押して下さい。 .. image:: https://i.gyazo.com/b79590e2493ec49fed8f9dc0e0470a26.png 追加でタブを開いて ``connect`` していけば参加者を増やせます。 開発ツールでは気軽にいろいろな設定を試せるようになっています。触ってみてください。 次のステップ ============ :doc:`本番稼働に向けて ` で Sora の本番稼働向けの設定を行ってください。 Sora はいろいろな機能を持っていますので、一通りドキュメントをご確認下さい。 ドキュメントで不明な点がありましたら、お気軽にお問い合わせください。 .. note:: :doc:`アプリケーション連携チュートリアル` は Sora を利用したアプリケーション連携用のチュートリアルを Python にて説明しています。 トラブルシューティング ====================== タイムアウトが起きてつながらない場合 ------------------------------------ .. important:: OS の設定やファイアウォールで UDP の通信ができない場合は接続に失敗します。 Sora が利用する UDP のポートの範囲は通常 32768 から 60999 です。この範囲の通信を許可にしてみてください。 それでもうまく繫がらない場合 ---------------------------- サーバーの IPv4 アドレスを ``ipv4_address`` に指定して、 ``ipv6`` を ``false`` にしてみてください。 .. code-block:: ini ## ライセンスファイルを指定してください ## この設定はオプションで、デフォルトは "etc/license.json" です # license_file = etc/license.json ## サーバーで利用する IPv4 アドレスを指定してください ## 指定が無い場合は、自動で見つけたアドレスを利用します ipv4_address = 192.0.2.10 ## 開発者ツールを有効にするかどうかを指定してください ## オプションでデフォルト false です devtools = true .. note:: Amazon EC2 インスタンス等のようなパブリック IP アドレスとプライベート IP アドレスが異なる環境では ブラウザからアクセスできる IP アドレス（パブリック IP アドレス）を ipv4_address に設定してください。 よくある問題 ------------ ここでは利用しているドメインを仮に ``example.com`` としています。 - ``https://example.com/`` にアクセスできない - nginx の設定が間違っている可能性があります。nginx の設定を見直して下さい - ``https://example.com/`` にアクセスしても 404 になる - Sora の組み込みの開発者ツールが有効になっていない可能性があります - ``sora.conf`` の設定で開発者ツールが有効になっているか確認して下さい - ``http://example.com:5000/`` にアクセスして開発者ツールが有効になっているかを確認して下さい - Sora が利用するポートを他のプロセスが利用していないかを確認してください - Sora が利用したいポートを他のプロセスが既に利用しているために、Sora が起動していない可能性があります それでも繋がらない場合 ----------------------------- **お問い合わせ前に以下を確認してください** - チュートリアル以外のことはやっていないかどうかを確認して下さい - **ファイアウォールの設定をすべて無効にして確認してください** - IPv6 アドレスを無効にして確認してください - Sora では基本的にロードバランサーを利用することはできませんので、ロードバランサーなしで確認してください すべてを確認しても繋がらない場合はお問い合わせください。 その際に以下の情報を **必ず** お送りください。 - どんな環境でチュートリアルを実行しているか - Sora のバージョン - Sora の設定ファイルである ``sora.conf`` - log ディレクトリ以下すべてを tar.gz にて圧縮してお送りください - 容量が 1 メガバイトを超える場合は事前にご連絡ください。アップローダーをご提供します - 繋がらなかった開発者ツール - たとえば ``sendonly`` など - 繋がらなかったブラウザを利用している OS とバージョン - たとえば ``macOS Big Sur 11.4`` や ``Windows 10 2004`` など - 繋がらなかったブラウザの種類とバージョン - たとえば ``Chrome 91.0.4472.77`` など それ以外にも可能な限り、こちらがサポートをするために必要そうな情報をお送りください。